Loom: Git coordination layer for parallel AI coding agents

Loom is a coordination layer sitting on top of Git, designed to solve a concrete workflow problem: when multiple AI coding agents (like Claude Code sessions) work on the same repository in parallel, they overwrite each other's changes and discover the collision only at merge or CI time, when fixing it is expensive.

The mechanism is straightforward. When an agent begins work, it calls `loom lease` with a goal and a file scope (e.g., "move auth to the new session model" with scope `src/auth/**`). Loom assigns the agent its own git worktree and returns a working directory. If a second agent's lease overlaps the first one's scope, Loom reports the overlap immediately (a "toe-step" warning) in the same MCP response, giving the agent a chance to renegotiate — for instance, by declaring a disjoint scope instead. If both agents proceed, they still work in separate worktrees, so nothing is clobbered. When the first agent finishes, it runs `loom stitch` (a checkpoint operation that records deletes as tombstones) and `loom propose` (which verifies in a scratch copy and asks for human consent). When the second agent proposes, Loom checks whether the shared mainline has moved; if it has, the proposal is refused with the message "fabric moved under you — rebase," and the agent rebases its thread and re-proposes. The key insight: the collision is surfaced by name (which file moved) when handling it costs one tool call, not after both agents' token budgets are spent.

The system integrates with Claude Code and other MCP clients. An agent's typical flow is: `loom_status` (check who is working on what), `loom_lease` (declare intent), edit in the returned worktree, `loom_stitch` every few edits (checkpoints and heartbeats the lease), `loom_propose` (verify and request consent), and on conflicts, `loom_rebase` (reconcile in the worktree) and re-propose. Dead threads are marked as orphans and are claimable via `loom adopt`, with goal, criteria, and checkpoint intact — schedulable work instead of mystery dangling branches.

For multi-machine collaboration, Loom syncs through hidden git refs (`refs/loom/*`) with no server or daemon. Both users run `loom init --verify <test-cmd>` and `loom sync --remote origin`, then work exactly as on a single machine: lease, edit, stitch, propose, sync. Edits live in per-thread worktrees and the shared line (the "fabric") advances only through a compare-and-swap ref push that refuses if the ref moved under you. The body stresses: "Neither of you can overwrite the other, because edits live in per-thread worktrees and the shared line only advances through a compare-and-swap ref push that refuses when it moved under you."

Loom ships with three configurable git history modes: `squash` (default, one commit per completed goal), `stitches` (every checkpoint as a commit on a per-thread branch, plus a merge commit), and `both` (both preserved). Nothing is ever pushed; the bridge is a local projection only. Deletions are first-class — a deleted file lands as a deletion and delete-vs-edit collisions refuse like any other conflict. Large files over 8 MiB are skipped loudly (named in the stitch result) unless the cap is raised or a `.loomignore` file is used. The verify gate runs in a scratch copy with a hard timeout and never lands red code. The tool is available for installation via `cargo install --path .` and is already tested (45 tests shipped for single-machine use), with support for a few people on shared remotes and design sketched for many peers over gossip.

The core problem Loom solves is a direct consequence of running multiple agents on a shared codebase: git reports collisions only at merge or CI time, after both agents have spent tokens on potentially conflicting work. When two agents simultaneously rewrite overlapping files with different intentions, the last one to land silently erases the first one's work, and debugging the resulting breakage falls to a third agent with no context — expensive token-burning that could have been prevented with early detection.

Loom's design inverts this timeline. By requiring agents to declare intent upfront (a lease with a goal and file globs), collisions become knowable before any editing happens. The system warns the second agent immediately, letting it either self-partition to non-overlapping scope or explicitly choose to proceed. Crucially, leases warn but never block — an agent is never stopped by Loom. The only hard gate is at landing: isolation via worktrees ensures nothing is overwritten, and a consent gate (human or approval queue) ensures only green code reaches the main branch. The body frames this as a fundamental shift from expensive after-the-fact reconciliation to early renegotiation and rare rebases.

The system is built on git primitives — worktrees, refs, and compare-and-swap ref pushes — and ships with a sync mechanism that uses hidden refs for multi-machine coordination without a daemon or central server. The trade-off is clear: Loom adds ceremony (leases, explicit coordination) but only where it matters: fleets of fast agents or humans working at agent speed. The body explicitly notes it is not for two careful humans working slowly, nor for N agents racing the same task (which needs a judge/tournament harness).

No comments yet. Be the first to share your thoughts!