loom

loom

A harness around the harnesses. loom drives multiple coding-agent CLIs — Claude Code, Codex, GitHub Copilot CLI, opencode, Google Antigravity's agy (Gemini), and others — as long-lived workers behind one Go interface, so a backend (or a human) can hand work to whichever agent fits, keep a session alive across turns, or fan one prompt across several at once.

A weaving harness is literally a loom component, and a loom holds many harnesses at once. That's the idea: each agent CLI is its own harness; loom weaves them.

MIT licensed.

Why

Modern coding agents (Claude Code, agy, Codex, …) are themselves harnesses — they have their own tools and loops. Driving them from a backend usually means one-shot re-spawns that reload context every time. loom gives them a common Session interface with context that persists across turns, plus a panel mode to run several agents on the same task and compare.

The backends are deliberately heterogeneous, because the real CLIs are:

backend	transport	multi-turn	notes
claude	persistent --input-format stream-json over stdin/stdout (NDJSON)	one process, many turns, holds context	the good path — verified (see below)
codex	one-shot codex exec --json per turn (JSONL events on stdout, prompt over stdin)	codex exec resume <thread_id> (fresh process/turn; codex checkpoints every session to disk)	claude-grade parity — verified (codex-cli 0.141.0, 2026-07-02): resume recalls context, tool events stream, interrupt = signal the turn's process (the on-disk session survives → steer via the next Send). Trust ladder maps to codex's native kernel sandbox: --consult → read-only (instruction AND enforcement), --isolate → workspace-write (no docker image needed), skip-permissions → --dangerously-bypass-approvals-and-sandbox. MCP config → translated to per-invocation -c mcp_servers.<name>.… overrides (stdio command/args/env + streamable-HTTP url/http_headers; shape + live tool-call round-trip verified codex-cli 0.144.6, 2026-07-20 — local sessions only, a remote box rides its own config.toml). Remaining claude-only opts (allowed-tools, permission-mode) ride codex config.toml/profiles instead.
local	stateless POST /v1/chat/completions (OpenAI-compat: llama-chip :8090, LM Studio, vLLM)	loom keeps the message history	the simplest backend — no process/stdio; verified (single + multi-turn) against the live rig; free. Makes panel a cloud+local council.
agy	one-shot agy -p per turn	--conversation <id> resume (fresh process/turn)	works (single-turn verified in a live panel, 2026-06-29) — two headless bugs worked around: stdin-EOF hang (feed empty stdin) + stdout-drop (recover the answer from the transcript file)
opencode	one-shot opencode run --format json per turn (JSON events on stdout, prompt as argv)	run -s <sessionID> (fresh process/turn; opencode persists sessions)	verified (opencode-ai 1.17.15, 2026-07-08): resume recalls context, tool events stream, and step_finish reports real USD cost — the only backend that fills Reply.CostUSD. Model via -m provider/model (the opencode-go/zen zoo: glm, kimi, deepseek, qwen…). Skip-permissions → --auto. No native filesystem sandbox — wall it externally when it matters. MCP config → translated to a temp opencode.json handed via OPENCODE_CONFIG (local + remote server forms; live tool-call round-trip verified opencode-ai 1.17.15, 2026-07-20 — local sessions only; headless permission gating may still need --skip-permissions for the tools to run).
copilot	one-shot copilot -p … --output-format json per turn (JSONL on stdout)	--resume <sessionId> (fresh process/turn; the id is stable)	verified (GitHub Copilot CLI 1.0.69, 2026-07-08): resume recalls context, tool events stream, the final result line carries the session id + usage. Trust ladder rides copilot's native permissions: skip-permissions → --allow-all, --isolate → --allow-all-tools with file paths still walled to the workdir (copilot's path verification), consult → directive with unapproved tools failing closed. Real hinge mappings: MCP config → --additional-mcp-config @file, allowed-tools → --allow-tool=…. Always --no-auto-update. NOTE: VS Code's copilot-chat ships its own copilot that can shadow npm's on PATH and lag versions — pin with LOOM_COPILOT_BIN.

MCP + skills across backends (verified 2026-07-20, on-box CLIs)

One --mcp-config (claude-format JSON, {"mcpServers":{…}}) now reaches every backend that can take it, and the OpenAI shim routes by model name (gpt*/codex*/sol/terra/luna → codex, copilot-* → copilot, <backend>:<model> pins, everything else → claude) instead of hardwiring claude:

