Long-running coding agents build up a lot of hidden state—edited files, a live development server, installed packages, and a warm prompt cache. When the agent misinterprets an error and overwrites a correct file, the only ways to recover are either to patch forward, which inflates the context and token cost, or to restart from step one, which re‑pays every model and tool call and cannot reproduce the exact non‑deterministic run. Engineers really want to jump back to a specific earlier step, but traditional version control only tracks files, not the live process or caches, so this rollback is impossible in current runtimes.
Shepherd is a Python runtime substrate that records every agent–environment interaction as a typed event in a Git‑like execution trace. Each event is effectively a commit that captures both the agent process and the filesystem together, using copy‑on‑weight semantics. Forking from any commit restores the exact process, open ports, installed packages, and reuses more than 95 % of the prompt cache, making recovery fast and cheap. Benchmarks show Shepherd forks the agent process and filesystem five times faster than Docker, and replay after a fork yields over 95 % prompt‑cache reuse.
Practical applications include a live supervisor that reverts a bad write before it is committed, automated recovery from a wrong tool call without a full restart, branching exploration of alternative agent strategies for comparison, and generating rollout data for reinforcement‑learning training by forking at selected turns. The system is MIT‑licensed, installable via pip, and works on Python 3.11+ with macOS Seatbelt or Linux Landlock sandbox enforcement.
Shepherd turns the expensive, nondeterministic redo of long agent runs into a lightweight, reversible operation, giving engineers the precise rollback they need while saving compute and money.
#AI #MachineLearning #DevOps #AgentFrameworks #Productivity #OpenSource