Wrap workspaces

capa wrap launches a provider against a shadow workspace so capa can install managed files there without rewriting provider configs inside your real project tree.

How wrap works

Pick a project and provider
Default project is the current directory (--project overrides). You pass a wrappable provider (or omit it to be prompted).
Build a shadow workspace
capa creates or reuses a directory under ~/.capa/workspaces, symlinks (or junctions) most of your project into it, and runs install against the workspace — not the real tree’s provider-owned paths.
Exclude provider-owned paths
Paths owned by the wrap target and by entries in capabilities.providers stay out of the symlink sync so wrap does not clobber the real project’s native configs.
Watch for changes
While wrap runs, capa watches your real project’s capabilities file (and related state) and re-applies into the workspace when things change.
Launch GUI or CLI
GUI providers stay attached until the window closes (or you interrupt). CLI providers run in the foreground; watchers continue in a detached helper process.

flowchart LR
  Real["Real project"] -->|symlink / sync| Shadow["~/.capa/workspaces/..."]
  Caps["capabilities.yaml"] -->|watch + re-apply| Shadow
  Shadow --> Provider["Provider GUI or CLI"]
  Stop["capa stop"] -->|ends wrap sessions| Shadow

Flags

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

capa wrap cursor
capa wrap claude-code --project ~/code/my-app
capa wrap cursor --print-dir
capa wrap --prune

Extra args after the provider are forwarded to the launch binary.

GUI vs CLI providers

Kind	Behavior
GUI	Watchers run in-process. Wrap stops when the app window closes, or on Ctrl+C / quit.
CLI	Watchers run in a detached worker so the TUI keeps a real stdin. Wrap follows the CLI process lifetime; stop signals clean up the watcher.

Stopping wrap

capa stop stops the capa server and any active wrap sessions. Closing a GUI window (or exiting the CLI) also ends that session’s watchers.

Use capa wrap --prune when you want to delete cached shadow workspaces under ~/.capa/workspaces without launching a provider.