backend	MCP carrier	skills
claude	--mcp-config <file> natively; remote: the local file is planted on the target (base64 + EXIT-trap temp file) and the flag repointed — the local file is the source of truth (remote+isolate mounts it into the sandbox)	~/.claude/skills/ (ships in the mounted --claude-home) + project .claude/skills/
codex	translated → -c mcp_servers.<name>.… overrides per invocation (mcpbridge.go; live tool-call proven, codex-cli 0.144.6); remote: the same overrides now survive bash -lc — every argv element is quoted (the raw join used to mangle the TOML; UNVERIFIED on a real remote — no codex on the practice box)	$CODEX_HOME/skills/ + project .codex/skills/ + project .agents/skills/ (discovery verified via codex debug prompt-input; does NOT read .claude/skills/)
copilot	--additional-mcp-config @<file> natively (same JSON shape); remote: local file planted on the target, @ repointed (argv-fixture tested; UNVERIFIED on a real remote)	project .claude/skills/ / .github/skills/ / .agents/skills/ + personal ~/.copilot/skills/ / ~/.agents/skills/ (verified via copilot skill list; no per-invocation flag — discovery is directory-driven)
opencode	translated → temp opencode.json via OPENCODE_CONFIG env (mcpbridge.go; live tool-call proven, opencode-ai 1.17.15 — headless permission gating may need --skip-permissions); remote: the translated doc is planted on the target each turn and OPENCODE_CONFIG exported in the same script (argv-fixture tested; UNVERIFIED on a real remote)	native skill tool, on-demand: .opencode/skills/ + .claude/skills/ + ~/.agents/skills/ + ~/.config/opencode/skills/ (verified via opencode debug skill, opencode-ai 1.17.15 — it DOES read Claude-format skills)
agy	not carried (structurally limited, below)	none

Remote MCP, the contract: when --mcp-config names a file that exists locally, that file is the single source of truth — its bytes ride inside the remote script as base64, land in a private /tmp file, and an EXIT trap removes them when the CLI ends. A path with no local file keeps the legacy meaning: it names a file already on the remote box. Either way the servers the config names must resolve on whichever box the agent runs. Live status (2026-07-21, NOCIX): the claude materialization is proven to the exact startup gate — a planted config passes claude's MCP validation (a missing one exits at startup with "MCP config file not found"); a full remote MCP tool call is UNVERIFIED there (the box's claude auth had expired, and loom does not run login flows).

Serve-side skills (loom serve --openai-home-root <root>): a shim seat named <model>#<role> gets its role's skills too. A claude seat already reads them from the mounted role home — author into <root>/<role>-claude-home/skills/. A host-run seat (codex/copilot/opencode) reads from its session workdir instead, so author into <root>/<role>-skills/ and loom mirrors them into <root>/<role>-workdir at open (the exact --skills path). The role workdir now resolves independently of any claude home — a codex seat needs no <role>-claude-home marker. Live-proven 2026-07-21: a real codex seat driven through a scratch serve (model: codex#capcom) read its mirrored .agents/skills/greeter/SKILL.md and returned the planted magic word.

The cross-provider skills lever is a directory, not a protocol — the harnesses split on which they read: .claude/skills/ reaches claude + copilot + opencode; .agents/skills/ reaches codex + copilot + opencode. Neither alone hits all four, but between them every backend is covered. loom automates this with **`--skills

`**: a source folder of `/SKILL.md` skills, mirrored at `Open` into the skill dir the **backend being run** reads — `claude → .claude/skills/`, `codex → .agents/skills/`, `copilot`/`opencode → .claude/skills/` (they read both, so one copy suffices). loom always knows its backend at `Open`, so it writes exactly one place, no redundant copies. Author once, the harness sees it. Local only (a remote box owns its filesystem); a same-named target skill is replaced by the authored source, other skills left untouched.

Why agy is the awkward one: agy has no working stdio/stream-json mode — it's an open, Google-acknowledged gap (antigravity-cli issues #76 stdout-drop, #119 stream-json parity, #31 --acp); --output-format json is currently rejected. The two real workarounds are transcript-scrape (what loom does — the right path on Windows) or a pseudo-TTY wrap (script -qec '…' /dev/null, Unix-only). When agy ships stream-json, the agy backend swaps to the clean path and drops the scrape.

Verified (2026-06-29, Claude Code v2.1.196)

The claude backend's premise is proven on the real path, not assumed:

