A coding agent at step ten is not a transcript. It is edited files, a running dev server, installed packages, and a warm prompt cache.
When it misreads a traceback and rewrites a file that was already correct, you have two bad options:
- Patch forward and watch the context window swell.
- Restart from step one and re-pay every model and tool call, knowing the rerun will not match exactly because agents are non-deterministic.
What you actually want is to jump back to step eight and branch from there.
Researchers at Stanford and Northeastern released Shepherd, an open-source Python substrate that treats agent runs like version control for live execution.
What Shepherd records
Every agent-environment interaction becomes a typed event in a durable trace. Core operations are formalized in a small algebraic-effects calculus (mechanized in Lean, if you care about proofs).
Plain English version:
| Git concept | Shepherd equivalent |
|---|---|
| Commit | Agent action + filesystem snapshot (copy-on-write) |
| Branch | Forked run with live process state |
| Checkout | Replay or resume from a past point |
| Diff | Inspect changeset before accepting output |
Unlike Git, a Shepherd commit covers the agent process and the filesystem together. A branch carries live state, not just files on disk.
Paper: Shepherd: A Runtime Substrate Empowering Meta-Agents.
Repo: lgs/shepherd on GitHub.
Why the economics matter
The research team reports numbers that matter for production agents:
| Metric | Reported result |
|---|---|
| Fork speed vs Docker commit | ~5x faster |
| KV-cache reuse on replay | >95% |
| CooperBench pair-coding (with live supervisor) | 28.8% → 54.7% pass rate |
That cache reuse line is the sleeper feature. Replaying from a branch point reuses the prompt prefix through the fork. You do not re-tokenize the entire conversation just to undo one bad tool call.
For client agents billed per million tokens, rewind beats retry.
Security: permissions at the syscall layer
Shepherd enforces repository grants with native jails:
- macOS Seatbelt
- Linux Landlock
A write to a path outside an explicit ReadWrite grant fails at the syscall, not at a merge gate you forgot to configure. Bindings are named per backend (ws.bind(root="backend/", name="backend")) and settled per run with select, release, or discard.
That is closer to how I want agent sandboxes to behave in regulated environments: permissions are readable before the run starts, not buried in prompt instructions.
Three applications the paper demos
- Live supervision — a meta-agent watches commits and intervenes before bad states merge.
- Post-hoc trajectory optimization — fork alternate branches from one real trace.
- Stateful RL — diverse rollouts from a single recorded run.
The CooperBench lift (28.8% → 54.7%) is the headline for teams shipping pair-coding agents. Supervision without rewind is mostly logging. Supervision with fork/replay is an control surface.
Minimal quickstart
Shepherd is early alpha (pip install shepherd-ai). Expect API churn.
mkdir /tmp/shepherd-quickstart && cd /tmp/shepherd-quickstart shepherd init shepherd demo write quickstart > quickstart_demo.py python quickstart_demo.py shepherd run list shepherd run changeset --latest
Inspect the durable payload:
shepherd run show --latest --json
Docs: docs.shepherd-agents.ai.
How Shepherd compares to other checkpoint approaches
The paper situates Shepherd against AgentGit, BranchFS, and AgentSPEX. Each puts checkpoints at a different layer:
| Approach | Checkpoint layer | Trade-off |
|---|---|---|
| AgentGit | LangGraph tools the agent calls | Agent must cooperate |
| BranchFS | Kernel filesystem branch() | OS-level, less agent-aware |
| AgentSPEX | DSL workflows | Language lock-in |
| Shepherd | Runtime substrate | Observes same events worker emits |
Shepherd's bet: couple environment state with execution state so meta-agents supervise without rewriting the worker harness.
Where I would use this in client work
Not everywhere. Shepherd shines when:
- Runs are long (dozens of tool steps)
- Mistakes are expensive to patch forward
- You need human review before outputs touch production files
Skip it when:
- Tasks are single-shot completions
- Your harness already has cheap idempotent retries
- You cannot run alpha infrastructure on a compliance-critical path
I would pilot on internal coding agents first, same as any new runtime.
Bottom line
Git made files reversible. Shepherd aims to make entire agent runs reversible.
That is not a science fair trick. It is a token bill and a reliability story. When your agent goes sideways on step nine of twenty, fork back, fix the plan, continue.
If you are designing agent fleets and want help pairing runtime primitives (checkpoints, sandboxes, eval gates) with your stack, book a free discovery call.