Researchers at Northeastern University and Stanford University have released Shepherd, an open-source Python substrate that records agent runs as a Git-like trace of typed events. This allows any past state to be forked and replayed, solving the problem where long-running agents accumulate state that transcripts cannot capture.
Is it deployable?
Shepherd is available in early alpha and not yet ready for production. It is MIT-licensed and installable via pip install shepherd-ai from PyPI. The system requires Python 3.11 or higher. OS-level grant enforcement runs on macOS using Seatbelt and on Linux via Landlock within a privileged container.
The tool targets software engineering, DevOps, AI infrastructure vendors, quantitative finance research, security tooling, and data engineering. The common trait is not the vertical, but the need for long-horizon agent runs against heavy sandbox state where a failed run is expensive to redo.
Applications include live supervision of coding agents, automated recovery from wrong tool calls without a full restart, and branching exploration over candidate agent strategies. Rollout generation for reinforcement learning also benefits from forking at selected turns.
What Shepherd changes
The system 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 acts effectively as a commit. Unlike Git, the commit covers the agent process and the filesystem together using 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 documentation organizes the framework around four concepts: tasks, effects, runs, and workspaces. A task is a typed function whose body the model fills in, so the signature is the contract. An effect is every crossing of the task boundary, and it can be watched, answered, or refused. A run is the durable record of those crossings.
Permissions are declared in the signature. A May[GitRepo, ReadOnly] binding is compiled to that run’s writable roots and enforced at the native syscall jail.
Once a run is forkable, a meta-agent can sit on top
Forking enables higher-order agents that observe a trace and intervene before a bad write commits. The research team demonstrates three applications:
- In runtime intervention, a live supervisor raised pair-coding pass rates on CooperBench from 28.8% to 54.7%.
- In counterfactual meta-optimization, branching exploration beat baselines across four benchmarks by up to 11 points, while cutting wall-clock time by up to 58%.
- In Tree-RL training, forking rollouts at selected turns improved TerminalBench-2 from 34.2% to 39.4%.
What it means
Engineers currently face a choice when an agent goes wrong: patch forward, which grows the context and token bill, or restart from step one, which is slow and non-deterministic. Shepherd offers a third option. It lets you jump back to step eight and resume exactly where you left off, preserving the live process and cache. This reduces wasted compute and makes debugging complex agent workflows significantly cheaper.
