Shepherd is a Python runtime substrate for meta-agents: agents that create, observe, and manage other agents. Every model action, tool call, and environment change in a run is recorded as a structured event in a Git-like execution trace, so a supervising agent can inspect a worker's run without perturbing it, intercept an action before it lands, fork a patched branch, or revert to any earlier state. The project is in early alpha, and its APIs may change between releases.
A task is a plain Python function with no body. Its signature and docstring are the contract an agent fulfills at runtime, and the task's implementation can be a sandboxed Claude agent. Work comes back as a retained output: a proposal held to one side that can be inspected and run, then selected, applied (three-way-merged onto a workspace that has moved on), released, or discarded. A deterministic provider runs the same machinery offline without an API key.
The signature is also the permission surface. Each bound repository is granted read-only or read-write access, and on macOS (Seatbelt) and Linux (Landlock) the grant is enforced at the system-call level, so a write outside the granted roots is refused before it happens. Windows is not supported.
The accompanying paper reports three meta-agent applications built on the substrate:
| Application | Reported result |
|---|---|
| Supervisor preventing conflicts among parallel coding agents | CooperBench pair-coding pass rate from 28.8% to 54.7% |
| Counterfactual workflow repair by replaying from changed behavior | 12.8% above MetaHarness on Terminal-Bench 2.0, with 58% lower wall-clock |
| Training meta-agent choosing fork points in RL rollouts | doubles GRPO's uplift on Terminal-Bench 2.0 |
| Reverting a past state | 5 times faster than docker commit and fork |
Features
- Reversible execution traces: every step of a run is a commit on a Git-like trace that can be forked or reverted
- Meta-agent operations: create, observe, intercept, fork, and revert a worker's execution from ordinary task code
- Tasks as contracts: a bodiless Python function whose signature and docstring define what the agent must deliver
- Retained outputs: agent work is held as a reviewable proposal and selected, applied, released, or discarded explicitly
- Per-repository grants: read-only or read-write access declared in the task signature
- OS-level enforcement: grants compiled to a syscall jail with macOS Seatbelt or Linux Landlock
- Offline provider: a deterministic provider exercises the same machinery with no model key
- Citation checker: an extra package that audits a paper's bibliography
