--- slug: "claude-loom" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/cosmix/claude-loom@main/README.md" repo: "https://github.com/cosmix/claude-loom" source_file: "README.md" branch: "main" --- # Loom Loom is an agent orchestration system for Claude Code. It coordinates AI agent sessions across git worktrees, enabling parallel task execution with crash recovery, context handoffs, and structured verification. ## What Loom Solves - Context exhaustion in long agent sessions - Lost execution state when sessions crash or end - Manual handoff/restart overhead - Weak coordination across multi-stage work ## Key Capabilities - Persistent orchestration state in `.work/` - Git worktree isolation for parallel stage execution - Stage-aware signals and recovery flows - Goal-backward verification (`artifacts`, `wiring`, `wiring_tests`, `dead_code_check`) - Plan-level and stage-level sandbox controls - Optional agent teams guidance in stage signals ## Platform Support - Linux: primary development and full CI test runs - macOS: supported for build/terminal integration, CI does build-only verification - Windows: not supported (WSL may work but is best-effort) ## Quick Start Loom is under active development and not yet published to GitHub Releases. You need to build locally with the Rust toolchain installed. ### 1. Install Loom ```bash git clone https://github.com/cosmix/loom.git cd loom bash ./dev-install.sh ``` `dev-install.sh` builds the release binary (`cargo build --release`) and runs `install.sh`, which installs `loom-*` prefixed agents and skills (non-destructively, preserving user customizations), hooks, and configuration into `~/.claude/` and the CLI binary to `~/.local/bin/loom`. Orchestration rules are written directly to `~/.claude/CLAUDE.md` (existing file is backed up). ### 2. Write a Plan Plans are how loom knows what to build. Open Claude Code in your target project and use the `/loom-plan-writer` skill to create one: ```bash cd /path/to/project claude # start Claude Code CLI ``` Inside the Claude Code session: 1. Enter plan mode (`/plan`) 2. Load the plan-writing skill by typing `/loom-plan-writer` 3. Describe what you want to build and discuss with Claude 4. Claude will write the plan to `doc/plans/PLAN-.md` To validate the draft before running it: ```bash loom plan verify doc/plans/PLAN-.md ``` ### 3. Run Loom Once your plan is written: ```bash loom init doc/plans/PLAN-.md loom run loom status --live loom stop ``` `loom init` parses the plan, creates stage state, and installs/configures project hook wiring automatically. For an existing repo that is missing Claude Code hook setup, run `loom repair --fix`. ### What Gets Installed | Location | Contents | | ---------------------------- | ---------------------------------------------------- | | `~/.claude/agents/loom-*.md` | Specialized subagents (per-item, non-destructive) | | `~/.claude/skills/loom-*/` | Domain knowledge modules (per-item, non-destructive) | | `~/.claude/commands/*.md` | Loom slash commands (`/pressure`, `/address`, `/distill`) | | `~/.claude/hooks/loom/` | Session lifecycle hooks | | `~/.claude/CLAUDE.md` | Orchestration rules | | `~/.codex/skills/pressure/` | Codex pressure-testing skill (`$pressure`) | | `~/.local/bin/loom` | Loom CLI | > The `~/.claude/commands/` and `~/.codex/skills/pressure/` entries are installed only by the local `install.sh` (cloned repo); the `curl | bash` install does not ship them yet. ## Core Workflow 1. Open Claude Code, enter plan mode (`/plan`), and use `/loom-plan-writer` to write a plan to `doc/plans/`. 2. Run `loom init ` to parse metadata and create stage state. 3. Run `loom run` to start daemon + orchestrator. 4. Track progress with `loom status --live`. 5. Recover, verify, merge, or retry stages as needed. ## CLI Reference ### Primary Commands ```bash loom init [--clean] loom run [--manual] [--max-parallel N] [--foreground] [--watch] [--no-merge] loom status [--live] [--compact] [--verbose] loom stop loom resume loom check [--suggest] loom diagnose loom pressure [--rounds N] [--dry-run] ``` `loom pressure` hardens a plan before you run it by combining two external agents over `--rounds` rounds (default 2). Each round runs both pressure-tests in parallel: Claude `/pressure` edits the plan in place in the foreground (you watch it live), while Codex `$pressure` writes an independent review next to it (`codex-.md`) in the background (its output is captured to a temp log to keep the terminal clean). Once both finish, Claude `/address` folds the review back in. Claude stays interactive (subscription billing) and auto-closes when done; Codex runs from the repo root. Requires both the `claude` and `codex` CLIs on PATH. `--dry-run` prints the exact commands without spawning anything. ### Plan Commands ```bash loom plan verify [--strict] [--json] [--no-color] ``` `loom plan verify` validates a plan file without touching `.work/` or requiring a git repo. It runs the same fatal validation as `loom init` (schema errors, duplicate IDs, unknown dependencies, path safety) plus advisory warnings (structural issues, missing knowledge-bootstrap stage, sandbox gaps). Exits 0 on success, non-zero on fatal errors; `--strict` promotes warnings to errors. ### Stage Commands ```bash loom stage complete [--session ] [--no-verify] [--force-unsafe --assume-merged] loom stage block loom stage reset [--hard] [--kill-session] loom stage waiting loom stage resume loom stage hold loom stage release loom stage skip [--reason ] loom stage retry [--force] [--context ] loom stage merge [stage-id] [--resolved] loom stage verify [--no-reload] [--dry-run] loom stage human-review [--approve|--force-complete|--reject ] loom stage dispute-criteria ``` ### Stage Outputs ```bash loom stage output set [--description ] loom stage output get loom stage output list loom stage output remove ``` ### Knowledge / Memory ```bash loom knowledge show [file] loom knowledge update loom knowledge init loom knowledge list loom knowledge check [--min-coverage N] [--src-path ] [--quiet] loom knowledge audit [--max-file-lines N] [--max-total-lines N] [--quiet] # Report size/duplicate/promoted-block issues loom knowledge gc [--model NAME] [--dry-run] [--quick] # Spawn Claude to compact (dedupe, summarize, drop stale) loom knowledge bootstrap [--model ] [--skip-map] [--quick] # --quick uses headless `claude -p` (see Billing note) loom memory note [--stage ] loom memory decision [--context ] [--stage ] loom memory change [--stage ] loom memory question [--stage ] loom memory query [--stage ] loom memory list [--stage ] [--entry-type ] loom memory show [--stage ] [--all] ``` `loom knowledge bootstrap` launches a Claude-driven exploration session that populates `doc/loom/knowledge/`. By default it runs a deep `loom map` pass first, then starts Claude with permission to update knowledge files via `loom knowledge update`. ### Other Commands ```bash loom review [--ai-summary] # Generate a code-review doc from stage memories; --ai-summary uses headless `claude -p` (see Billing note) loom sessions list loom sessions kill | --stage loom worktree list loom worktree remove loom graph loom map [--deep] [--focus ] [--overwrite] loom repair [--fix] loom clean [--all|--worktrees|--sessions|--state] loom self-update loom completions [] [--install] [--migrate] ``` ### ⚠️ Billing: headless `claude -p` flags Loom runs every orchestrated stage as a normal **interactive** Claude Code session, which bills against your Claude subscription exactly like launching `claude` yourself. A few **opt-in** flags instead invoke Claude in headless print mode (`claude -p`): | Command | Flag | Behavior without the flag | | -------------------------- | -------------- | --------------------------------------------------------------- | | `loom knowledge bootstrap` | `--quick` | Runs an interactive bootstrap session instead | | `loom knowledge gc` | `--quick` | Runs an interactive compaction session instead | | `loom review` | `--ai-summary` | Uses the plan's first paragraph as the summary (no Claude call) | Headless `claude -p` usage may be billed **separately from (and in addition to) your Claude subscription** as API/extra charges, depending on your account and auth setup. These flags are **off by default** so loom never silently incurs those charges — only pass them when you knowingly accept the headless billing. ## Plan Format Plans live in `doc/plans/` with metadata in fenced YAML between loom markers. ````markdown # PLAN-0001: Feature Name ```yaml loom: version: 1 sandbox: enabled: true stages: - id: implement-api name: Implement API description: Add endpoint + tests working_dir: "." stage_type: standard dependencies: [] acceptance: - "cargo test" - command: "cargo test api_integration::returns_200" stdout_contains: ["test result: ok"] files: - "loom/src/**/*.rs" artifacts: - "loom/src/api/*.rs" wiring: - source: "loom/src/main.rs" pattern: "mod api;" description: "API module registered" execution_mode: team - id: integration-verify name: Integration Verify working_dir: "." stage_type: integration-verify dependencies: ["implement-api"] acceptance: - "cargo test --all-targets" - command: "cargo test api_integration::returns_200" stdout_contains: ["test result: ok"] ``` ```` ### Stage Fields | Field | Required | Notes | | ---------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------- | | `id` | Yes | Stage identifier | | `name` | Yes | Human-readable title | | `working_dir` | Yes | Relative execution directory (`.` allowed) | | `description` | No | Optional summary | | `dependencies` | No | Upstream stage IDs | | `acceptance` | Conditionally required | Shell criteria (strings or extended objects with stdout_contains etc.) | | `setup` | No | Setup commands | | `files` | No | File glob scope | | `stage_type` | No | `standard` (default), `knowledge`, `integration-verify` | | `artifacts` / `wiring` | Conditionally required | Required for `standard` and `integration-verify` (acceptance OR goal-backward) | | `wiring_tests` / `dead_code_check` | No | Extended verification | | `before_stage` | No | Pre-spawn checks (TruthCheck list); stage → Blocked if any fail | | `after_stage` | No | Post-acceptance checks (TruthCheck list); completion fails if any fail | | `code_review` | No | `integration-verify` only: `dimensions` (string list) and `require_all` (bool); rendered as checklist in agent signal | | `context_budget` | No | Context threshold (%) for handoff | | `sandbox` | No | Per-stage sandbox override | | `sandbox.permission_mode` | No | `auto`, `accept-edits`, `bypass-permissions`, `plan`, `default` (resolves: stage > plan > stage-type default) | | `execution_mode` | No | `single` (default) or `team` hint | ### Stage Type Behavior - `knowledge`: knowledge/bootstrap work, different verification expectations - `standard`: implementation stage; must define goal-backward checks - `integration-verify`: final quality gate combining code review and functional verification; must define goal-backward checks. Define `code_review.dimensions` to render a checklist of review dimensions in the agent's signal. - `knowledge-distill`: final stage; curates stage memories into permanent knowledge files ## Verification Model `loom check ` validates outcomes, not just compilation/tests: - `acceptance`: shell criteria (simple strings or extended objects with `stdout_contains`, `exit_code`, etc.) - `artifacts`: real implementation files exist - `wiring`: critical integration links exist - `wiring_tests`: runtime integration checks - `dead_code_check`: detect unused code via command output patterns For `standard` and `integration-verify` stages, acceptance criteria or at least one goal-backward check must be defined. ## Sandbox Configuration Loom supports plan-level defaults plus stage-level overrides. ```yaml loom: version: 1 sandbox: enabled: true auto_allow: true excluded_commands: ["loom"] filesystem: deny_read: - "~/.ssh/**" - "~/.aws/**" - "../../**" - "../.worktrees/**" deny_write: - "../../**" - "doc/loom/knowledge/**" allow_write: - "src/**" network: allowed_domains: ["github.com", "crates.io"] additional_domains: [] allow_local_binding: false allow_unix_sockets: [] ``` Note: knowledge file writes are intentionally protected by sandbox defaults; knowledge updates should be done via `loom knowledge ...` commands. ### Permission Mode All stages default to `auto` (agents auto-accept any action their heuristics deem safe, since loom stages run autonomously with no human to answer prompts; the sandbox deny/allow rules are the safety boundary). Override per-plan or per-stage to tighten control: ```yaml loom: version: 1 sandbox: permission_mode: accept-edits # plan-level override stages: - id: my-stage sandbox: permission_mode: plan # stage-level override (takes precedence) ``` Valid values: `auto` (default), `accept-edits`, `plan`, `default`. `bypass-permissions` is rejected at init time. ### Remote Control Claude Code's `--remote-control` flag lets the loom orchestrator drive spawned Claude sessions programmatically. Loom enables it automatically when prerequisites are met — no configuration required. **Prerequisites (preflight check):** - **Claude version** ≥ 2.1.51 - **Auth**: claude.ai login — `~/.claude/.credentials.json` must be present and none of these env vars may be set: `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, `CLAUDE_CODE_USE_FOUNDRY` The flag exits non-zero when its prerequisites are not met, so loom never passes it blindly. When preflight fails, loom falls back silently to standard mode and prints a one-line advisory at orchestrator startup (e.g. `⚠ Remote Control disabled: `). **Configuration** — the `[remote_control]` section of `.work/config.toml` carries a single switch: ```toml # .work/config.toml [remote_control] mode = "auto" # default: enable whenever preflight passes # mode = "off" # never enable, regardless of preflight ``` Toggling `mode` takes effect on the next session spawn — no daemon restart needed. **Mid-run fallback** — if a session crashes within 15 seconds of spawn while Remote Control is active, loom writes a `.work/remote_control-unsupported` marker, then respawns and omits the flag for the rest of the run. ## Agent Teams (Experimental) Loom enables agent teams in spawned sessions (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) and injects team-usage guidance into stage signals. Use teams when work needs coordination/discussion across agents (multi-dimension review, exploratory analysis). Use subagents for independent, concrete file-level tasks. ## State Layout ```text project/ ├── .work/ │ ├── config.toml │ ├── stages/ │ ├── sessions/ │ ├── signals/ │ └── handoffs/ ├── .worktrees/ └── doc/plans/ ``` ## Shell Completions Loom provides context-aware tab completions for all commands, subcommands, flags, and dynamic values (stage IDs, plan files, session IDs, knowledge files). ### Quick Install ```bash loom completions --install ``` Auto-detects your shell from `$SHELL` and writes completions to the standard location: | Shell | Install Path | | ----- | ------------------------------------------------- | | Bash | `~/.local/share/bash-completion/completions/loom` | | Zsh | `~/.zfunc/_loom` | | Fish | `~/.config/fish/completions/loom.fish` | Follow the printed post-install instructions to activate (e.g., for zsh, ensure `fpath=(~/.zfunc $fpath)` appears before `compinit` in `~/.zshrc`). ### Manual Setup You can also write the completion script to a file yourself: ```bash # bash loom completions bash > ~/.local/share/bash-completion/completions/loom # zsh — ensure ~/.zfunc is in fpath (add before compinit in ~/.zshrc): # fpath=(~/.zfunc $fpath) # autoload -Uz compinit && compinit mkdir -p ~/.zfunc loom completions zsh > ~/.zfunc/_loom # fish loom completions fish > ~/.config/fish/completions/loom.fish ``` ### Migrating from Older Versions Older versions of loom used `clap_complete` and required an `eval` line in your shell RC file that ran a subprocess on every shell startup. The new system writes a static script to disk and only calls `loom` at actual tab-completion time, which means faster shell startup and completions that work even before `loom` is in your `PATH`. To check whether you need to migrate: ```bash loom completions --migrate ``` This scans for two things: 1. **`eval` lines** in RC files (`.bashrc`, `.zshrc`, etc.) like `eval "$(loom completions zsh)"` — these should be removed 2. **Stale completion files** containing old `clap_complete` markers — these need to be regenerated If issues are found, follow the printed instructions. Typically: remove the `eval` line from your RC file, then run `loom completions --install` to write the new file-based completion script. ### What's Completed - Commands and subcommands (`loom stage ` shows all stage subcommands) - Flags (`loom run --` shows available flags) - Stage IDs with smart filtering (`loom stage complete ` shows only executing stages) - Plan files, session IDs, knowledge files (including aliases like `deps`, `tech`) - Model names, trigger types, and more ## License MIT