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

> Shepherd runs an AI agent's work as a reversible, Git-like execution trace, so meta-agents can observe, fork, replay, and revert any run.

Published: 2026-07-06
URL: https://daniliants.com/insights/shepherd-reversible-git-like-execution-traces-for-ai-agents/
Tags: ai-agents, sandboxing, claude-code, agent-architecture

---

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