DaCapo

Context deduplication for LLM agent sessions. Agents pay for the same bytes over and over — the same file read five times, the same git status between steps, a scout subagent re-reading what it already read. DaCapo intercepts tool output and, when a context sees content it has already seen, replaces the repeat with a short ref token (⟦dc:<16hex>⟧, ~15 tokens, approx) instead of the full payload. The original is recoverable with dacapo expand. It is a layer, not a rewrite: it composes with format-compressors rather than competing with them.

"Da capo" (music): repeat from the beginning. We don't replay the repeat — we point back to it.

Requirements

• Node.js >= 24 — DaCapo uses the built-in node:sqlite module, so there are zero native dependencies and nothing to compile. Older Node will not run it.

Install

npm install -g @lyupro/dacapo     # the single `dacapo` bin
dacapo install                    # merge our hook into your agent's config (asks nothing destructive)
dacapo doctor                     # read-only self-check: Node, cache DB, config, installed hooks

dacapo install writes only its own keys, atomically, with a backup, and is idempotent; dacapo uninstall is symmetric and restores your config byte-for-byte. Every installer supports --dry-run. By default dacapo install targets the global agent config (~/.claude/...); pass --scope project only when you deliberately want a repo-local hook.

Installing globally without sudo (Linux/macOS)

npm install -g can fail with EACCES when Node's global prefix is root-owned. Prefer a setup where global installs land in your home, so no elevation is ever needed — a Node version manager (nvm / fnm), or a user-owned prefix (npm config set prefix ~/.npm-global, then add ~/.npm-global/bin to your PATH). This also keeps dacapo update working: it runs npm install -g without elevating (it never runs sudo for you — by design), so a root-owned install it cannot overwrite would break self-update. sudo npm install -g @lyupro/dacapo works as a last resort, but then updates need sudo too, and dacapo update will only print that command, never run it. (Windows is unaffected — npm's global prefix is already user-owned.)

What it guarantees (plain language)

• A ref is only ever shown to a context that already saw the original. The main thread and each subagent have separate "seen" memories; a subagent never inherits the main thread's, and vice versa. If DaCapo can't be sure a context saw the content, it sends the full output. A broken reference is worse than no savings, so it never risks one.
• It can't lose or corrupt your output. Any internal error (database, config, disk) falls back to passing the original through unchanged. Failures go to a log and to dacapo doctor, never into the stream your agent reads.
• Your command's exit code is preserved (the rewrite keeps pipefail), so the agent still sees failures.
• Secrets are never cached. Output that looks like a key/token/credential is passed through without being written to disk.
• Zero network at runtime, zero telemetry. The only command that ever touches the network is the explicit dacapo update.

Adapters

Four hosts are wired through one registry (dacapo install covers all detected ones):

• Claude Code — pre-execution command-wrap (Bash + PowerShell). Validated end-to-end against a live headless session.
• Cursor — the same pre-execution command-wrap (Shell tool), sharing the adversarially-tested POSIX-sh wrapper. Subagent attribution and permission-less rewrite are structurally tested but not yet verified in a live IDE session.
• Codex CLI — post-hoc substitution (a repeated PostToolUse result is replaced with a ref). Ships observe-only by default (agents.codex.trust_context=false): it records what it would save but emits no substitution until the operator verifies subagent attribution — because a ref must never reach a context that may not have seen the original. dacapo doctor surfaces this.
• Hermes — post-hoc substitution via transform_tool_result (a repeated tool result is replaced with a ref). Its config.yaml is patched comment-safe (foreign keys and comments survive install/uninstall). Ships the same observe-only default (agents.hermes.trust_context=false) until subagent attribution is verified; some protocol details (result field name, transform stdout encoding) are marked UNVERIFIED-live in docs/INTEGRATION/hermes.md.

Everyday commands

dacapo stats [--daily] [--by agent|cmd] [--json]   # local savings; token counts marked (approx)
dacapo purge --all | --project . | --older-than 30d # reclaim disk (headless-safe without --yes)
dacapo doctor [--json]                              # read-only diagnostics, changes nothing
dacapo update [--check] [--dry-run]                 # self-update via npm (the only network use)
dacapo expand <ref>                                 # recover an original by its ref token

dacapo update reads our own version, compares it to the registry's dist-tags.latest, and (unless --check/--dry-run) runs npm install -g @lyupro/dacapo@latest. It never elevates: if the global install root is not writable it prints the exact command for you to run and stops.

Quick demo

Pipe any command's output through dacapo dedup with a stable context id. The first time it passes through unchanged; the second time the same context sees the same bytes and gets a ref instead:

echo "hello world" | dacapo dedup --ctx demo --cmd echo
# hello world

echo "hello world" | dacapo dedup --ctx demo --cmd echo
# ⟦dc:…⟧ = this exact content already appeared earlier in this conversation (deduplicated). Recover: dacapo expand <ref>
# ⟦dc:a1b2c3d4e5f60718⟧ (12B, first seen 0 tool calls ago, cmd: echo)

dacapo expand a1b2c3d4e5f60718
# hello world

A different --ctx (a different conversation window, e.g. a subagent) never receives a ref for content it has not itself seen — that is the whole point.

Privacy

• Originals are stored locally, unencrypted, at ~/.lyupro/.dacapo/cache/dacapo.db (SQLite), so that dacapo expand can recover them. This file never leaves your machine.
• Turn it off: set cache.store_originals: false in ~/.lyupro/.dacapo/config.json — dedup and stats keep working, only expand can no longer recover that content.
• Clean up any time: dacapo purge --all (or --project / --older-than).
• Zero network, zero telemetry at runtime. dacapo doctor reports cache health and config foot-guns without touching anything.

Numbers are honest: token estimates are bytes/4 and always shown (approx); any figure published elsewhere must be reproducible by a repo benchmark script. Savings depend on how repetitive your session is — DaCapo promises the mechanism (a repeat collapses to a ~15-token ref), not an average.

Docs

• docs/ARCHITECTURE.md — the design and the core invariant.
• docs/CONFIGURATION.md — every config key and DACAPO_* env var.
• docs/INTEGRATION/{claude-code,codex,cursor,hermes}.md — per-adapter reference incl. known limits.
• docs/PUBLISHING.md — the release runbook.
• ROADMAP.md — shipped work, what's next, and ideas under exploration.

License

MIT