Shepherd is a Python runtime substrate for agent work that needs inspection, reversibility, and supervision. It records each agent run as a durable execution trace in which every model action, tool call, and environment change is a first-class object, and it retains the run's workspace output as a proposal that you review before selecting, applying, releasing, or discarding it. Nothing touches your files until you accept the result.
A task is a plain Python function whose signature and docstring form the contract an agent fulfils at runtime; the body can be a sandboxed Claude agent invoked through the claude CLI, or a deterministic provider for keyless offline runs. Parameters typed as GitRepo, or May[GitRepo, ReadOnly] and May[GitRepo, ReadWrite], declare the permission surface per bound repository. On a jailed device those grants are enforced at the OS syscall layer (macOS Seatbelt, Linux Landlock), so a write outside a ReadWrite grant is refused before it happens rather than caught at a merge gate.
The same substrate supports meta-agents: higher-order agents that create, observe, intercept, fork, and revert a worker's trace as ordinary task code. The accompanying paper applies it to runtime intervention, counterfactual optimization, and tree-search reinforcement learning. Shepherd requires Python 3.11+ and is in early alpha; Windows is unsupported except through WSL.
Features
- Reversible traces: every run is recorded as an inspectable execution trace that can be forked and reverted
- Retained outputs: agent writes land as proposals; select, apply, release, or discard them from the CLI or API
- Three-way apply: merges a candidate onto a workspace that has moved on when changes are path-disjoint
- Signature-as-permissions: GitRepo, ReadOnly, and ReadWrite annotations define what each task may touch
- OS-level jail: grants compiled to writable roots and enforced by Seatbelt on macOS and Landlock on Linux
- Agent lane: tasks whose body is a sandboxed Claude agent, with shepherd doctor claude to verify credentials and sandbox readiness
- Offline provider: a deterministic backend that exercises the same run machinery without an API key
- Meta-agent operations: runtime intervention, counterfactual optimization, and tree-search RL over worker traces
- Workspace CLI: shepherd init, run list, run show, run changeset, and task show, with --json output for machine consumption