• Context across turns in one process — turn 1 "remember 42" → turn 2 recalled "42", same session_id. (The LOOM_SMOKE=1 test reproduces this.)
• Cost amortization is real, measured — a cold one-shot pays ~27K cache-creation tokens every spawn ($0.055 for a trivial turn); in a live session, turn 2 cache-READ ~24K (incl. turn 1's context) and created only ~7K. So loom chat's persistent session is materially cheaper than re-spawning per turn.
• Gotcha baked in: --print + --output-format stream-json requires --verbose; the ~27K cold context loads the working dir's CLAUDE.md/MCP/memory, so run loom in the repo you want that context from.

Use

go build -o loom.exe ./cmd/loom

loom run   --agent claude "summarize the files in this dir"      # one-shot
loom run   --agent claude --events "count the .go files"         # + stream tool calls/thinking to stderr
loom run   --agent local  --model gemma-4-12b "..."              # a free local model on llama-chip's :8090
loom chat  --agent claude --dir /path/to/repo                    # multi-turn: one msg per stdin line
loom run   --agent claude --clone https://github.com/org/repo.git "..." # clone into a fresh temp workdir
loom panel  --agents local,claude "is this function correct?"    # cloud+local council: fan + compare
loom review --agents claude,local [--dir R] [--diff HEAD] [files...]   # review a git diff or files
loom duo    --agent claude --critic-agent codex --dir /repo "build X"  # worker builds, critic (read-only) judges each build point
loom run    --agent claude --isolate --dir /path/to/repo "..."   # claude in a docker sandbox (host walled off)
loom run    --agent claude --remote cpuchip@box --dir /repo "..." # claude on another machine over ssh
loom run    --agent claude --remote cpuchip@box --isolate --dir /repo "..." # sandboxed claude ON the remote box
loom run    --agent claude --resume <session-id> "..."           # reattach to a prior session (survives process/pipe death)
loom run    --agent claude --json "..."                          # emit the Reply as one JSON line on stdout (subprocess callers)
loom agents                                                      # list backends

loom review loads a git diff (default: the working-tree diff vs HEAD; --diff HEAD/main...HEAD) or named files, and fans a reviewer prompt across the agent(s) — a one-shot code review, or a cloud+local council. loom found and fixed real bugs in its own code this way (history-poisoning, a data race, and an incomplete <think>-stripper — the orphan </think> case a self-review caught).

--events makes loom observable — the agent's tool calls (→ Glob), tool results, and thinking stream to stderr as they happen, while the final answer comes back on stdout. Backends emit what they can: claude the full stream, local/agy a coarse one.

Duo — worker + critic build loop (loom duo)

loom duo binds two agents to one working directory: a worker that builds and a critic that evaluates the worker's trajectory at every build point, with loom running the loop between them. It's trajectory eval made operational — a second, opposed seat checking the work as it's built, not after.

loom duo --agent claude --model sonnet \
         --critic-agent codex --critic-model gpt-5.6-terra \
         --dir /path/to/repo [--rounds 6] [--json] [--events] \
         "build the thing"

The build point is the turn boundary — loom's per-turn exec model already gives a natural checkpoint after each reply. Each round is worker turn → critic turn → route:

• The worker opens with your trust flags (exactly as run), works in coherent increments, and ends each reply with a build-point report (what it did, what it verified, what's next). When the whole task is done it begins a reply with BUILD COMPLETE.
• The critic opens read-only (--consult) on the same --dir, so it inspects the real tree — files, git diff, the tests — not just the worker's report (where the two disagree, the tree wins). It ends every reply with VERDICT: CONTINUE | REVISE | DONE. Its session is resumed each round, so it accumulates the whole trajectory — that memory is the point.
• loom routes on the verdict: REVISE sends the critic's feedback back into the worker; CONTINUE tells the worker to proceed; DONE ends the loop. BUILD COMPLETE does not end the loop by itself — nothing outranks the check; only a critic DONE (or the --rounds cap) ends it. A garbled verdict fails open (treated as CONTINUE with a warning to stderr) — the loop never wedges on the critic, only on the tree.

The two seats carry opposed mandates — the worker is driven to finish, the critic to distrust the finish — which is exactly why the pair catches the gap between "I built it" and "it works" that a single agent grading its own work cannot. The critic defaults to the worker's backend/model; point it at a different one (--critic-agent/--critic-model) for genuine second-eyes.

--json emits one object: {worker_session, critic_session, rounds:[{verdict, feedback_summary}…], status, text, cost_usd}. Both session ids surface so either seat can be resumed or inspected afterward (loom run --resume <id>, --consult for the critic). --events streams both seats' tool calls to stderr, tagged [worker]/[critic].

Flow — a step DAG with cached resume (loom flow)

loom flow runs a JSON-declared DAG of steps — each one loom session with its own working dir, prompt, dependency edges, and a deterministic oracle (shell cmd in the step's dir; exit 0 = green) — with bounded parallelism and a journal under $LOOM_HOME/flows/<flow-id>/. The killer feature is resume-from-journal: loom flow resume <flow-id> SKIPS every step whose latest record is green (green = cached, served instantly) and re-runs only the red ones, with cached greens satisfying their dependents. A foreman crash costs nothing but the re-issue of the command. Design doc: docs/proposals/loom-flow.md.

loom flow run --skip-permissions my-flow.json     # run the DAG (flags BEFORE the file)
loom flow resume --skip-permissions my-flow       # skip greens, re-run reds

{"flow":"svc-refactor","concurrency":3,"steps":[
  {"id":"brief","prompt":"Write refactor-brief.md …","oracle":"test -s refactor-brief.md"},
  {"id":"build","agent":"codex","dir":"svc","prompt_file":"prompts/build.md","needs":["brief"],
   "oracle":"go build ./... && go test ./..."},
  {"id":"review","needs":["build"],"prompt":"Review; write REVIEW.md","oracle":"test -s REVIEW.md"}]}

Semantics: a failed step marks its transitive dependents dependency_failed (recorded, never silent) while independent branches keep running; --budget gates DISPATCH (in-flight steps finish; refused steps record budget_refused); relative dir/prompt_file resolve against the flow file; exit 0 only when every step is green. Trust/plumbing flags (--isolate --skip-permissions --mcp-config --skills) are flow-wide and per-invocation — re-pass them on resume: the saved copy never carries trust, and the first live smoke showed why you'll notice — without them, a claude step's edits fail closed while the model claims the write happened; the oracle stays red until the flags return.

Live-proven (2026-07-21, haiku): a two-step flow went 1/2 green (the oracle caught the model writing beta - alpha for beta-alpha — the reply claimed success, the tree disagreed, the tree won), then flow resume served step one cached with zero model turns and re-ran only step two to all-green.

Structured output — --output-schema

loom run --output-schema contract.json "..." forces the worker's final answer through a JSON Schema, so a foreman parses a contract instead of regex-mining prose. The schema is appended to the prompt (a model can't hit a contract it never saw), the reply's JSON is extracted tolerantly (whole reply, ```json fences, or the first decodable value in prose), and validated. On failure loom re-prompts once with the violations + the schema; still invalid → non-zero exit with the errors on stderr. With --json, the validated object rides the Reply as a parsed field. Works on send too (not --detach — there's no session at hand to re-prompt).

The validator is a deliberate hand-rolled subset (loom stays zero-dependency): type (incl. integer, multi-type arrays), properties/required (unknown keys allowed), items, enum, minimum/maximum, minLength/maxLength, minItems/maxItems. Anything else ($ref, oneOf, pattern, format, …) is ignored, not rejected — keep contracts inside the subset.

Usage + budget — what a turn cost, and a ceiling on the loop

Every Reply (and every run manifest) now carries a normalized usage block — tokens, USD, and a cost_source marker that keeps the fidelity honest. Each backend reports exactly what its CLI emits (all four shapes live-captured 2026-07-20), never an invented number:

backend	tokens	USD	cost_source
claude	in / out / cache-read / cache-write (per turn)	real (per-turn delta)	real
opencode	in / out(+reasoning) / cache-read / cache-write (per step)	real (summed steps)	real
codex	in (fresh, cached split out) / out / cache-read	none reported	none
copilot	output tokens only + premium_requests (its billing unit)	none reported	none
local	in / out (standard OpenAI usage block)	none reported (locally free)	none
agy	nothing machine-readable	none	none

loom runs sums today per backend under its table (claude 3 run(s) $0.41, codex 2 run(s) 84,120 tokens). cost_source: "estimated" is reserved for a future price-table experiment — nothing sets it today.

--budget <n> (on run, send, chat, duo) is a spend ceiling with one number, two meters: a turn with real USD counts its dollars against the limit; a token-only turn counts its total tokens against the same limit; either meter crossing refuses further turns (the turn in flight always completes). duo ends with status budget_exceeded; chat refuses the next line; on run/send the budget gates the --output-schema retry turn. A backend reporting neither (agy) is invisible to the budget — pair it with --rounds-style caps instead.

Sessions — carry & resume

Two different guarantees, both verified on the real path:

• Carry context across turns (one live process): the claude backend is a single persistent claude -p --input-format stream-json … --verbose process; each turn writes to the same stdin and reads to that turn's result, so claude holds full context. That's loom chat. ✅ (LOOM_SMOKE oracle: turn 1 "remember 42" → turn 2 "42", one process.)
• Resume across a process restart / dropped pipe (--resume <id>): the session persists to disk on whichever box runs claude. loom run/loom chat print the session_id; reopen it later — even from a fresh process on another day — with --resume <id>, and the context is restored. ✅ verified 2026-06-30 by a two-process oracle (process A remembers 73 and exits → a brand-new process B --resume recalls 73) and the CLI end-to-end. This is what makes a remote session durable: a broken ssh pipe doesn't lose the session — loom just reattaches by id.

loom run --agent claude "remember the number 88, reply OK"  # prints: [session <id> — resume: loom run --resume <id> ...]
loom run --agent claude --resume <id> "what number?"         # → 88, from a brand-new process

Under the hood: claude --resume <id> (the real CLI also has --session-id <uuid> to pre-assign an id, --fork-session to branch, -c for most-recent — natural follow-ons).

• Interrupt a turn in flight & steer (Interrupt()): stop the agent while it's working and redirect it, without losing the session. loom writes a stream-json control_request/subtype:interrupt to stdin (the real wire format, probe-verified 2026-06-30 — claude acks with a control_response success, then ends the turn with a result subtype:error_during_execution); the subprocess stays alive, so a following Send steers with full context. ✅ verified by a live oracle: interrupt a running turn (~0s to stop) → Send "reply ALIVE" → ALIVE, context intact. Race-checked (go test -race) on the concurrent read-vs-interrupt path. In the CLI, the first Ctrl-C during a turn interrupts the agent (not loom) — type your next line to steer; a second Ctrl-C at the prompt exits. Programmatically it's the optional loom.Interruptible interface (if it, ok := sess.(loom.Interruptible); ok { it.Interrupt() }).

The session-lifecycle triad is complete on the real path: carry (across turns) · resume (across process death) · interrupt+steer (mid-turn). The only remaining nuance is concurrent mid-turn injection without interrupting (queue-while-working) — undocumented upstream and not needed: interrupt-then-instruct covers the steering case cleanly.

Isolation — the wall (--isolate)

A Claude Code session runs in a real directory with full host access (it has Bash, Read, Write). That's the asset — loom can hand the substrate reach into a repo or corpus. It's also the risk — a full-filesystem agent commanded by a backend could touch the host. --isolate is the wall: it runs claude inside a docker container (docker/Dockerfile.claude → loom-claude) that sees only:

• /work — the repo (--dir), the one host path the agent can read/write, and
• ~/.claude/.credentials.json — the subscription auth, mounted read-only (claude writes its own session state into an ephemeral in-container ~/.claude, gone on --rm — pass --claude-home to persist it and to inject skills/instructions; see Configuring the agent below).

docker build -t loom-claude -f docker/Dockerfile.claude .
loom run --agent claude --isolate --dir /path/to/repo "review this repo"

Verified: the container's / is a stock Linux fs + /work — no host C:\Users, no host system. The agent can't reach anything you didn't hand it. (Honest scope: the container still holds the OAuth token and has network, so it isn't zero-trust — a tighter version would use a scoped/short-lived token or egress limits. But the host filesystem is walled.) agy --isolate is not yet wired (its Antigravity auth is gnarlier). This is the presiding covenant made literal — delegation needs a lawful wall (D&C 121).

