**Shepherd: Replaying Agent Runs from a Commit, Not a Transcript**
Long-running agents accumulate state that no transcript captures. A coding agent at step 10 holds 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, neither available recovery path is cheap: patching forward grows the context and the token bill, and restarting from step one re-pays every model and tool call while reproducing nothing exactly, because runs are non-deterministic. Jumping back to step eight is the option engineers actually want, and it is the one existing runtimes cannot offer.
Researchers at Northeastern University and Stanford University have released **Shepherd**, a Python runtime substrate that records an agent run as a Git-like trace of typed events, so any past state can be forked and replayed. The research team reports forks 5× faster than Docker and over 95% prompt-cache reuse on replay.
—
### Is it deployable?
Yes, but it is available in early alpha and not ready for production. Shepherd is MIT-licensed and installable with `pip install shepherd-ai` from PyPI. It requires Python 3.11+ and uses OS-level grant enforcement: macOS via Seatbelt and Linux via Landlock (in a privileged container).
**Target industries and applications:**
– **Industries:** Software engineering and DevOps, AI infrastructure and agent-platform vendors, quantitative finance research, security tooling and offensive-security research, and data engineering. The common trait is long-horizon agent runs against heavy sandbox state where a failed run is expensive to redo.
– **Applications:** Live supervision of coding agents with a meta-agent that can revert a bad write before it commits; automated recovery from wrong tool calls without a full restart; branching exploration over candidate agent strategies; and rollout generation for reinforcement learning with forking at selected turns.
—
### What Shepherd changes
Shepherd is a Python substrate that records an agent’s execution as a first-class object. Every agent-environment interaction becomes a typed event in a Git-like execution trace. Core operations are formalized as functions and mechanized in Lean.
Each interaction is effectively a commit. Unlike Git, the commit covers the agent process and the filesystem together, copy-on-write. A branch therefore carries live state, not just files. Returning to an earlier point is a single fork from that commit.
The research team reports that Shepherd forks the agent process and its filesystem **5× faster than Docker**. Because the prompt prefix through the branch point is unchanged, replay achieves **over 95% prompt-cache reuse**.
The framework is organized around four concepts:
– **Tasks:** Typed functions whose body the model fills in; the signature is the contract.
– **Effects:** Every crossing of the task boundary, which can be watched, answered, or refused.
– **Runs:** The durable record of those crossings.
– **Workspaces:** The runtime context for execution.
Permissions are declared in the signature (e.g., `May[GitRepo, ReadOnly]`), compiled to that run’s writable roots, and enforced at the native syscall jail.
Forking enables higher-order agents that observe a trace and intervene before a bad write commits. The team demonstrates three applications:
– **Runtime intervention:** A live supervisor raised pair-coding pass rates on CooperBench from **28.8% to 54.7%**.
– **Counterfactual meta-optimization:** Branching exploration beat baselines by up to **11 points** while cutting wall-clock time by up to **58%**.
– **Tree-RL training:** Forking rollouts at selected turns improved TerminalBench-2 from **34.2% to 39.4%**.
—
### Frequently Asked Questions
**Q: Is Shepherd production-ready?**
A: No. Shepherd is released as early alpha. It is research-grade software intended for evaluation and experimentation, not for production deployments.
**Q: What does “forking” mean in Shepherd?**
A: Forking creates a new branch from a past commit in the execution trace. The new branch includes a live copy of the agent process and its filesystem state, enabling fast, low-cost recovery or exploration without re-running earlier steps.
**Q: How does Shepherd improve prompt-cache reuse?**
A: Because forks start from a shared commit point, the prompt prefix up to the fork is identical. This enables over 95% prompt-cache reuse during replay, significantly reducing redundant token generation.
**Q: Which operating systems are supported?**
A: Shepherd supports Python 3.11+ on macOS and Linux. OS-level enforcement uses Seatbelt on macOS and Landlock on Linux (inside a privileged container).
**Q: What industries can benefit from Shepherd?**
A: Software engineering, DevOps, AI infrastructure, agent platform vendors, quantitative finance, security tooling, offensive-security research, and data engineering—anywhere long-horizon agent runs involve heavy sandbox state and expensive re-runs.
**Q: Can Shepherd prevent irreversible actions like sending an email?**
A: Forking cannot undo effects that have already reached the outside world. Shepherd’s approach is refusal rather than rollback: every crossing is an effect that handlers in scope can watch, answer, or refuse before it happens.
—
### Conclusion
Shepherd represents a fundamental shift in how agent executions are recorded and recovered. By treating agent runs as Git-like traces of typed events, it enables fast, low-cost forking and near-complete prompt-cache reuse—addressing a critical pain point for long-horiented agent workflows. While still in early alpha, its demonstrated improvements in pass rates, wall-clock efficiency, and exploration robustness highlight its potential to become a foundational substrate for safe, reversible, and efficient agent runtime systems.
