agentvc

Por qué agentvc

Git se creó para que los humanos hicieran commits a un ritmo humano. Los agentes de IA mutan tu espacio de trabajo a velocidad de máquina: decenas de archivos por minuto, giros equivocados, refactorizaciones a medio terminar, eliminaciones que nunca pediste. Para cuando te das cuenta, git stash ya no te va a salvar.

agentvc le da a cada sesión de agente una máquina del tiempo. Hace una instantánea de todo el espacio de trabajo en milisegundos, bifurca intentos paralelos en ramas y restaura cualquier estado anterior al instante — con cero pérdida de datos por diseño.

Related MCP server: checkpointer

Características

¿Por qué no solo git?

agentvc no reemplaza a git para publicar código. Se sitúa debajo del bucle del agente: un historial barato, desechable y que se puede rebobinar que nunca contamina tu git log.

Requisitos

Node.js 20 o superior. No tiene otras dependencias de runtime.

Instalación

npm install -g agentvc

O ejecútalo sin instalarlo:

npx agentvc init

Inicio rápido

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

Dale a tu agente una máquina del tiempo

Registra una vez el servidor MCP incluido y tu agente podrá crear puntos de control y recuperarse por su cuenta.

Claude Code

claude mcp add agentvc -- avc mcp

Cursor · Codex · cualquier cliente MCP — añádelo a .mcp.json (o consulta examples/mcp-config.json):

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

Establece AVC_ROOT=/path/to/project si el servidor no debe usar su directorio de trabajo.

Enséñale cuándo crear puntos de control

Pon esto en tu AGENTS.md / CLAUDE.md: es la diferencia entre una herramienta bonita y una red de seguridad de verdad.

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

Herramientas MCP

Referencia de la CLI

Las refs aceptan HEAD, un nombre de rama, un id completo de punto de control o cualquier prefijo de id único.

avc diff -p imprime diffs unificados estándar (--- a/path, +++ b/path, fragmentos @@), de modo que la salida se pasa directamente a patch -p1 o git apply. Los archivos binarios se indican como Binary files … differ; los archivos de más de 2 MB / 50 000 líneas se listan sin contenido, y las reescrituras demasiado grandes para un diff de líneas exacto se muestran como un reemplazo del archivo completo.

Úsalo como biblioteca

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
}

Totalmente tipado. Se exportan AgentVCS, diffTrees, computePatch, formatPatch y todos los tipos de resultado.

Cómo funciona

Almacenamiento direccionado por contenido: la buena idea de git sin el ritual de git.

.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

• El contenido idéntico de los archivos se almacena una sola vez, en todos los puntos de control y ramas.

• Los archivos sin cambios nunca se reescriben al restaurar.

• Se respeta tu .gitignore existente; .git/ y node_modules/ se omiten.

• Elimina .avc/ y tu espacio de trabajo quedará intacto.

[!IMPORTANT] La garantía de seguridad. Cada rollback y switch crea una instantánea de tus cambios sin guardar en un punto de control de seguridad automático antes de tocar un solo archivo. Revertir es reversible. No hay ninguna ruta de código en agentvc que pueda perder tu trabajo.

Hoja de ruta

• Diffs a nivel de línea en la terminal (avc diff -p)

• Fusión de ramas (fast-forward hoy, 3-way después)

• Hooks de autoguardado: con file watcher, o después de cada turno del agente

• Coordinación multiagente: dos agentes, un repositorio, ramas separadas

• Hitos con nombre y etiquetas de sesión

• SDK de Python con paridad de MCP

• Copia de seguridad remota cifrada opcional del almacén de puntos de control

Las ideas y los PRs son bienvenidos — consulta CONTRIBUTING.md.

Contribuciones

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

Los informes de errores, las solicitudes de funcionalidades y los pull requests son bienvenidos. Por favor, lee CONTRIBUTING.md y nuestro Código de Conducta. Problemas de seguridad: consulta SECURITY.md.

Licencia

MIT © Nintech Ltd

Creado y mantenido por Nintech

Los ingenieros que lo construyen también lo operan.

IA aplicada · ingeniería de software resiliente · alojamiento gestionado — Reino Unido y UE

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