Shepherd treats agent runs like Git branches you can rewind

What it does

Shepherd is a Python runtime that wraps agent tasks in durable execution traces. You define a task as a Python function signature—no body needed—and the agent fills it in inside a sandbox. The result lands as a retained output, a proposal held to one side that you can review, run, apply, or throw away without polluting your workspace. It is built to let meta-agents supervise, optimize, and train other agents by observing and rewinding their runs.

The interesting bit

The clever part is that the function signature itself is the permission surface. Declaring a parameter as May[GitRepo, ReadOnly] or ReadWrite compiles down to OS-level syscall jails—Seatbelt on macOS, Landlock on Linux—so a write to the wrong repository is blocked at the kernel, not caught later at a merge gate. Grants are whole-profile per binding, and the README notes that sub-root path grants are not yet part of this alpha cut.

Key highlights

• Every agent run produces a durable, inspectable trace with retained outputs you can accept, merge, or discard.
• Permissions are derived from Python type signatures and enforced natively at the syscall level on macOS (Linux enforcement is currently container-gated).
• Supports both Claude-code agent lanes and a fully offline, deterministic provider that needs no API keys.
• Requires Python 3.11+; Windows is unsupported (advisory-only at best, use WSL).
• Companion repository contains the frozen substrate and experiments from the arXiv paper for reproducibility.

Caveats

• The project is early alpha and explicitly warns that APIs may change between releases.
• OS-level grant enforcement is fully exercised only on macOS; Linux uses Landlock inside a container, and Windows is out of scope.

Verdict

Worth a look if you are building meta-agents or simply want a safety net around autonomous code generation. Skip it if you need production-stable APIs or native Windows support.