Loom

Local-first capture and worklog system for exploratory research and AI-mediated work.

Principle: capture first, explain later.

Markdown files on disk are the durable source of truth. AI synthesis is optional, bounded, and non-authoritative.

This repository contains application code only — scripts, docs, prompts, and public examples. Your private Loom workspace (captures, summaries, project pages, registry) lives outside the repo by default.

---

Daily use

The main interaction surface is the Loom capture window — a small native macOS UI (PySide6):

• large text field with placeholder project: unfinished thought
• syntax helpers: idea · decision · reference · reminder (they edit the line; saved text is authoritative)
• state footer: reminders due, optional Open weekly review →

Open capture

Recommended (macOS): assign a global hotkey with Hammerspoon — the repo ships an example that binds ⌥ Space to launch the app. Hammerspoon is launcher-only; it does not own capture UI or logic. Check for hotkey conflicts with other apps on ⌥ Space.

Manual:

export LOOM_WORKSPACE="${HOME}/loom-workspace"   # private data directory (created on first run)
pip install -r requirements.txt
python3 /path/to/loom/scripts/loom_capture_pyside.py

Type one line, Enter to save, Esc to dismiss without saving.

What gets written

Each capture appends a timestamped line to today's file under your workspace:

$LOOM_WORKSPACE/captures/YYYY-MM/YYYY-MM-DD.md

Example line:

- 14:32 [writing] {idea} verification before synthesis

Explicit reminder syntax (project remind monday: message) also creates a companion file under $LOOM_WORKSPACE/reminders/<due-date>/.

No AI runs in the capture path.

---

Other capture paths

Path	Role
Loom capture app (scripts/loom_capture_pyside.py)	Primary — low-friction GUI
Terminal loom (scripts/chatlog.py)	Interactive logging, project onboarding, fuzzy correction
log shell helper (scripts/log.sh)	One-shot CLI capture
scripts/capture.py	Non-interactive save (used by the capture app and automations)
Obsidian	Optional reader/editor — not required for capture

Tkinter prototype (scripts/loom_capture_app.py) remains a fallback if PySide6 is unavailable.

---

Weekly re-entry

Weekly synthesis lives in $LOOM_WORKSPACE/weekly/YYYY/YYYY-Www.md. The capture footer can run missing daily summaries for the current week, regenerate the weekly file, and open it (Obsidian when OBSIDIAN_URI is set, otherwise the system default app).

Terminal alternative:

python3 scripts/daily_summary.py --date YYYY-MM-DD
python3 scripts/weekly_summary.py --date YYYY-MM-DD

AI features are optional. Loom's capture path does not use AI. If you configure a local model, summary scripts can use --ai for daily or weekly synthesis overlays. Model paths are configured through environment variables (LOOM_MODEL_PATH or --model); no model is bundled with Loom. See USER_GUIDE.md for local model setup.

---

Setup

Repo vs workspace: clone this repository anywhere (e.g. ~/src/loom). Set LOOM_WORKSPACE to a separate private directory (default: ~/loom-workspace). Scripts read and write data only under the workspace — not under the code repo.

Your project registry is private. The public repo ships an example registry, but your real config/projects.yml should normally stay untracked.

1. Clone this repository (application code only).
2. Install dependencies: pip install -r requirements.txt
3. Set your workspace: export LOOM_WORKSPACE="${HOME}/loom-workspace" (add to your shell profile).
4. Create your project registry — either copy the example (mkdir -p "$LOOM_WORKSPACE/config" && cp examples/config/projects.yml "$LOOM_WORKSPACE/config/projects.yml") or use prompts/create-project-registry.md with an LLM to interview you and produce a private registry.
5. Optionally copy example project brains: cp -r examples/projects "$LOOM_WORKSPACE/projects" (edit for your work).
6. Optionally install Hammerspoon and merge examples/hammerspoon/init.lua — see docs/hammerspoon.md.
7. Optionally set OBSIDIAN_URI if you want weekly review to open in Obsidian.
8. Optionally set LOOM_MODEL_PATH to a local GGUF file if you use --ai summaries.

Real captures, reminders, and config should not normally be committed to the public repo.

Full setup and usage: USER_GUIDE.md
Current status: STATUS.md
Command shortcuts: CHEATSHEET.md
Pre-publish checklist: docs/release-checklist.md
LLM / agent context: CONTEXT.md

---

Repository layout

scripts/      # capture, summaries, reminders (application code)
docs/         # decisions, experiments, Hammerspoon setup
prompts/      # LLM prompts for vault setup
examples/     # public-safe sample config, captures, reminders, project pages
requirements.txt

Private workspace (outside the repo, at $LOOM_WORKSPACE):

config/projects.yml
captures/
reminders/
daily/
weekly/
logs/
projects/
ideas/

---

What this is not

• not a task manager or scheduling product
• not an autonomous agent framework
• not a cloud sync or vector-database layer
• not dependent on Obsidian, Hammerspoon, or local AI — those are optional integrations
• not a pre-populated private vault — clone and add your own working data

---

Historical note

docs/historical/implementation.md is an early planning document. It predates the standalone Loom capture app and describes exploratory design choices (Raycast, Keyboard Maestro, Obsidian-as-primary) that were not all adopted. For the current system, prefer this README and USER_GUIDE.md.

Deprecated capture mechanisms (Hammerspoon webview overlay, global Return/Escape bindings in Hammerspoon) are documented only in docs/hammerspoon.md under historical/deprecated paths.