# CAPA: one capabilities.yaml for Cursor, Claude Code, Codex and 35+ agents

> CAPA is a TypeScript package manager and MCP gateway that turns a single capabilities.yaml into native config for dozens of AI coding agents, then proxies every agent's tools through one local endpoint. It is a strong fit for teams that want agent setup version-controlled next to code, and a poor fit for anyone who wants a stable, documented, long-lived platform today.

**infragate/capa** — One capabilities.yaml wires skills, tools, rules, sub-agents, MCP servers, and plugins into Cursor, Claude Code, Codex, Windsurf, GitHub Copilot, and 30+ other AI coding agents

- Repository: https://github.com/infragate/capa
- Website: https://capa.sh
- Stars: 737 · Forks: 99
- Language: TypeScript
- License: not declared
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/infragate-capa

## The problem CAPA targets: agent config that never leaves your laptop

The README opens with a blunt diagnosis: agent configuration today is scattered across CLAUDE.md, .cursor/rules/, AGENTS.md, MCP JSON, hooks and skill folders. No two teammates match, nothing is pinned, and cloning the repository does not clone the agent setup. That last point is the one worth taking seriously. If a new engineer clones a repo and their agent behaves differently from yours, the difference lives in files that were never committed.

CAPA's answer is to make capabilities.yaml the source of truth and capabilities.lock the pinning layer, so a clone tomorrow produces the same bytes as a clone today. The audience is teams running more than one agent across more than one machine, and it is a team-shaped problem: a solo developer with one editor gets less from it than a group where Cursor, Claude Code and Codex are all in play.

One caveat before anything else. The README badge says MIT, but the repository metadata supplied for this review lists the licence as unknown, and the top-level entries include a LICENSE file whose contents are not shown. Treat the licence as unverified until you open that file yourself.

## One file, many native layouts: how CAPA fans out

CAPA is written in TypeScript and ships a compiled CLI. The mechanism has two halves. At install time, CAPA reads capabilities.yaml, resolves SHAs into capabilities.lock, fills a cache, and writes per-provider files into each agent's native layout: .cursor/rules/, .claude/agents/, AGENTS.md and the rest. The README describes these writes as marker blocks, meaning CAPA edits only the region it owns and leaves hand-edited content alone. That is the detail that decides whether the tool is usable on a repository that already has agent config, and it is the detail the README states but does not illustrate.

At runtime, CAPA is an MCP gateway. Each agent talks to one local endpoint instead of each upstream server directly. CAPA proxies stdio, HTTP and SSE servers, lazy-loads tools on demand, applies formatters, and records activity. Sub-agents get filtered endpoints, so a research sub-agent does not inherit a git push tool. That filtering is the most defensible part of the design: it is a permission boundary expressed in the same file as the capability list.

The README claims on-demand tool loading cuts tokens by 19 to 40 percent across 150 trials on claude-opus-4-8. That is a vendor figure from the project's own README, not an independent measurement, and the trial methodology is not described.

## Installing CAPA and running a first capability

Installation is a shell script on macOS and Linux, and a PowerShell one-liner on Windows. Both are hosted at capa.sh. The README does not document an npm or Homebrew route, so if you avoid piping remote scripts into a shell you will need to read install.sh before running it, or build from source with the bun scripts in package.json.

```bash
curl -LsSf https://capa.sh/install.sh | sh
```

The Windows equivalent uses irm against install.ps1. After that, initialise a project. This creates capabilities.yaml and registers the project with the local CAPA server, which the README gives as http://localhost:5912.

```bash
cd your-project
capa init
```

Add a capability from a registry, or define an MCP server inline. The second command is the one to watch: it declares a stdio server that CAPA will later launch, so it belongs in the executable surface you review.

```bash
capa add vercel-labs/agent-skills@web-researcher
capa add --server --id brave --cmd npx --arg @brave/brave-search-mcp
```

Then install. Interactive runs confirm the executable surface first; CI and scripts must pass --yes, and --dry-run previews MCP servers, hooks and commands without writing.

```bash
capa install --dry-run
capa install --yes
```

Finally, tools are reachable from the terminal as subcommands under capa sh, and capa status prints the local Web UI URL when the server is running.

```bash
capa sh brave search --query "..."
capa status
```

## Where CAPA gets in the way

The first-install prompt is the honest limitation. CAPA prints the executable surface (MCP stdio servers, hooks, command tools, plugins) and asks for confirmation, because installing a capability means agreeing to run code. In CI there is no one to ask, so the README requires --yes, which is exactly the flag that removes the review step. A pipeline that runs capa install --yes on every build is trusting whatever the registry resolved to at that moment.

