Loom

Loom is an agent orchestration system for Claude Code. You write a plan; loom executes it — stages run in parallel across isolated git worktrees, completion is gated by checks loom runs itself rather than by the agent's own account of its work, and what each session learns is captured and distilled into a knowledge base the next session reads first.

What Loom Solves

Autonomous agent work fails in a small number of predictable ways. Loom answers each with a mechanism, not a paragraph of prompt.

Key Capabilities

Deterministic guardrails

The rules that matter are not left to the model. Loom installs 16 Claude Code hooks and a git pre-commit hook that fire regardless of what an agent intends:

• commit-guard.sh blocks a session from ending with uncommitted work or a stage still Executing
• git-add-guard.sh blocks git add -A / git add .; git-pre-commit-hook.sh blocks commits containing .work or .worktrees
• worktree-isolation.sh / worktree-file-guard.sh block cross-worktree writes, reads, and path traversal
• commit-filter.sh blocks subagent git operations (a subagent commit loses the main agent's work) and blocks AI attribution in commit messages
• subagent-verify-guard.sh blocks subagents from running project-wide build/test/lint suites, so verification stays with the one agent that can see the whole tree — with integration-verify stages carved out, and no opt-out environment variable
• pre-compact.sh blocks compaction, writes a handoff, then allows it; session-start.sh re-anchors the resumed agent to its signal file
• plans-path-guard.sh keeps plans in doc/plans/ where loom and git can see them

Subagent detection is a live process-tree ancestry check, not a PPID comparison. See Verification Is the Main Agent's Job.

Verification that outlives the agent's opinion

loom stage complete is not a self-report. Loom executes the stage's acceptance criteria in-process and refuses completion on failure, leaving the stage Executing so the agent must fix and retry. On top of that, goal-backward verification asks whether the outcome exists:

• artifacts — files exist and contain real implementation (stub detection rejects TODO, FIXME, unimplemented!, todo!, pass, NotImplementedError)
• wiring — regex proof that new code is actually referenced: module registered, route mounted, component rendered
• wiring_tests — runtime commands proving the integration behaves
• dead_code_check — command output patterns catching code that exists but is never called
• before_stage / after_stage — pre-spawn and post-acceptance gates; a failed pre-check blocks the stage before a session is even spawned

The escape hatches (--no-verify, --force-unsafe, --assume-merged) require a one-time operator proof bound to the project, stage, action, and exact flag set. The operator supplies the daemon secret only while minting the proof; the target command cannot fetch that credential for its caller or reuse the proof for another action.

Knowledge capture and distillation

Loom treats what agents learn as a first-class artifact with a pipeline, not a scratch file.

1. Capture — during execution, agents record to a per-stage journal: loom memory note (gotchas, mistakes-with-prevention), decision (with rationale), change, question. The journal is injected into the recitation section at the end of the next signal, where model attention is highest.
2. Distill — a knowledge-distill stage runs at the end of a plan, reads every stage memory, and curates it into permanent knowledge — mistakes rewritten as actionable prevention rules, decisions with their rationale, reusable patterns and conventions.
3. Retrieve — the result is a tiered base under doc/loom/knowledge/: a generated INDEX.md, seven tier-1 summaries, and tier-2 topic files. Agents read the index, then the summary for their area, then only the topics they touch — so the base can grow without every session paying to load it.

Knowledge lives in doc/loom/knowledge/; agents write it through loom, and loom knowledge sync rebuilds the derived retrieval artifacts after the tree changes, including the one-time flat-to-hierarchical upgrade. Details: Knowledge System.

Cost control by construction

Loom's savings come from delegation, not downgrade:

• Orchestration is always Opus at xhigh effort. Every stage's main agent plans, decomposes, verifies, and commits — the judgment-heavy work that is worst to economize on.
• Implementation is always delegated, spawned by agent type so the choice is explicit rather than inherited: Fable for major bugs, visual/UI design, and extremely challenging algorithmic design (no agent type pins it — the model override is stated explicitly at spawn); Opus for mainstream architecture and algorithm implementation; Sonnet or Codex GPT-5.6 Terra for common implementation and integration tests; Codex GPT-5.6 Luna for boilerplate, scaffolding, and simple unit tests. The codex tiers are licensed only on stages listing codex in implementers, and additionally require the codex CLI and its plugin to be installed — when either is missing, loom run prints an advisory warning at startup (it never aborts) and terra-/luna-tier work falls back to Sonnet.
• Signals are built for cache reuse. Each signal is a four-section layout with a per-stage-type stable prefix that is byte-identical across sessions, so the large doctrine block is a cache hit rather than a re-read.
• Context budgets prevent compaction, which is the expensive failure: an uncached re-read that costs more and produces worse work.
• Tiered knowledge and a skill index keep the working set small — at most 5 matched skills are injected per stage, out of 61 installed.
• Orchestrated sessions are interactive, billing against your Claude subscription. The handful of headless claude -p paths are opt-in flags, off by default (see the Billing note below).

Per-stage model, reasoning_effort, and ultracode fields let you override any of this explicitly.

Parallel execution and progressive merge

Stages form a dependency DAG; everything independent runs at once, each in its own worktree (.worktrees/<stage-id>, branch loom/<stage-id>). Completed stages merge back progressively under a file lock, and a real conflict spawns a dedicated resolution session rather than stalling the run.

Crash recovery and liveness

All orchestration state is plain files in .work/, so nothing is lost when a process dies. The daemon polls every 5s, tracks PID liveness and per-session heartbeats, flags hung sessions after 300s, and classifies failures across ten types into retryable (exponential backoff) and needs-diagnosis. Tool-call telemetry drives a stuck-session signal when a session's recent calls are overwhelmingly failures. Orphaned sessions are recovered on daemon restart.

Sandboxing and plan hardening

Plan-level defaults and per-stage overrides control filesystem reads/writes, network domains, and permission mode for the agent session, and commands loom runs from your plan get a rebuilt, allowlisted environment so they cannot read ambient credentials (Sandbox Configuration). Before you spend anything, loom plan verify validates a plan with no side effects — running the same sandbox validation that would otherwise only fail at loom init — and loom pressure hardens it through adversarial review rounds run by two different model families.

Human-in-the-loop where it matters

Thirteen stage states make "needs a person" a first-class outcome rather than a hang: WaitingForInput (raised automatically when an agent asks a question), NeedsHumanReview, Blocked, MergeConflict. Operators get loom stage hold/release/skip/retry/human-review, and an agent that believes a criterion is wrong can escalate with loom stage dispute-criteria instead of quietly weakening it.

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)
• Headless (SSH, no terminal emulator): supported via the tmux backend — see Terminal Backends

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 Workf