CAPA: one capabilities.yaml for 35+ coding agents, plus a local MCP gateway

The problem CAPA targets: agent config that does not travel with the repo

The README states the problem plainly: agent configuration is scattered across CLAUDE.md, .cursor/rules/, AGENTS.md, MCP JSON, hooks and skill folders, and "no two teammates match." That is a real failure mode. A repository clone gives you source code and a lockfile, but it does not give you the agent setup that produced the code. Nothing is pinned, so the same prompt can hit a different tool catalog on a different machine.

CAPA's answer is to put one file, capabilities.yaml, next to the code and treat it as the source of truth for skills, tools, rules, sub-agents, MCP servers, hooks and plugins. A second file, capabilities.lock, holds SHA pins. The README's framing is that the teammate who clones tomorrow gets the exact setup you have today. That is a version-control argument, and it is the strongest argument in the repository.

The audience is teams, not solo users. A single developer with one agent and two MCP servers does not need a fan-out layer; they need a JSON file. CAPA becomes worth its own install step when the same capability set has to land in Cursor, Claude Code, Codex, Windsurf and GitHub Copilot without five people maintaining five copies.

How the fan-out works: capabilities.yaml, a lockfile, and marker blocks

The pipeline described in the README has four stages. You declare capabilities in capabilities.yaml. You run capa install, which resolves SHAs, fills a cache, writes per-provider files, and registers one MCP endpoint with each configured agent. Resolved SHAs land in capabilities.lock. Each provider then gets its native layout: .cursor/rules/, .claude/agents/, AGENTS.md and so on.

The write strategy is the detail worth noticing. CAPA uses "marker blocks" for what the README calls surgical writes that leave hand-edited content alone. This matters because provider config files are frequently shared: AGENTS.md in particular is a file a human is likely to edit. A tool that rewrites the whole file on every install would be unusable in that setting. Marker blocks are the mechanism that makes repeated installs tolerable.

The runtime half is separate from the install half. CAPA also acts as an MCP gateway: every agent talks to one local endpoint, and CAPA proxies upstream stdio, HTTP and SSE servers, lazy-loads tools on demand, and scopes what each sub-agent can call. The README's example is that a research agent never inherits a git push tool. That filtering is enforced at the gateway rather than by asking the agent nicely, which is the only version of this that holds up. The README also claims 19 to 40 percent fewer tokens across 150 trials on claude-opus-4-8 from on-demand tool loading; that is the project's own number and I have not reproduced it.

Getting it running: init, add, install, and the --yes gate

Installation is a shell script on macOS and Linux, and a PowerShell one-liner on Windows. Both are fetched from capa.sh, so the install path depends on that host being reachable.

From there the sequence is short. cd into the project, run capa init, which creates capabilities.yaml and registers the project with the local CAPA server on http://localhost:5912 by default. Then add capabilities. The README gives three forms: capa add vercel-labs/agent-skills@web-researcher for a registry reference, capa add --server --id brave --cmd npx --arg @brave/brave-search-mcp for an MCP server, and capa registry search skills-sh "research" to browse. Then capa install.

The install command has three modes worth knowing. Bare capa install is interactive and confirms the executable surface before writing. capa install --yes skips the prompt and is required in non-interactive shells, including CI and scripts. capa install --dry-run previews MCP servers, hooks and commands without making changes. The README notes that the first install prints the executable surface (MCP stdio servers, hooks, command tools, plugins) and asks for confirmation, and that an unchanged surface skips the prompt on re-run.

Two more surfaces exist. capa sh turns every configured tool into a CLI command: capa sh lists tools, capa sh brave lists subcommands, capa sh brave search --query "..." runs one, and capa sh --raw skips per-tool formatters. capa status prints the local URL of the Web UI, which is an interactive editor with live YAML sync, registry browse, OAuth setup and drag-to-reorder. There is also a bundled /bootstrap skill that scans an existing project and drafts the CAPA config after capa init.

capa wrap and the shadow workspace under ~/.capa/workspaces

capa wrap is the feature with the clearest single-purpose justification. It builds a shadow workspace under ~/.capa/workspaces/, symlinks your project minus provider-owned paths, installs capabilities into the shadow, and launches the agent there. Your real repository never receives .cursor/ or .claude/ directories.

That is a direct answer to a real annoyance. Provider directories are noise in git status, they invite accidental commits, and they differ per teammate. The README lists Claude Code, Codex, Cursor and Gemini as wrappable today, with commands like capa wrap cursor, capa wrap claude (alias claude-code), capa wrap agent for the Cursor CLI, capa wrap codex, capa wrap gemini-cli and capa wrap opencode. capa wrap cursor --print-dir prints the shadow path before launching, capa wrap --prune cleans stale workspaces, and capa stop stops the server and active wrap sessions.

The README says wrappable today is Claude Code, Codex, Cursor and Gemini, while the example block also shows an opencode invocation. That is a small inconsistency between the prose and the examples, and it is the kind of thing you would want to confirm on your own machine rather than take on faith. Symlinking a project minus provider-owned paths is also the sort of setup where build tools that resolve real paths can behave differently from a plain checkout, so a first run against a project with unusual symlink handling is worth doing before you make it the default.

