Watch the shared checkout
Open quilt ui for the full dashboard or use quilt status in the terminal. Both show who owns each working-tree change.
docs · start here
Everything you need to run Quilt.
Move from one shared checkout to traceable, per-agent commits. Follow the setup path once, then use the reference whenever the work gets busy.
- Node.js 20+
- Git 2.18+
- macOS or Linux
Install the CLI, wire the repo, and verify that capture is flowing.
install and wire
$ npm install -g @quilt-dev/cli
$ cd your-repo
$ quilt setup
$ quilt doctorquilt setup detects the tools installed on your machine and wires what they need: repo-local capture hooks, the shared MCP server, coordination guidance in CLAUDE.md and any existing AGENTS.md, Cursor config when present, and user-global Codex hooks when Codex is installed. It is idempotent, and --dry-run previews the changes.
Setup lists any generated config that Git neither tracks nor ignores. Commit the repo-local files to share the wiring with every checkout, or run quilt setup --gitignore to keep newly untracked config local. The .quilt/ sidecar always stays local and gitignored.
Give shell-driven agents a stable actor
four terminals, one repo
$ QUILT_ACTOR=auth-agent claude # terminal 1
$ QUILT_ACTOR=api-agent claude # terminal 2
$ QUILT_ACTOR=tests-agent claude # terminal 3
$ QUILT_ACTOR=docs-agent claude # terminal 4Native hooks and separate MCP connections can auto-name sessions for captured edits. Actor-sensitive shell commands such as claim, preview --mine, and commit --mine still need a CLI identity. Launching each agent with QUILT_ACTOR makes that identity explicit and keeps the examples below runnable. You can also use quilt start or the global --as option.
Claude Code: MCP claim tools appear after a restart and a one-time /mcp approval. Native hooks still capture supported Edit and Write operations. Before shell commands or code generation, place a whole-file or directory claim. quilt watch adds live detection, but it cannot identify several raw writers on its own.
See the work, reserve risky boundaries, and commit only the lines that belong together.
Claim before broad or raw edits
With explicit actor ids, wired edit tools deny a different actor at a claim boundary. Claims also bind uncaptured file changes to the right actor. Auto-derived callers can adopt a sole live claim holder, so use explicit ids when strict separation matters.
Preview, then commit your patch
quilt preview --mine shows the exact patch. quilt commit --mine creates an ordinary Git commit while every other actor's work stays in the tree.
Verify durable provenance
quilt provenance HEAD reads the authorship record stored with the commit, even from a fresh clone with no local Quilt state.
the loop
$ quilt ui
$ quilt claim src/auth/ --intent "fix session refresh"
$ quilt preview --mine
$ quilt commit --mine -m "fix auth redirect"
✓ Committed 1 file (b41e7a2)
$ quilt provenance HEADRaw tools remain advisory. A shell command can bypass denial-before-write. Claim the whole file or directory first so Quilt can bind the result to you. quilt watch adds live collision detection, but it does not distinguish several raw writers.
Use native hooks where they exist. Use MCP for explicit capture and claim-aware denial-before-write. Pair claims with explicit actor ids when strict separation matters.
Claude Code
hooks + MCPquilt setup wires native capture hooks and the shared MCP server. Sessions and subagents receive their own ids automatically.
Codex CLI
capture hooksSetup wires user-global ~/.codex/hooks.json when Codex is installed. One interactive approval is required. Apply-patch capture is supported; prevention parity is not yet.
Cursor
MCPWhen a .cursor/ directory exists, setup writes .cursor/mcp.json. Route edits through Quilt's MCP tools for exact capture and claim enforcement.
Other runtimes
MCP or explicit claimsUse quilt_edit and quilt_write for claim-aware denial-before-write. For arbitrary edits, set an explicit actor, claim first, and use quilt watch as additional collision detection.
Several agents in one process
Identity is automatic when each agent has its own session or MCP connection. If several subagents share one process or connection, give each a stable id and pass it as actor on every Quilt call, or set QUILT_ACTOR per subprocess.
For a complete integration runbook, including queueing, wait behavior, workspace setup, and deadlock recovery, open the agent integration guide on GitHub.
The commands used in the normal coordination loop. The canonical reference covers every flag and JSON shape.
A global actor option comes before the command: quilt --as auth-agent status. An explicit QUILT_ACTOR environment variable wins over --as.
| Command | When to use it |
|---|---|
quilt setup | Wire a repo or workspace with hooks, MCP config, and coordination guidance. Use --dry-run to preview or --gitignore for newly untracked config. |
quilt doctor | Check wiring, identity, capture flow, Git compatibility, installed version, and the MCP server. |
quilt ui | Open the local dashboard for authorship, claims, blocked work, prompts, and the needs-you queue. |
quilt fleet | See the same shared-work overview in the terminal. Add --watch for live refresh. |
quilt status | See who owns each working-tree change. |
quilt claim | Reserve files, directories with a trailing slash, or file#symbol targets with an intent. --queue registers interest and returns immediately; --wait blocks. |
quilt release | Release selected claims, or all of your claims when no path is given. |
quilt preview --mine | Inspect the exact patch your per-agent commit would contain. |
quilt commit --mine | Commit only the lines you own and leave every other actor's uncommitted work untouched. |
quilt conflicts | Separate same-line clashes from adjacent edits that can commit cleanly. |
quilt escalate | Send a collision that agents cannot reconcile to the human needs-you queue. |
quilt resolve | Mark a collision handled, or transfer another actor's dirty operations with --take. |
quilt undo / restore | Back out one actor's uncommitted changes or recover work that another actor overwrote. |
quilt provenance | Read the durable authorship record embedded in a commit. |
quilt watch | Attribute external file events to the active actor and catch collisions live. Run one watcher per repo. |
quilt telemetry | Read or change anonymous usage telemetry. It is off by default and strictly opt-in. |
quilt mcp | Run the stdio MCP server for agent integration. |
Run quilt <command> --help for flags, or open the complete CLI reference on GitHub.
One governing rule: a blocked commit beats a wrong one. Uncaptured work is inferred only when the tree is uncontested. On contested paths, Quilt leaves it pending instead of guessing the wrong author.
Capture at the tool boundary
Claude native hooks, Codex apply-patch hooks, and Quilt MCP edit tools record the author when a supported edit happens. When the ledger knows a line, that record wins.
Use claims for prevention and binding
For explicit actor ids, wired edit tools deny another actor across a claim boundary. Auto-derived callers can adopt a sole live claim holder. A prior whole-file claim also binds later shell or code generation changes to the claimant.
Reconcile as the safety floor
Commands compare the tree with Quilt's last observed snapshot. Gating prevents a contested tree from being absorbed by whichever actor happens to reconcile first.
quilt commit --mine keeps only your owned patch, applies it to a temporary Git index, and creates an ordinary commit. Your real index and working tree are not rewritten. Other actors' changes remain exactly where they were.
Attribution keys each change by side, symbol scope, content, and occurrence. Identical lines in different functions can therefore belong to different actors.
Quilt coordinates work without taking ownership of your repository, your agents, or your Git history.
Local working state lives in the gitignored .quilt/ sidecar: actors, sessions, per-line ownership, the append-only capture ledger, claims, preserved overwrites, and the escalation queue. Delete it at any time; the repository itself is untouched.
- Ordinary Git: Quilt never rewrites history. Every commit it produces is a normal Git commit.
- No agent runtime: Quilt never calls an LLM and never spawns or supervises agents.
- Scoped enforcement: wired edit tools can deny explicit actors across claim boundaries. Auto-derived callers may adopt a sole holder, and raw shell commands remain advisory.
- Private by default: the dashboard binds to
127.0.0.1, and prompt context is read locally. - Opt-in telemetry: when enabled, Quilt sends anonymous usage events and coarse environment metadata. It never sends code, paths, prompts, or names.
The practical limits and failure modes are documented without softening them in Sharp edges, stated plainly.