wrap

Use capa wrap when you want capa’s install output in a shadow workspace under ~/.capa/workspaces instead of writing provider files into the project tree.

Synopsis

capa wrap [provider] [args...] [--project <dir>] [--print-dir] [--prune]

If you omit provider, capa prompts (TTY) for a wrappable provider. Extra [args...] are forwarded to the provider binary.

Flags

Flag	Description
`--project <dir>`	Source project directory (default: current working directory)
`--print-dir`	Print the workspace path before launching
`--prune`	Remove wrap workspaces under `~/.capa/workspaces` and exit

Behavior

Resolves the provider (prompt if omitted).
Fails fast if the provider launch binary is missing from PATH.
Prepares a shadow workspace, validating and repairing it on every session: provider directories (.cursor, .claude, …) and their install paths must be real directories in the workspace, never symlinks into the real project.
Installs capa-managed artifacts there, writing only under the workspace. Like capa install, this asks you to confirm the executable surface when it is new or changed. All MCP servers from the capabilities file are enabled.
Launches the provider against that workspace.

Without a TTY, pass the global --yes flag before the subcommand to accept the executable surface: capa --yes wrap claude. Flags after the provider are forwarded to the provider binary.

Windows arguments

Forwarded arguments keep their quoting: capa wrap claude -p "fix the bug" reaches Claude as a single prompt. Providers installed as .cmd / .bat shims (such as Cursor’s agent) run through cmd.exe, so capa refuses arguments that contain line breaks for them. Pass multi-line prompts on stdin instead.

capa stop also stops active wrap sessions. See Server lifecycle.

Examples

capa wrap
capa wrap cursor
capa wrap claude-code --print-dir
capa wrap cursor --project ../other-app
capa wrap --prune