Where CAPA is the wrong tool

CAPA inserts a local server into your workflow. capa init registers the project with a server on localhost:5912, and the gateway is the runtime path for every MCP call. On a machine where you cannot run a long-lived local process, or in a CI container where agents are not launched interactively, the gateway half of the product has nothing to attach to. The install half still works, but you are then using CAPA as a config generator and paying for a dependency you do not use.

The second boundary is the lockfile. capabilities.lock pins SHAs, which is the property that makes the clone argument true. It also means capability updates are a deliberate act rather than a side effect of running install. If your expectation is that agents pick up upstream skill changes automatically, the lock is working against you by design.

The third is provider coverage in the other direction. The README claims fan-out to 35+ agents and names Cursor, Claude Code, Codex, Windsurf and GitHub Copilot among them, but wrap support is listed for four. Configuration writing and runtime wrapping are different capabilities with different coverage, and the README does not enumerate which of the 35+ fall into which group. If your agent is not in the wrap list, assume you are getting file generation only until you check.

Finally, the licence. The README badge says MIT and links to LICENSE, but the repository metadata supplied to me lists the licence as unknown. Those two statements cannot both be right, and for a tool that writes into your repository and proxies your MCP traffic, the licence is not a formality.

How this differs from hand-maintained config and from MCP aggregator proxies

The obvious alternative is doing nothing: keep CLAUDE.md, .cursor/rules/, AGENTS.md and a hand-written MCP JSON per agent, and accept the drift. The difference is not convenience, it is determinism. Hand-maintained config has no lockfile, so two clones of the same repository can produce different agent behaviour with no diff to explain it. CAPA's capabilities.lock is the artifact that closes that gap. If you do not care about reproducibility across machines, the manual approach costs nothing and adds no local server.

A closer comparison is an MCP aggregator or proxy that fronts multiple upstream servers behind one endpoint. Those exist to reduce the number of endpoints an agent has to be configured with, and CAPA's gateway does that too: one local endpoint per project, proxying stdio, HTTP and SSE upstreams with lazy tool loading. The difference is what sits behind the endpoint. A standalone aggregator is configured independently of the agent config, so the tool catalog and the agent's rules, skills and sub-agent definitions live in two places. CAPA puts both in capabilities.yaml and derives both from it, which is why sub-agent isolation can be expressed as a filter on the same file that declares the sub-agent. If you only need endpoint consolidation and you are happy maintaining agent rules separately, a plain aggregator is less machinery.

The third option is provider-native passthrough. CAPA has capa add --passthrough, which writes provider-native files directly for unmanaged one-offs. That is an admission that not everything belongs in the managed model, and it is a reasonable escape hatch to keep in mind before you conclude that a capability cannot be expressed.

Maintenance cost, plugins, and the release cadence

The repository shows three releases in roughly three weeks: v2.1.0 on 2026-08-21, v2.1.1 on 2026-08-26, and v2.1.2 later the same day. The last push is 2026-09-07. That cadence is fast enough that pinning matters for reasons beyond reproducibility: a CLI that changes shape every few weeks will break scripts that wrap it. The --yes and --dry-run flags are the parts most likely to appear in CI, so those are the flags to check against the changelog before upgrading.

Plugins add a second maintenance surface. The README says Claude and Cursor plugins decompose into skills, MCP, rules, sub-agents and hooks. That means installing a plugin is not a single opaque unit; it injects multiple capability types into your capabilities.yaml and lockfile. When a plugin updates upstream, the diff you review will be a decomposed set of changes rather than one version bump, and that is more to read, not less.

Registries are the third surface. CAPA can browse skills.sh, the Cursor Marketplace, Claude plugins and Claude marketplace catalogs. Each of those is an external dependency with its own availability, and capa registry search is the command that reaches them. If a registry is unreachable, the failure shows up at add time rather than install time, which is at least the cheaper place to find out.

On licence: the README badge asserts MIT and links to a LICENSE file, while the repository metadata I was given lists the licence as unknown. I am not in a position to resolve that, and it is not legal advice to say so. Read the LICENSE file in the repository before you depend on the terms, particularly if you intend to redistribute CAPA or bundle it into an internal platform.

Editorial conclusion

Adopt CAPA if your team runs more than one coding agent and you are tired of CLAUDE.md, .cursor/rules and MCP JSON drifting apart, or if you want one local MCP endpoint per project with per-sub-agent tool filtering. Do not adopt it if you need a stable CLI surface today, if you run agents on a machine where you cannot install a local server on port 5912, or if your workflow depends on hand-editing provider directories that CAPA would own. Before committing, run capa install --dry-run on a real repository and read the printed executable surface, check that capabilities.lock contains the SHAs you expect, and confirm whether the repository ships a LICENSE file, since the badge and the repository metadata disagree on the licence.

Official sources

1. infragate/capa on GitHub
2. Issues
3. Project website
4. README
5. Releases