Skip to content
Documentation Overview

Getting started

AgentDiff Documentation

AgentDiff is a local-first runtime transaction system for AI-agent commands. It records what changed, evaluates every mutation against deterministic policy, explains the run's blast radius, and can selectively undo unchanged collateral.

Find anything quickly: press Ctrl K or / to open indexed documentation search. Use the arrow keys and Enter to open a result, or Escape to return to the page.

Capability boundary: the local runtime observes a subprocess; it is not a kernel sandbox. Use an explicit sandbox runtime when you need isolation or network enforcement. Read the trust model.

Start here

01 · Quickstart Record your first transaction

Initialize policy, wrap a real command, inspect the evidence, and safely recover collateral.

About 5 minutes → 02 · Mental model Understand the runtime

Learn what AgentDiff observes, what it can prove, and where enforcement begins and ends.

Read the runtime model → 03 · Governance Decide before you score

Give each path an allow, review, or deny result with exact rule provenance.

Write a policy → 04 · Recovery Undo only the collateral

Preserve allowed work and refuse to overwrite paths changed after the run.

See safe rollback → 05 · Agent memory Connect Claude, Codex, or Ollama

Retrieve verified run memory and route a bounded context pack through one explicit provider.

Explore Cortex →

The transaction loop

1Capture

Build a no-follow filesystem manifest and record the runtime baseline.

2Execute

Launch the explicit argv under local observation or a selected sandbox backend.

3Evaluate

Diff state, apply policy, score blast radius, and persist an integrity manifest.

4Recover

Conflict-check current state before restoring or removing eligible collateral.

Feature status

Status Implemented surface
Beta Local transactions, policy, capsules, verification, scoring, regular-file recovery, evidence memory, and Cortex provider routing
Experimental srt adapter, MCP policy hook, LangChain callback, and legacy evaluator
Planned Published packages, authenticated capsules, telemetry export, and a maintained hosted sandbox integration

There is no HTTP server, hosted dashboard, Docker backend, bundled sandbox, or claimed PyPI release.

A complete local run

The following shape is taken from a real repository run. AgentDiff reported a successful process exit, but denied the transaction because it created a protected environment file.

agentdiff run \
  --task "Update the parser" \
  -- python3 agent_task.py

Task completed

Expected changes:   1
Unexpected changes: 1
Protected changes:  1

Blast Radius: CRITICAL (81/100)
Recovery available: YES
Policy outcome: DENY

Status: denied (deny)
Mutations: 3
  deny   created  .env
  review created  pyproject.toml
  allow  created  src/parser.py

agentdiff inspect <run-id>
agentdiff verify <run-id>

Status: denied (deny)
Blast radius: 81/100
Capsule integrity: true

agentdiff rollback <run-id> --safe-only

Actions: 2
  removed  .env
  removed  pyproject.toml
Conflicts: 0
Skipped: 1

Choose your next path

  • Install AgentDiff — supported source installation and requirements. Installation →
  • Use the CLI — exact commands and flags implemented in v0.1.0. CLI reference →
  • Integrate a command or framework — use the transaction API, or the separately labeled experimental compatibility hooks. Integrations →
  • Connect an AI provider — use verified repository memory with Claude, Codex/OpenAI, or Ollama. Cortex →
  • Review the security boundary — explicit guarantees, observations, and non-goals. Security & limits →