Skip to content
CAPA CAPA capa

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

Section titled “How wrap works”

  1. Pick a project and provider
    Default project is the current directory (--project overrides). You pass a wrappable provider (or omit it to be prompted).

  2. 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.

  3. 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. Before each session capa validates the workspace: provider directories (.cursor, .claude, …) and nested install paths such as .cursor/skills must be real directories in the workspace. A symlink or junction that would send writes into the real project is removed and the workspace is reinstalled.

  4. 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. Capability edits made in the Web UI re-render hooks, rules, agent instructions, and sub-agents into active wrap workspaces only: the real project’s provider files change only when you run capa install there.

  5. 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

Section titled “Flags”
FlagPurpose
--project <dir>Source project directory (default: cwd)
--print-dirPrint the workspace path before launching
--pruneRemove wrap workspaces under ~/.capa/workspaces and exit
Terminal window
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. On Windows, arguments with spaces stay intact; .cmd / .bat provider shims refuse arguments containing line breaks (pass multi-line prompts on stdin).

The wrap install uses the same executable surface confirmation as capa install. In non-interactive sessions, use capa --yes wrap <provider>.

GUI vs CLI providers

Section titled “GUI vs CLI providers”
KindBehavior
GUIWatchers run in-process. Wrap stops when the app window closes, or on Ctrl+C / quit.
CLIWatchers 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

Section titled “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.

Section titled “Related”