Remote (--remote)

The third point on the trust axis: run the agent on another machine over ssh — the same transport-wrapping pattern as --isolate. stream-json flows over the ssh pipe unchanged. This is how a backend (pg-ai-stewards) commands a Claude Code session on a remote box — the substrate's reach, at distance.

loom run --agent claude --remote cpuchip@workchip --dir /home/cpuchip/repo "review this repo"

Verified 2026-06-30: a Windows loom.exe → ssh cpuchip@<box> → a Claude Code agent listing/summarizing a repo on the remote Ubuntu machine, its → Bash tool-events streaming back live (~$0.12/turn). The pipe worked first try; the far-side PATH (below) was the only catch.

The whole trust axis is one transport tree in the claude backend (claudeCmd):

direct                claude …                                                     (full host access)
--isolate             docker run -i … loom-claude claude …                          (host walled)
--remote H            ssh -T H bash -lc 'cd <dir> && claude …'                       (another machine)
--remote H --isolate  ssh -T H bash -lc 'docker run -i … loom-claude claude …'       (sandboxed ON the remote)

--remote --isolate composes the two: a sandboxed claude on the remote box — the exact shape "manage remote claude sessions safely" wants (reach + wall). The docker command runs over ssh, so its volume paths resolve on the remote ($HOME expanded there, --dir is a remote path). Pass --dir to scope the sandbox; without it, it falls back to the remote $HOME.

