Skip to content
CAPA CAPA capa

Lockfile and cache

Managed install resolves remote skills, plugins, rules, hooks, and agent snippets once, then records those decisions so later installs stay reproducible and fast.

Lockfile (capabilities.lock)

Section titled “Lockfile (capabilities.lock)”

When you run capa install, capa writes capabilities.lock next to your capabilities file. The lockfile pins resolved refs for remote sources so the next install reuses the same commits/versions instead of floating to whatever main is today.

Treat the lockfile as part of the project: commit it so teammates and CI get the same resolved graph.

Hook body hashes

Section titled “Hook body hashes”

For hooks whose body comes from a remote URL or a GitHub/GitLab repo, the lockfile also records bodySha256: the SHA-256 of the fetched body. On the next install, capa compares the freshly fetched body against that hash for the same hook and pin. If the content changed upstream without a pin change, capa refuses to install it and reports Hook "<id>": content changed upstream.

When the change is expected, review it and re-resolve with capa install --no-cache, which records the new hash.

Provider config ownership

Section titled “Provider config ownership”

When capa adds a value to a setting in a provider’s own config file, it records exactly what it added under providerConfig in capabilities.lock. Today this covers Gemini CLI’s .gemini/settings.json → context.fileName, which capa points at AGENTS.md or its generated GEMINI.md (see Rules → Shared instruction files). Each entry lists the provider, config path, key path, the values capa added, and whether capa created the key.

capa clean (and any install where the value is no longer needed) removes only those recorded values, leaving your own entries and other settings untouched. Because the record lives in the committed lockfile, this also works on a fresh clone. capa install --passthrough makes the same edit but records no ownership.

Cache

Section titled “Cache”

capa caches remote git sources locally as bare git mirrors (plus file snapshots) so repeated installs do not re-clone from the network every time.

Commands

Section titled “Commands”
Terminal window
capa cache          # show location, size, per-repo breakdown
capa cache clean    # remove all cached repositories and snapshots

Bypass for one install

Section titled “Bypass for one install”
Terminal window
capa install --no-cache

--no-cache bypasses the on-disk cache and lockfile for that run and re-resolves every remote source from scratch. It does not delete the cache; use capa cache clean when you want to free disk space.

Typical loop

Section titled “Typical loop”
  1. Declare remotes in capabilities.yaml (skills, plugins, rules, and so on).
  2. Install with capa install: capa resolves, caches mirrors, and writes capabilities.lock.
  3. Re-install later: capa uses lock pins + cache for speed and stability.
  4. Force a fresh resolve with capa install --no-cache when you intentionally want new upstream content.
  5. Reclaim disk with capa cache clean if mirrors have grown large or look stale.
Section titled “Related”