There is no documented rollback. The README does not explain how to undo an install, how to remove a capability cleanly, or what happens to marker blocks when a capability is dropped from capabilities.yaml. capa wrap avoids one class of mess by building a shadow workspace under ~/.capa/workspaces/ and symlinking the project minus provider-owned paths, but that solves repo pollution, not configuration reversibility. capa wrap --prune cleans stale workspaces, and capa stop stops the server and active wrap sessions.

Provider coverage is also uneven in a way the headline number hides. The README says 35+ agents, but the wrappable list is four: Claude Code, Codex, Cursor and Gemini. If your workflow depends on wrapping rather than writing config, the effective surface is much narrower than the marketing line.

## CAPA versus committing your own AGENTS.md and MCP JSON

The realistic alternative is not a competing product. It is doing the fan-out by hand: commit an AGENTS.md, a .cursor/rules/ directory and an MCP JSON file, and keep them in sync through review. That approach has real advantages. The files are plain text, every agent already reads them, there is no gateway process between your agent and its tools, and nothing needs a local server on port 5912.

The difference in approach is where the pinning lives. Hand-maintained config pins nothing: a skill pulled from a registry is copied at whatever revision the author had, and the copy drifts. CAPA moves that pinning into capabilities.lock and resolves SHAs at install time. The trade is a dependency on CAPA's resolution logic and on the gateway staying up. If the local server is not running, the runtime half of the tool is not available, and the README does not describe a fallback path for agents pointed at the CAPA endpoint.

A second alternative is scoping down: use CAPA only for MCP gateway duties and keep hand-written rules. The README's capa add --passthrough exists for the opposite instinct, writing provider-native files directly when you want unmanaged one-offs.

## Maintenance, releases and upgrade cost

The repository is not archived and the last push was on 2026-09-07. Releases are frequent and tightly spaced: v2.1.0 on 2026-08-21, v2.1.1 and v2.1.2 both on 2026-08-26. That cadence is a real cost for anyone pinning CAPA in CI. Two patch releases in one day suggests fixes landing quickly, and it also means a lockfile strategy for the CAPA binary itself, separate from capabilities.lock, is worth having.

The versioning is confusing in a way that matters for upgrades. package.json declares version 1.0.0 while the latest release tag is v2.1.2. The README does not explain the relationship between the two, so do not infer compatibility from either number. The CLI is built with bun and the build script compiles src/cli/index.ts to dist/capa, copying registries into dist/registries, so a source build needs bun present.

On licence: the badge says MIT, the metadata says unknown. MIT would permit commercial use and redistribution with attribution, but that is a general property of the licence text, not a statement about this repository. Confirm the LICENSE file before you depend on it.

## Conclusion

Adopt CAPA if you run several agents across a team and the drift between CLAUDE.md, .cursor/rules/ and AGENTS.md is costing you real time; the marker-block writes and capabilities.lock are the parts that matter. Do not adopt it if you need a documented licence, a stable config schema, or a tool whose runtime behaviour you can predict from the README alone. Before committing, verify the LICENSE file contents, run capa install --dry-run on a throwaway checkout, and confirm that the executable surface it prints matches what you expect to run from your repository.

## FAQ

### How do I install CAPA on macOS or Linux?

The README gives a single shell command: curl -LsSf https://capa.sh/install.sh | sh. Windows uses a PowerShell equivalent against https://capa.sh/install.ps1. The README does not document an npm or Homebrew installation route.

### Can I use CAPA in CI where no one can answer the install prompt?

Yes, but you must pass --yes. The README states that non-interactive shells such as CI and scripts must pass --yes, because the first install prints the executable surface and asks for confirmation before writing anything.

### What port does the CAPA local server use?

The README gives the default as http://localhost:5912, and capa init registers the project with that local CAPA server. capa status prints the local URL when the server is up.

### How do I run a configured MCP tool from the terminal with CAPA?

Every tool you define is also a CLI command under capa sh. capa sh lists every configured tool, capa sh brave lists the subcommands of one tool, and capa sh --raw skips the per-tool formatters.

## Sources

- [infragate/capa on GitHub](https://github.com/infragate/capa)
- [Issues](https://github.com/infragate/capa/issues)
- [Project website](https://capa.sh)
- [README](https://github.com/infragate/capa/blob/main/README.md)
- [Releases](https://github.com/infragate/capa/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/infragate-capa