Requirements: the remote box has claude installed + authed (it uses its own ~/.claude), and your ssh key reaches it. loom runs the remote command in a login shell (bash -lc) so the box's full PATH loads — a plain non-interactive ssh host "claude …" uses a shell that misses nvm / npm-global / ~/.local/bin installs and dies with claude: command not found even when claude works fine in your interactive ssh session there (a real gotcha, hit + fixed 2026-06-30). For --remote --isolate, the remote also needs docker + the loom-claude image (build it there: docker build -t loom-claude -f docker/Dockerfile.claude .). Verify from your own agent-loaded shell — a passphrase-locked key with no agent can't authenticate from an automated context.

--model overrides the model (e.g. --model haiku); --dir sets the agent's cwd.

Configuring the agent — the substrate hinge

For a backend (pg-ai-stewards) to drive claude as a worker — not just ask it a question — loom forwards claude's configuration flags, and under --isolate controls the container's ~/.claude. Two walls, set independently:

• Filesystem wall — --isolate / --remote: where the agent can touch (container / remote / host).
• Capability wall — --mcp-config + --allowed-tools: what it can call.

loom flag	claude flag	for
--mcp-config <file>	--mcp-config	the hinge — wire in an MCP server (e.g. pg-ai-stewards) so the agent reads/writes the substrate back
--allowed-tools <list>	--allowed-tools	scope which tools (incl. MCP) it may call — the capability wall
--permission-mode <mode>	--permission-mode	e.g. acceptEdits, plan
--skip-permissions	--dangerously-skip-permissions	headless autonomy — safe only inside --isolate (the container is the wall)
--system-prompt-file <f>	--append-system-prompt-file	inject instructions
--claude-home <dir>	(mount)	--isolate only — the injection point, below

