Getting started

Quickstart¶

Run an intentionally risky command, inspect its independent evidence, and remove only unchanged collateral while preserving the allowed edit.

Zero-touch in one line¶

For coding agents, agentdiff init compiles the canonical trust configuration and agentdiff wrap runs the full pipeline automatically:

agentdiff init
agentdiff wrap -- codex exec "Fix authentication timeout"

See Zero-touch automation for the AUTO / RETRY / HUMAN routing contract. The rest of this quickstart walks through the transaction primitives underneath.

1. Install from source¶

You need Python 3.14 (or 3.12+) and uv.

git clone https://github.com/kam6l/agentdiff.git
cd agentdiff
uv tool install .

2. Create a disposable project¶

mkdir agentdiff-quickstart
cd agentdiff-quickstart
agentdiff policy init

The generated agentdiff.yaml allows src/**, reviews dependency metadata, denies common secret paths, observes network-related state without blocking traffic, and enables bounded recovery backups.

3. Create the task¶

Save this as agent_task.py:

from pathlib import Path

Path("src").mkdir(exist_ok=True)
Path("src/parser.py").write_text("def parse(value):\n    return value.strip()\n")
Path("pyproject.toml").write_text('[project]\nname = "demo"\n')
Path(".env").write_text("API_TOKEN=demo-only\n")

The values are synthetic, but use only a disposable workspace for the walkthrough.

4. Run under observation¶

agentdiff run --task "Update the parser" -- python agent_task.py

The human summary now leads with the outcome:

Task completed

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

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

The process completed, but the transaction returns exit code 3 because a protected mutation was observed. Local mode records the write after execution; it does not intercept or block it.

5. Inspect and verify¶

Copy the run ID printed below the summary:

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

6. Recover only collateral¶

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

Expected result:

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

src/parser.py stays because policy allowed it. If a person or later process changed a collateral path, AgentDiff records a conflict and preserves the current path.