agentvc

Warum agentvc?

Git wurde für Menschen gebaut, die in menschlichem Tempo committen. KI-Agenten verändern deinen Workspace in Maschinengeschwindigkeit: Dutzende Dateien pro Minute, Irrwege, halb fertige Refactorings, Löschungen, um die du nie gebeten hast. Bis du es bemerkst, wird dich git stash nicht mehr retten.

agentvc gibt jeder Agenten-Sitzung eine Zeitmaschine. Es erstellt Schnappschüsse des gesamten Workspaces in Millisekunden, zweigt parallele Versuche auf Branches ab und stellt jeden früheren Zustand sofort wieder her — konstruktionsbedingt ohne Datenverlust.

Related MCP server: statecli-mcp-server

Funktionen

Warum nicht einfach git?

agentvc ersetzt git nicht beim Ausliefern von Code. Es sitzt unterhalb der Agenten-Schleife: günstige, wegwerfbare, zurückspulbare Historie, die dein git log nie verschmutzt.

Voraussetzungen

Node.js 20 oder neuer. Keine weiteren Laufzeitabhängigkeiten.

Installation

npm install -g agentvc

Oder führe es ohne Installation aus:

npx agentvc init

Schnellstart

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

Gib deinem Agenten eine Zeitmaschine

Registriere den mitgelieferten MCP-Server einmal und dein Agent kann eigenständig Checkpoints setzen und wiederherstellen.

Claude Code

claude mcp add agentvc -- avc mcp

Cursor · Codex · beliebiger MCP-Client — füge ihn zu .mcp.json hinzu (oder siehe examples/mcp-config.json):

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

Setze AVC_ROOT=/path/to/project, wenn der Server nicht sein Arbeitsverzeichnis verwenden soll.

Bring ihm bei, wann ein Checkpoint gesetzt werden soll

Lege das in deine AGENTS.md / CLAUDE.md — es ist der Unterschied zwischen einem netten Tool und einem echten Sicherheitsnetz:

## 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-Referenz

Refs akzeptieren HEAD, einen Branch-Namen, eine vollständige Checkpoint-ID oder ein beliebiges eindeutiges ID-Präfix.

avc diff -p gibt standardmäßige Unified Diffs aus (--- a/path, +++ b/path, @@-Hunks), sodass die Ausgabe direkt in patch -p1 oder git apply übernommen werden kann. Binärdateien werden als Binary files … differ gemeldet; Dateien über 2 MB / 50.000 Zeilen werden ohne Inhalt aufgelistet, und Umschreibungen, die zu groß für einen exakten Zeilen-Diff sind, werden als kompletter Dateiaustausch angezeigt.

Als Bibliothek verwenden

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
}

Vollständig typisiert. AgentVCS, diffTrees, computePatch, formatPatch und alle Ergebnistypen werden exportiert.

So funktioniert es

Inhaltsadressierter Speicher – gits gute Idee ohne gits Zeremonie:

.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

• Identischer Dateiinhalt wird nur einmal gespeichert, über jeden Checkpoint und Branch hinweg.

• Unveränderte Dateien werden bei einer Wiederherstellung nie neu geschrieben.

• Deine bestehende .gitignore wird respektiert; .git/ und node_modules/ werden übersprungen.

• Lösche .avc/ und dein Workspace bleibt unberührt.

[!IMPORTANT] Die Sicherheitsgarantie. Jeder rollback- und switch-Vorgang sichert deine ungespeicherten Änderungen in einem automatischen Sicherheits-Checkpoint, bevor auch nur eine einzige Datei angefasst wird. Ein Rollback ist umkehrbar. In agentvc gibt es keinen Codepfad, der deine Arbeit verlieren kann.

Roadmap

• Zeilenweise Diffs im Terminal (avc diff -p)

• Branch-Merging (heute Fast-Forward, als Nächstes 3-Wege-Merge)

• Auto-Save-Hooks: bei Datei-Watcher oder nach jedem Agenten-Schritt

• Multi-Agenten-Koordination — zwei Agenten, ein Repo, getrennte Branches

• Benannte Meilensteine und Session-Tags

• Python-SDK mit MCP-Parität

• Optional verschlüsseltes Remote-Backup des Checkpoint-Speichers

Ideen und PRs willkommen — siehe CONTRIBUTING.md.

Mitwirken

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

Fehlerberichte, Feature-Wünsche und Pull Requests sind alle willkommen. Bitte lies CONTRIBUTING.md und unseren Code of Conduct. Sicherheitsprobleme: siehe SECURITY.md.

Lizenz

MIT © Nintech Ltd

Entwickelt und gepflegt von Nintech

Die Ingenieure, die es bauen, betreiben es auch.

Angewandte KI · resilientes Software-Engineering · Managed Hosting — UK & EU

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