Setup guide

Install CVC in a couple of minutes.

Pick how you code. Everything below switches to that one path. No account is needed for local setup.

Capture is local, in your repo's .git/cvc. Nothing leaves your machine until you share and publish it, each behind a typed confirmation. How your data moves →

New in CVC 0.7.0: native Claude Code capture. What's new →

Claude Code

Transcript tier

Transcript capture: every assistant response, recorded from the transcript Claude Code writes through its own lifecycle hooks — no cooperation from the model. You need Claude Code, a Git repository, Node.js and npm (or a release archive), and CVC 0.7.0 or later. Verified on Linux and macOS; Windows hook execution is untested in 0.7.0.

  1. 1

    Install CVC

    Once per machine. The npm launcher provides cvc as well as cvc-mcp; a release archive from GitHub works too.

    npm install -g @volute_cvc/cvc-mcp

    You should see: cvc --version prints 0.7.0 or later.

  2. 2

    Initialize the repository

    Creates the local cache and the advisory Git hooks. Once per repository.

    cvc init

    You should see: cvc status runs without error.

  3. 3

    Acknowledge local capture, once per repository

    Type I UNDERSTAND LOCAL CAPTURE at the prompt. Passive capture — these hooks included — stays off until you do, and the next step refuses to install without it.

    cvc privacy acknowledge-capture

    You should see: cvc privacy status shows capture_acknowledged: true.

  4. 4

    Install the Claude Code hooks

    Writes PostToolUse, Stop, and SessionEnd entries into this checkout’s .claude/settings.local.json, pointing at the cvc you just ran. Per checkout: repeat it in each linked worktree, including one created by Claude Code’s own worktree option. Cowork sessions are not supported.

    cvc harness install claude-code

    You should see: /hooks inside Claude Code lists the three entries.

  5. 5

    Start a new Claude Code session and work normally

    A session that was already running does not pick up the hooks. From then on every assistant response is recorded as a private thought; there is nothing to invoke.

    You should see: cvc conversations lists the session (its id is the Claude Code session id) with a growing thought count. Commit from inside the session: the post-commit hook prints CVC: Linked N thought(s) to commit <sha>. and those thoughts link to it.

What this changes

Files writtenPer machine: the CVC binaries. Per checkout: three hook entries in .claude/settings.local.json, never committed — CVC adds the file to the repository’s info/exclude. Per repository: .git/cvc and the advisory Git hooks from cvc init.
Processes runAfter each tool call and each answer, cvc ingest claude-code --hook runs for a few milliseconds and appends new responses to the local database. Silent on success; a transcript it cannot read fails visibly without blocking Claude Code.
Where data livesA local SQLite cache in .git/cvc, shared across the repo’s linked worktrees. Nothing leaves your machine until you share and push. Remove the hooks with cvc harness uninstall claude-code.

Claude and Claude Code are trademarks of Anthropic. Volute is not affiliated with or endorsed by Anthropic.

Publish to hosted review (optional)

Same on every path, and always deliberate. Authorize the remote, see what is recorded, share the conversations you choose, then publish. Each step asks for its typed phrase (I AUTHORIZE SHARING, I SHARE, I PUBLISH). A normal git push never carries CVC data.

cvc privacy acknowledge-sharing --remote origin
cvc conversations
cvc share <conversation-id> --remote origin
cvc push --manual --remote origin

You should see: the conversation marked [shared] in cvc conversations, and the shadow timeline beside the diff in hosted review after the push.

Sign in for hosted review
Open source

The client you just installed is open source.

Core library, cvc CLI, cvc-mcp, and the VS Code extension are Apache-2.0. Read the code before you trust it with your prompts, or install from a release archive verified against SHA256SUMS.txt.

Browse the repository Download release binaries
Advanced: fidelity tiers, MCP tools, hooks, troubleshooting

Capture fidelity

Every capture channel carries a tier, so you always know what a record is worth.

TranscriptVerbatim I/O as the tool persists it (VS Code Copilot watcher; Claude Code hooks). “What was actually said.”
AttestedAgent-authored records via MCP commit_thought. “What the agent chose to record.”
TraceRaw command I/O without structure via cvc run. “What crossed the wire.”

MCP tools

commit_thoughtRecord a task, reasoning, and optional result (Attested).
read_historyRead prior recorded context and decisions.
get_contextInspect Git-backed context for one file.
setup_cvcInitialize CVC storage and hooks for the repo.
sync_historyImport CVC history already published to the Git remote by other sessions or teammates, so read_history can find it. Never pushes.

Git hooks

Added at repository setup, not at install, and never silently. Hooks are advisory and never fail a Git operation. The pre-push hook publishes only under a standing auto-push grant (cvc privacy set-auto-push on --remote origin, typed I AUTHORIZE AUTO PUSH ON <fingerprint>).

Upgrading from 0.5.x or 0.6.0

The first 0.7.0 component to open a repository rebuilds one table once (capture-source-claude-code/v1); 0.5.x and 0.6.0 binaries keep working on the migrated store, so upgrade the CLI, language server, and MCP server on a machine together. Restart running MCP servers afterwards. cvc component and cvc auth are removed. Full 0.7.0 notes →

If the MCP server does not start

  • • Re-run npm install -g @volute_cvc/cvc-mcp to confirm the global install.
  • • Restart the client after editing MCP settings.
  • • After upgrading CVC, restart your MCP client so it loads the new server — hosts keep the old process alive for the session.
  • • Run cvc --version in a terminal — it prints the version and exits 0 — to confirm the install.

Common questions

Do I need an account?

No. Local setup works without signing in. An account is only for hosted review, private repositories, and teams.

Do I set CVC up in every worktree?

The database and your consent choices are shared across a repository's linked worktrees (they live in the common .git directory). You enable and bind each worktree separately, but they read and write the same history. Claude Code hooks are installed per checkout — a worktree created by Claude Code's own worktree option starts without them, so run cvc harness install claude-code there and start the session again.

Does CVC work with Claude Code?

Natively, from CVC 0.7.0, through Claude Code's lifecycle hooks (Transcript tier) — pick the Claude Code path above. MCP stays optional beside it for curated decision notes through commit_thought (Attested tier); both land in the same conversation list.

What exactly does CVC record from Claude Code?

One private thought per assistant response: the prompt or tool results it reacted to, exposed thinking as it appears in the transcript, the text, tool calls with their status, and the repository paths read or edited (subject to .thoughtignore). Tool output is size-bounded; unfamiliar content blocks are kept as named placeholders; subagent runs become separate conversations named <session>:agent-<id>, and each conversation carries Claude Code's session title. Claude Code deletes its own transcripts after its retention period; CVC's copy is already made.

How do I stop Claude Code capture?

cvc harness uninstall claude-code removes exactly the three hook entries from this checkout. The capture acknowledgement itself stays until you remove privacy.json by hand; there is no revoke command yet.

Can I install without npm or the marketplace?

Yes. Each GitHub release ships archives with cvc, cvc-mcp, and cvc-lsp. Verify against SHA256SUMS.txt, extract, and put them on PATH.

Is CVC open source?

The client is — Apache-2.0 on GitHub. The hosted review platform is a separate service built on the same open client.