infragate/capa

TL;DR

CAPA is a package‑manager‑style tool that lets you declare all the AI‑coding‑agent capabilities (skills, tools, rules, sub‑agents, MCP servers, plugins, etc.) in a single capabilities.yaml file and then automatically writes the appropriate configuration for dozens of agents (Cursor, Claude Code, Codex, Gemini‑CLI, GitHub Copilot, …). It also runs a local MCP gateway so every agent talks to the same endpoint, which proxies upstream servers, lazily loads tools, and isolates sub‑agents.

---

What it does (in plain language)

Step	What you run	What happens
Initialize	capa init	Creates a capabilities.yaml next to your code and registers the project with a local CAPA server (default http://localhost:5912).
Declare capabilities	capa add … (e.g., capa add vercel-labs/agent-skills@web‑researcher)	Adds a skill, tool, rule, MCP server, or plugin to the YAML file. You can also pull from registries like skills.sh or the Claude Marketplace.
Install	capa install (or capa install --yes in CI)	Resolves exact SHAs, writes the needed files into each agent’s native layout (.cursor/, .claude/, AGENTS.md, etc.), creates a lockfile (capabilities.lock) and starts a per‑project MCP endpoint that the agents will use.
Run an agent without polluting your repo	capa wrap cursor (or capa wrap claude, capa wrap codex, …)	CAPA builds a shadow workspace under ~/.capa/workspaces/, symlinks your project (excluding provider‑specific folders), installs the declared capabilities there, and launches the chosen agent. The real repository stays clean.
Interact from the terminal	capa sh brave search --query "…"	Calls a registered tool directly via the local MCP gateway. capa sh also lists available tools.
Edit visually	capa open	Opens a local React‑based web UI where you can CRUD capabilities, browse registries, see live activity traces, and set OAuth credentials.

Key ideas behind CAPA

1. Single source of truth – All capabilities live in one version‑controlled YAML file, plus a lockfile that pins exact versions (SHAs). No more scattered CLAUDE.md, .cursor/rules/, etc.
2. MCP gateway – A local proxy (localhost:5912) that every agent talks to. It forwards calls to the real upstream MCP servers, loads tools only when needed, and can filter which tools a sub‑agent may use.
3. Write‑once, fan‑out – When you run capa install, CAPA translates the declarative config into the native file format required by each supported agent (35+ providers at launch). This keeps the repo in sync across teammates.
4. Shadow workspaces – capa wrap lets you spin up an agent in an isolated copy of the repo, preventing provider‑specific hidden folders from contaminating your source tree.
5. Observability – The built‑in UI shows a live feed of every MCP call, tool execution, and agent span, helping you debug or audit what the agents are doing.

---

Who might use it?

• Teams building AI‑assisted development tools that rely on multiple coding agents (e.g., a mix of Claude Code, Cursor, and Gemini‑CLI) and want a reproducible, version‑controlled setup.
• DevOps / MLOps engineers who need to pin exact tool versions and ensure every CI runner gets the same agent configuration.
• Individual developers who want to experiment with new agent skills without manually editing dozens of config files.

---

Quick start checklist (copy‑paste)

# 1️⃣ Install the CLI (macOS / Linux)
curl -LsSf https://capa.sh/install.sh | sh
# Windows – PowerShell version omitted for brevity

# 2️⃣ Initialise a project
cd my‑project
capa init

# 3️⃣ Add a skill / tool (example)
capa add vercel-labs/agent-skills@web-researcher
capa add --server --id brave --cmd npx --arg @brave/brave-search-mcp

# 4️⃣ Install into all agents
capa install   # interactive first run
# or in CI
capa install --yes

# 5️⃣ Run an agent without touching the repo
capa wrap cursor   # opens Cursor GUI in a shadow workspace

# 6️⃣ Open the visual editor (optional)
capa open   # launches http://localhost:5912 in your browser

---

Limitations / open questions (as of the README)

• GitHub Copilot cannot yet be wrapped because it shares .github/ / .vscode/ directories.
• On Windows, creating the shadow workspace may require Developer Mode or elevated privileges for symlinks.
• The list of supported agents is growing; if you rely on a niche agent, check whether a provider plugin exists.

---

Where to learn more

• Official docs & getting‑started guide: https://capa.sh/getting-started/introduction/
• Schema reference & internals: docs/README.md inside the repo.
• Release notes & binaries: GitHub releases page (badge in the README).

---

Bottom line

CAPA aims to make AI‑coding‑agent environments reproducible and manageable by turning a scattered, manual setup into a declarative, version‑controlled workflow, while also providing a local MCP gateway and a handy UI for visibility.