How capa works

capa’s loop is small: edit one capabilities file, apply it, and let the local server handle MCP and credentials. Everything else is fan-out to providers — either into your repo or into a wrap workspace.

Source of truth

capabilities.yaml (or capabilities.json) is the only declaration capa trusts. If a skill, server, rule, hook, or plugin isn’t in the file, capa won’t manage it. Leftover files under .cursor/, .claude/, and similar folders are ignored unless you put them in the file (or use passthrough / bootstrap flows that intentionally write native files).

Secrets stay out of the file: use ${VarName} placeholders. capa resolves them at install time from its credential store or a .env file.

Install fan-out

capa install reads the file and writes provider-facing artifacts: skill directories, MCP client entries, rules, hooks, agent instruction blocks, and plugins. Managed entries capa owns are labeled so a later capa clean can remove them without touching hand-authored config.

In the default managed path, install also starts the capa server.

Server role

The local server (around localhost:5912) is the runtime hub:

MCP endpoints providers connect to
Credential prompts via the web UI
capa sh tool execution

Lifecycle commands: capa start, capa stop, capa restart, capa status. capa stop also stops active wrap sessions, not just the server process.

Wrap vs in-repo

flowchart LR
  A[capabilities.yaml] --> B{How do you apply it?}
  B -->|capa install| C[In-repo provider configs]
  B -->|capa wrap| D[Shadow workspace under ~/.capa/workspaces]
  C --> E[capa server :5912]
  D --> E
  B -->|--passthrough| F[Native provider files only]

Path	Config location	capa proxy / server
Managed install	Written into the real project	Yes — server started, MCP managed
Wrap	Shadow workspace; real repo stays clean	Yes — wrap session uses capa’s layout
Passthrough	Native provider files in the project	No — skips capa proxy management

Everyday loop

Edit capabilities.yaml.
Run capa install (or capa wrap <provider>).
Verify with capa status / capa sh.
Use capa stop when you’re done with the server and any wrap sessions.