agentvc

Why agentvc

Git was built for humans committing at human pace. AI agents mutate your workspace at machine pace: dozens of files per minute, wrong turns, half-finished refactors, deletions you never asked for. By the time you notice, git stash isn't going to save you.

agentvc gives every agent session a time machine. It snapshots the entire workspace in milliseconds, forks parallel attempts onto branches, and restores any previous state instantly — with zero data loss by design.

Related MCP server: statecli-mcp-server

Features

Why not just git?

agentvc doesn't replace git for shipping code. It sits underneath the agent loop: cheap, disposable, rewindable history that never pollutes your git log.

Requirements

Node.js 20 or newer. No other runtime dependencies.

Install

npm install -g agentvc

Or run it without installing:

npx agentvc init

Quickstart

mkdir demo && cd demo
avc init                              # initialise .avc/

echo "v1" > app.txt
avc save -m "known good state"        # checkpoint everything

echo "v2" > app.txt                   # ...agent goes wrong...
avc status                            # see what changed
avc diff -p                           # see exactly which lines changed
avc rollback HEAD                     # instant undo — nothing lost

avc branch plan-b && avc switch plan-b   # fork a parallel attempt
avc save -m "trying redis instead"
avc timeline                          # every attempt, side by side

Give your agent a time machine

Register the bundled MCP server once and your agent can checkpoint and recover on its own.

Claude Code

claude mcp add agentvc -- avc mcp

Cursor · Codex · any MCP client — add to .mcp.json (or see examples/mcp-config.json):

{
  "mcpServers": {
    "agentvc": { "command": "avc", "args": ["mcp"] }
  }
}

Set AVC_ROOT=/path/to/project if the server shouldn't use its working directory.

Checkpoint automatically

You don't have to rely on the agent remembering. Pick one (or both):

avc hook claude --install      # Claude Code: checkpoint after every agent turn
avc hook claude --install --on-edit   # ...and after every Edit/Write tool call
avc watch                      # any agent: checkpoint whenever files stop changing for 2s

avc hook claude merges a Stop hook running avc save --auto into .claude/settings.json (re-running it is a no-op). avc save --auto only writes a checkpoint when something actually changed, so history never fills with duplicates; avc log --no-auto hides automatic entries. Other agents can call the same command from their own hook or post-turn script.

Teach it when to checkpoint

Even with hooks on, a short note in your AGENTS.md / CLAUDE.md makes checkpoints meaningful rather than merely frequent:

## Session checkpoints (agentvc)

- Before any risky operation (refactors, deletions, dependency upgrades,
  schema changes), call `avc_save` with a short message.
- After reaching a working state, call `avc_save` again.
- If an approach fails twice, call `avc_rollback` to the last good checkpoint
  and try a different plan — optionally on a new branch via `avc_branch`.
- Never leave more than ~15 minutes of work uncheckpointed.

MCP tools

CLI reference

Refs accept HEAD, a branch name, a full checkpoint id, or any unique id prefix.

avc diff -p prints standard unified diffs (--- a/path, +++ b/path, @@ hunks), so the output pipes straight into patch -p1 or git apply. Binary files are reported as Binary files … differ; files over 2 MB / 50,000 lines are listed without contents, and rewrites too large for an exact line diff are shown as a whole-file replacement.

Use it as a library

import { AgentVCS, formatPatch } from "agentvc";

const avc = new AgentVCS(projectRoot);
await avc.ensureInit();

const cp = await avc.save({
  message: "before db migration",
  meta: { task: "upgrade-postgres", attempt: 2 },
});

const { clean, modified } = await avc.status();
if (!clean) console.log("agent touched:", modified);

await avc.branch("plan-b");
await avc.checkout("plan-b");

await avc.rollback(cp.id);   // instant, lossless

for (const p of await avc.diffPatch(cp.id, "work")) {
  console.log(formatPatch(p));   // unified diff per file, with hunks available on p.hunks
}

Fully typed. AgentVCS, watchWorkspace, diffTrees, computePatch, formatPatch, and all result types are exported.

How it works

Content-addressed storage, git's good idea without git's ceremony:

.avc/
├── objects/ab/c3ef…      blobs + trees, deduplicated by SHA-256
├── checkpoints/          parents, tree, message, structured meta
├── refs/heads/main       branch tips
└── index.json            id → summary, for fast prefix lookups

• Identical file content is stored once, across every checkpoint and branch.

• Unchanged files are never rewritten on restore.

• Your existing .gitignore is respected; .git/ and node_modules/ are skipped.

• Delete .avc/ and your workspace is untouched.

Roadmap

• Line-level diffs in the terminal (avc diff -p)

• Branch merging (fast-forward today, 3-way next)

• Auto-save hooks: on file watcher, or after each agent turn

• Multi-agent coordination — two agents, one repo, separate branches

• Named milestones and session tags

• Python SDK with MCP parity

• Optional encrypted remote backup of the checkpoint store

Ideas and PRs welcome — see CONTRIBUTING.md.

Contributing

git clone https://github.com/nintechio/agentvc.git
cd agentvc && npm install
npm run typecheck && npm test && npm run build

Bug reports, feature requests, and pull requests are all welcome. Please read CONTRIBUTING.md and our Code of Conduct. Security issues: see SECURITY.md.

License

MIT © Nintech Ltd

Built and maintained by Nintech

The engineers who build it also run it.

Applied AI · resilient software engineering · managed hosting — UK & EU

nintech.io · GitHub · X · YouTube · admin@nintech.io