Meet Shepherd: An Open-Source Python Substrate That Lets Meta-Agents Fork, Replay, and Revert Any Agent Run

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. Git versions files, not a live process or a cache. 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 needs Python 3.11+. OS-level grant enforcement runs on macOS (Seatbelt) and Linux (Landlock, in a privileged container).

• 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 not the vertical. It 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 reverting a bad write before it commits. Automated recovery from a wrong tool call, without a full restart. Branching exploration over candidate agent strategies, compared side by side. Rollout generation for reinforcement learning, 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 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.

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

Key Takeaways

• Shepherd records each agent-environment interaction as a typed event in a Git-like, forkable trace.
• A commit covers the agent process and filesystem together, so a rewind restores live state, not just files.
• Reported: 5× faster forks than Docker and over 95% prompt-cache reuse on replay.
• A live supervisor lifted CooperBench pair-coding pass rates from 28.8% to 54.7%.

Check out the Paper, GitHub, Experiments repo, Project page and PyPI. Also, feel free to follow us on Twitter and don’t forget to join our 150k+ML SubReddit and Subscribe to our Newsletter. Wait! are you on telegram? now you can join us on telegram as well.

Need to partner with us for promoting your GitHub Repo OR Hugging Face Page OR Product Release OR Webinar etc.? Connect with us

Michal Sutter is a data science professional with a Master of Science in Data Science from the University of Padova. With a solid foundation in statistical analysis, machine learning, and data engineering, Michal excels at transforming complex datasets into actionable insights.