AgentQuilt

Inspiration

Anyone who's maintained a shared agents, skills or AGENTS.md file knows the pain: it's one giant Markdown blob, and the moment two people touch it at the same time — one adding a testing rule, another adding a security rule — Git hands you a merge conflict in the middle of prose. Unlike code, agent instructions are semantic, not syntactic, so there's no clean three-way merge to fall back on. We also watched the multi-agent-platform problem compound this: teams now maintain near-duplicate instruction files for Codex, Cursor, Claude and Copilot by hand, each one drifting slightly from the others. We wanted structured source files to do for agent instructions what they already do for infrastructure and code: small, ordered, composable units that compile deterministically into whatever output each tool needs.

What it does

AgentQuilt turns agent instructions into small Markdown fragments — one concern per file (role, build commands, testing rules, security rules) — stored under .agentquilt/agents/<agent-id>/ and numbered with gaps (010, 020, 030) so new fragments can be inserted without renumbering. A deterministic compiler reads the fragments plus a minimal agent.yaml manifest and produces identical, hash-verified Markdown every time — the same fragments compile straight to .codex/agents/*.toml, AGENTS.md, .claude/agents/*.md files, with no hand-written Codex config at all. agentquilt check is a gate that detects drift between source and disk, and a build-time tamper guard refuses to silently overwrite a generated file that's been hand-edited since the last build. On top of the CLI, we built a VS Code extension: a sidebar tree of agents and fragments read straight from the lock file, a live preview webview with real HTML rendering (via marked) instead of a raw escaped-string dump, a drift status bar that flips the moment a fragment changes and clears after a rebuild, and a one-click "Enable Provider" command that edits .agentquilt/config.yaml through the yaml package's Document API so comments and formatting survive.

How we built it

The core is TypeScript with Zod schema validation and Commander for the CLI (agentquilt init, build, build --watch, check, agents add/list, skills add/list). The compiler normalizes fragments (LF line endings, trailing newlines) before hashing so the hash always matches the output, and orders fragments strictly by Unicode code point — never locale-aware sorting — to keep builds reproducible across machines. A Merkle-style target version binds fragment content, order, and format identity together, so any change to any of the three bumps the version. Adapters translate the same fragment set into platform-specific output: Claude, Codex (as standalone TOML, never touching .codex/config.toml), and the vendor-neutral Agent Skills format. For the demo, we scripted a live, unstaged comparison: a monolithic REVIEWER.md where two simultaneous branches collide in a merge conflict, versus the same two changes as separate fragment files, which merge cleanly and then compile into a combined Codex agent. The VS Code extension reads the same agentquilt.lock file the CLI writes, so the editor view and the CLI's idea of "current state" never disagree.

Challenges we ran into

Model-tier resolution across platforms turned into a real trap, not just a demo bug: enabling Codex on the repository's own 14-agent dev portfolio broke the build outright, because modelTiers only mapped tier names like balanced to Claude model IDs, and Codex has no default model identifiers scaffolded (a deliberate choice per ADR-0015, not an oversight) — so every agent using model: balanced threw Tier "balanced" has no mapping for platform "codex". The fix wasn't to add Codex entries to fill the gap; it was recognizing that this particular target shouldn't have Codex enabled at all, and using a separate fixture repo to exercise Codex-specific features instead. Getting the Codex preview to render readably in the extension was its own fight — Codex's TOML output escapes newlines as literal \n in strings, so a naive text dump was unreadable; we ended up parsing it with smol-toml (the same library the CLI itself uses) to decode it back into real prose before rendering. And more mundanely: running concurrent work in the same checkout kept yanking uncommitted extension work across branches, which pushed us to build the extension in an isolated git worktree instead of fighting branch switches.

Accomplishments that we're proud of

Deterministic output is a genuinely hard guarantee to keep honest, and we kept it: the same fragments always hash to the same target version and always compile to byte-identical Markdown, verified in CI via agentquilt check. The tamper guard means the tool can refuse to overwrite a manually edited generated file instead of silently discarding someone's work — a small feature that prevents a real class of data loss. Getting a from-scratch VS Code extension to read live off the same lock file the CLI produces, with drift detection and auto-refreshing previews, gave the merge-conflict story a visual, editor-native payoff instead of just a terminal trick. And the "adopt an existing hand-written agent file with one command, then watch it start compiling to a second platform for free" flow is the kind of demo that makes the value concrete in under a minute.

What we learned

The deepest lesson was that "platform-agnostic" is a much stricter constraint than it sounds: it means every named provider is an example instance of a registry entry, never a special case baked into the compiler, and it surfaces in unglamorous places like model-tier mappings, not just in adapter code. We also learned to treat generated files as sacred — agentquilt.lock, .codex/agents/*, AGENTS.md, CLAUDE.md are never hand-edited, full stop — because the moment you let one exception in, drift detection loses its meaning. On the tooling side, building the VS Code extension against the same lock file the CLI already writes (rather than re-deriving state) kept the two surfaces honest with each other for free, which we think is the right pattern for any companion UI layered on top of a CLI-first tool.

What's next for AgentQuilt

Immediate: rehearsing and recording the VS Code extension demo, then committing the extension work out of its current worktree and getting it through review. Near-term, deferred items already on the roadmap: lint rules and semantic diffing for fragments, an eval runner for regression-testing agent behavior across compiled versions (not just prompt-presence checks), and release packaging/migration tooling. Longer-term, the "Enable Provider" and platform quick-pick UX in the extension point toward making platform onboarding a guided, zero-hand-editing flow rather than a config file edit — and there's an open question of whether AgentQuilt should ship a small library of common fragment patterns (security review blocks, testing conventions) that teams can pull in rather than write from scratch.

Built With

• codex