capa cache

Inspect or manage the on-disk cache that CAPA uses to avoid re-cloning remote repositories on every install.

Usage

capa cache              # show cache info (alias for "capa cache" with no subcommand)
capa cache clean        # delete everything in the cache

Description

Whenever capa install resolves a GitHub or GitLab source, CAPA materialises the cloned repository into a content-addressed snapshot under your cache directory. Subsequent installs that reference the same repo (and the same version or commit) reuse the snapshot instead of cloning again. That's why repeated installs feel close to instant.

The cache lives at ~/.capa/cache/ (Windows: %USERPROFILE%\\.capa\\cache\\) and is shared across all your projects.

Subcommands

capa cache

Without a subcommand, prints a summary of what's currently cached:

Cache directory: /Users/you/.capa/cache
Total size:      482.3 MB
Repositories:    7

Per-repo breakdown (largest first):
  github:vercel-labs/agent-skills
    total:     312.1 MB
    mirror:    156.0 MB
    snapshots: 156.1 MB (4)
  gitlab:my-org/internal-skills
    total:     108.4 MB
    mirror:     54.2 MB
    snapshots:  54.2 MB (2)
  ...

For each repo, the output shows:

  • mirror: the bare clone CAPA uses for fast checkouts.
  • snapshots: the working trees materialized for specific resolved commits (one per unique commit SHA you've installed).

capa cache clean

Wipes the entire cache. Future installs will need to clone repositories from scratch.

capa cache clean
✓ Cleared cache (freed 482.3 MB) at /Users/you/.capa/cache

When to Use

  • Free up disk space. Large monorepos can occupy hundreds of MB.
  • Force a fresh clone if you suspect the cache is stale or corrupted. For a single install you can use capa install --no-cache instead, which bypasses the cache and lockfile for that one run without deleting anything.
  • After upgrading capa, only if release notes call for it. CAPA otherwise migrates cache layouts in place.

How the Cache Interacts with the Lockfile

When CAPA installs a remote skill or plugin, it records the resolved commit SHA in capabilities.lock alongside the originally requested version or ref. The next capa install:

  1. Reads the lockfile to find the previously resolved SHA.
  2. Checks if a cache snapshot exists for that SHA.
  3. If yes, reuses it. No network call required.
  4. If no (or --no-cache was passed), re-resolves and re-clones.

The lockfile gives you reproducibility (everyone on the team installs the exact same commit). The cache gives you speed.

Related Commands

  • capa install: uses the cache automatically. Pass --no-cache to bypass it.
  • capa clean: removes installed skill files. Does not touch the cache.