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

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:

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-<name>.md

To validate the draft before running it:

loom plan verify doc/plans/PLAN-<name>.md

3. Run Loom

Once your plan is written:

loom init doc/plans/PLAN-<name>.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

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 <plan-path> 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

loom init <plan-path> [--clean]
loom run [--manual] [--max-parallel N] [--foreground] [--watch] [--no-merge]
loom status [--live] [--compact] [--verbose]
loom stop
loom resume <stage-id>
loom check <stage-id> [--suggest]
loom diagnose <stage-id>
loom pressure <plan-path> [--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-<plan>.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

loom plan verify <plan-path> [--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

loom stage complete <stage-id> [--session <id>] [--no-verify] [--force-unsafe --assume-merged]
loom stage block <stage-id> <reason>
loom stage reset <stage-id> [--hard] [--kill-session]
loom stage waiting <stage-id>
loom stage resume <stage-id>
loom stage hold <stage-id>
loom stage release <stage-id>
loom stage skip <stage-id> [--reason <text>]
loom stage retry <stage-id> [--force] [--context <message>]
loom stage merge [stage-id] [--resolved]
loom stage verify <stage-id> [--no-reload] [--dry-run]
loom stage human-review <stage-id> [--approve|--force-complete|--reject <reason>]
loom stage dispute-criteria <stage-id> <reason>

Stage Outputs

loom stage output set <stage-id> <key> <value> [--description <text>]
loom stage output get <stage-id> <key>
loom stage output list <stage-id>
loom stage output remove <stage-id> <key>

Knowledge / Memory

loom knowledge show [file]
loom knowledge update <file> <content>
loom knowledge init
loom knowledge list
loom knowledge check [--min-coverage N] [--src-path <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 <name>] [--skip-map] [--quick]             # --quick uses headless `claude -p` (see Billing note)

loom memory note <text> [--stage <id>]
loom memory decision <text> [--context <why>] [--stage <id>]
loom memory change <text> [--stage <id>]
loom memory question <text> [--stage <id>]
loom memory query <search> [--stage <id>]
loom memory list [--stage <id>] [--entry-type <type>]
loom memory show [--stage <id>] [--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

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 <session-id...> | --stage <stage-id>
loom worktree list
loom worktree remove <stage-id>
loom graph
loom map [--deep] [--focus <area>] [--overwrite]
loom repair [--fix]
loom clean [--all|--worktrees|--sessions|--state]
loom self-update
loom completions [<shell>] [--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):

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.

# 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

Stage Type Behavior

• knowledge: knowledge/bootstrap work, different verification expectations
• standard: implementation stage;