--claude-home <dir> is the injection point for everything under --isolate. It mounts a host directory as the container's writable ~/.claude, so it carries skills (<dir>/skills/), instructions (<dir>/CLAUDE.md), settings, MCP config — and it persists claude's session state across containers. That last part is what makes resume + isolate work: every docker run is a fresh container, but the session lives in the mounted home, so a later --resume reattaches. Verified 2026-06-30 (remember 55 in one container → recall 55 in a brand-new one, projects//sessions/ written to the home). Without --claude-home, an isolated session's state dies with the container (--rm), so --resume --isolate silently starts fresh.

Config-file paths (--mcp-config, --system-prompt-file) are interpreted on the target — local host, remote box, or (under --isolate) inside the container. So for isolate, put them in --claude-home and pass the container path (e.g. --mcp-config /home/node/.claude/mcp.json).

The substrate pattern: keep a per-work-item --claude-home seeded with the substrate's skills + instructions + the pg-ai-stewards MCP config; mount the repo as --dir; run --isolate --skip-permissions; store loom's session_id on the work-item so a later dispatch resumes by re-mounting the same home. That is loom as the substrate's hands: reach (dir), voice back (MCP hinge), wall (isolate), memory (resume).

Full integration guide — a copy-in contract for a backend driving loom (subprocess model, the two walls, the canonical dispatch, prereqs, council note): docs/pg-ai-stewards-integration.md.

Serve — loom as a service (loom serve) + warm-resident sessions

loom serve runs loom as a websocket service: a client (another loom, a browser) drives sessions over a socket with a token instead of spawning subprocesses/ssh. It's the fourth transport (--connect ws://…), honoring the same Backend/Session/Interruptible interfaces — so run/chat/review work unchanged over the wire. There is no TLS yet: bind a mesh IP (e.g. NetBird 100.x), never 0.0.0.0.

loom serve --token-file ~/.loom/tokens --add-token         # mint a token (first run)
loom serve --listen 100.x.y.z:7777 --token-file ~/.loom/tokens [--idle-ttl 4h]

The warm-resident upgrade (the cheap round). A round — home implements → a remote box verifies over the socket — used to respawn claude and cold-read the whole session every drive (dollars per turn on a big session). Now a session opened under a stable name stays resident and warm; a later open of that name reattaches to the live process instead of respawning. First open cold-reads once; every later drive is a cache-warm reattach.

# reattach-or-open by name, send a turn, leave the resident warm for the next drive:
loom send --connect ws://100.x.y.z:7777 --token T --session verify-loop "verify feat/x @ <sha>"

# a minutes-long turn, detached — returns a turn-id at once; fetch the verdict later:
loom send  --connect … --token T --session verify-loop --detach "build + re-extract + report"   # → 7
loom await --connect … --token T --session verify-loop --turn 7 [--timeout 60]                   # blocks then returns the reply
loom await --connect … --token T --session verify-loop --last-reply                              # most recent turn, id unknown

loom sessions --connect … --token T   # list residents: name, backend, frozen opts, idle, last turn-id

run/chat also take --session <name> over --connect (a warm drive from discrete tool calls). The design guarantees, all hermetically tested (serve_test.go, no live claude / no cost):

• Name-keyed, id-agnostic — keyed on the client-chosen name, never claude's session id (which forks on every cold resume). Two-writer fence: a name that's resident reattaches; a second process is never spawned against one lineage (opens serialize; opts froze at first open — a reattach with conflicting opts reattaches and notes it).
• Per-turn reply ring — the last few replies are buffered by turn-id, so a socket that drops mid-turn loses no verdict: reconnect (open the same name) and await it.
• send --detach / await — a long turn runs without a synchronous client pinned to it.
• Idle TTL — a resident idle past --idle-ttl (default 4h; 0 = never) is downgraded: its process is closed but its evolved lineage id is remembered, so the next open of the name cold-resumes it — one cold-read, never lost data.

An open without a name is unchanged: ephemeral, dropped on disconnect (unless keep_alive).

Pairing & pinned mTLS (wss://) — no CA, no shared secret

loom serve binds a mesh IP over plaintext ws by design (the encryption is the mesh's, e.g. WireGuard). To make loom safe on its own — not just because it's on the mesh — two nodes can pair once and then talk over pinned-certificate mTLS:

# on each box, once — the watch-pairing ceremony:
loom pair --listen 0.0.0.0:9999            # box A waits
loom pair --connect A-host:9999 --name box-a   # box B dials

# both terminals show the SAME six-digit PIN grouped "465 629" and prompt:
#   match on both screens? [y/N]
# tap y on BOTH → each pins the other's key. n or a mismatch → abort (possible MITM).

# thereafter, serve + connect over mTLS instead of a token:
loom serve --tls --listen 0.0.0.0:7777                    # token optional under --tls; the pin is the wall
loom send  --connect wss://A-host:7777 --peer box-a --session iw "…"

The trust model is pinned raw keys (RFC 7250 / the SSH-and-WireGuard shape), not a CA: each node self-generates a persistent keypair + self-signed cert under ~/.loom/identity/; the ~/.loom/pins file maps a peer name → its SPKI fingerprint; verification is "does the peer's cert fingerprint match the pin?" — no certificate authority, no expiry ceremony. Revoke a peer = delete its pin. The pairing uses commit-then-reveal + a Short Authentication String bound to the ECDH shared secret (ZRTP's shape): a man-in-the-middle who substitutes keys makes the two PINs diverge, so the human's tap catches it. Zero external dependencies — Go stdlib crypto only. Plain ws:// + --token is unchanged; wss:// requires --peer <name> (dial a known pin, never trust-on-first-use).

For clients that can't do the two-screen PIN compare (a phone app, an unattended machine, an agent), loom enroll is the one-code alternative: the box shows a short code, the client submits it, and both sides end up mutually pinned just like pairing. And loom serve --tls-listen <addr> runs plain and mTLS at once so live clients migrate one at a time. See docs/enrollment.md for the enroll wire protocol (what the brain-app implements) and the plain→mTLS migration map.

# on the box: open a one-shot enrollment window, read the printed code to the device
loom enroll --serve --listen 100.x.y.z:7779 --name phone
# on the enrolling machine/agent: submit the code, pin the box
loom enroll --connect 100.x.y.z:7779 --code GV56-OSAX --name mybox

Test

go test ./...                 # pure unit tests (parsing, registry) — no money
LOOM_SMOKE=1 go test ./...    # + the live claude multi-turn oracle (spends a little)

Status / roadmap (v0.4)

• ✅ Core Backend/Session interface · claude backend (persistent stream-json) · local backend (OpenAI-HTTP → :8090; verified single + multi-turn against the live rig; cloud+local panel proven) · structured event streaming (SendStream + --events; verified — claude's tool calls/thinking observable, proven on a real tool-using task) · agy backend (experimental) · panel (concurrent council) · loom review (diff/files → fan a review across agents) · CLI · smoke oracle.
• ✅ Dogfooded: loom reviewed its own code and found+fixed real bugs (history-poisoning, a SessionID data race, the orphan-</think> CoT-strip gap).
• ✅ Isolation (--isolate): claude in a docker sandbox (loom-claude), host walled to /work + read-only creds — verified.
• North star: loom = the substrate's agent fabric — a uniform, walled way to summon intelligence; its soul is running agentic harnesses (Claude Code, agy) the substrate can't run itself, safely. Axes: agency (raw model ↔ agent) × trust (local ↔ sandboxed ↔ remote).
• ✅ Remote (--remote): ssh transport live-verified end-to-end (2026-06-30) — a Windows loom.exe drove a Claude Code agent on a remote Ubuntu box, its → Bash tool-events streaming back, ~$0.12/turn. The trust axis is complete on the real path (direct / --isolate / --remote).
• ✅ Resume (--resume <id>): durable sessions — reattach to a prior session across a process restart / dropped pipe (context restored from claude's on-disk session store). Verified 2026-06-30 by a two-process oracle + CLI e2e. The piece that makes a remote session survive a broken pipe.
• ✅ Interrupt + steer (Interrupt() / Ctrl-C): stop a turn in flight and redirect on the live session (stream-json control_request interrupt; probe-verified wire format). Live oracle + -race on the concurrent path. Completes the session-lifecycle triad (carry / resume / interrupt+steer).
• ✅ remote + isolate: sandboxed claude on the remote box (ssh → docker-on-remote, volume paths resolved there via $HOME). Built + unit-tested (the composed argv); live-verify pending the loom-claude image built on the remote. Reach + wall composed — "manage remote sessions safely."
• ✅ The substrate hinge (config surface): --mcp-config (wire the substrate MCP into the agent — reads/writes back), --allowed-tools (capability wall), --skip-permissions (headless, safe in --isolate), --system-prompt-file (instructions), and --claude-home (the container's ~/.claude: skills/instructions/settings + persisted sessions → resume+isolate now works, live-verified). loom can now drive claude as a configured substrate worker, not just a chat.
• ✅ --json output + integration guide: --json emits the Reply as one stdout line (the clean "pull" channel for subprocess callers; events stay on stderr). Full contract in docs/pg-ai-stewards-integration.md — subprocess model, the two walls, exfil channels (bind-mount / MCP / git / stdout), push-vs-pull data flow, the canonical dispatch.
• ✅ Proven by the substrate + non-root image fix (2026-07-01): pg-ai-stewards ran the first real substrate→loom dispatch (pull-only, direct mode: claude read a corpus, wrote findings.md back, clean --json Reply). It surfaced one real bug — the loom-claude image ran claude as root, which Claude Code refuses for --dangerously-skip-permissions. Fixed: the image now runs as non-root node (mounts at /home/node/.claude); isolate + --skip-permissions live-verified. Autonomous isolated headless dispatch is unblocked.
• ✅ Serve + warm-resident (loom serve / --connect): loom as a websocket service (token-gated, mesh-only, no TLS yet). Name-keyed resident sessions reattach to a live warm process instead of respawning + cold-reading (the cheap round); a two-writer fence, a per-turn reply ring (recover a dropped mid-turn verdict), send --detach/await for minutes-long turns, loom sessions, and an idle TTL that downgrades to cold-resumable (lineage remembered, never lost). Hermetically tested (serve_test.go, -race, no live cost); live cheap-warm-round proof is Michael's.
• ★ Next: the first real pg-ai-stewards → loom run --isolate --mcp-config … dispatch (the viability test); tighter sandbox (scoped/short-lived token, egress limits — toward zero-trust); agy --isolate; panel role-routing (doer→critic).
• Backlog: --session-id/--fork-session (pre-assign / branch) surfaced in the CLI; agy --conversation resume in the CLI; a condenser for very long sessions (pattern from OpenHands' LLMSummarizingCondenser); routing/role assignment across the panel.

ACP — researched 2026-06-29, decision: skip for now

ACP (the Agent Client Protocol, JSON-RPC-2.0 over stdio, now folding toward the Linux Foundation A2A standard) is an optional future backend, not a near-term need:

• Claude Code has no native ACP (real-path-confirmed on v2.1.196); it'd require Zed's Node adapter (@agentclientprotocol/claude-agent-acp, renamed from @zed-industries/… — verify the exact name before installing). Our direct stream-json claude backend is dependency-free, single-process, and faster — no reason to route it through ACP.
• Codex has no native ACP either (community adapters only).
• Gemini CLI (gemini, the standalone) had native --acp — but ⚠️ Google EoL'd it for personal accounts on 2026-06-18 (Pro/Ultra/free stopped serving; consolidated into closed-source agy). It survives only for enterprise / API-key. So gemini --acp is a dead path for us — agy is now the only Google terminal agent. The route to a fuller Gemini is not ACP; it's container config-injection for agy (seed its config dir with GEMINI.md/skills/MCP inside an isolated container — the same container-is-the-config-surface trick as --claude-home, generalized). Gate: agy's headless auth in a Linux container (API-key vs OAuth-keyring) — feasibility-probe it before building the loom-agy backend.

Decision: keep the direct CLI backends; an ACP-client backend is only interesting now if Codex ships native ACP (Claude's direct stream-json is faster + dependency-free; gemini --acp is gone). (ACP→A2A is worth watching — same lineage as pg-ai-stewards' A2A engine.)

Related

Built alongside pg-ai-stewards (a substrate that drives Claude Code for code review — loom is the natural home for that long-lived-session logic) and garrison (a local-first coding agent). Reference: OpenHands (All-Hands-AI/OpenHands) for heavier agent-loop patterns.