Shepherd: reversible, Git-like execution traces for AI agents

My notes

Summary

Shepherd is an early-alpha Python framework that runs an AI agent’s work (including Claude Code sessions) as a durable, Git-like execution trace: every run’s file changes land as a “retained output” that nothing touches until it is explicitly selected, released, or discarded. It couples the agent to its environment so the whole pair can be copy-on-write forked roughly 5x faster than docker commit, and replaying or branching a run reuses about 95% of the KV-cache instead of re-decoding context from scratch.

Key Insight

• Tasks are contracts, not code. A Shepherd task is a plain Python function with no body, just a type-hinted signature and a docstring. The docstring is the prompt the agent fulfils; the signature’s type hints are the enforced permission surface.
• Permissions are OS-enforced, not code-reviewed. Repos are bound read-only or read-write per task (May[GitRepo, ReadOnly] vs ReadWrite), and violations are refused at the syscall layer (macOS Seatbelt, Linux Landlock; the Linux path is currently container-gated) before any undo point exists, not caught later at a merge/review gate.
• Outputs are staged, like Git. Nothing an agent writes touches your real files automatically. Each run’s changes are a “changeset” you inspect (shepherd run changeset --latest) and then explicitly select (keep) or discard (throw away). The trace remembers the decision either way.
• Performance numbers that matter for meta-agent workflows: copy-on-write forking the agent+environment pair together is ~5x faster than docker commit, and ~95% KV-cache reuse on replay means forking many exploratory branches of the same run is cheap rather than restarting inference from zero each time.
• Auth nuance for sandboxed runs: a short-lived interactive Claude sign-in session can’t be refreshed from inside the sandbox: it may work in a normal terminal but silently fail inside Shepherd. The fix is a long-lived token via claude setup-token exported as CLAUDE_CODE_OAUTH_TOKEN. shepherd doctor claude --probe checks which credential type you actually have before a run.
• The framework backs an arXiv paper (Yu et al., 2026, “Shepherd: Enabling Programmable Meta-Agents via Reversible Agentic Execution Traces”) with a companion shepherd-experiments repo that freezes the exact substrate snapshot used for the paper’s benchmarks, so the performance numbers stay reproducible against that specific version.