Shepherd: Programmable Meta-Agents via Reversible Execution Traces

[!IMPORTANT] Shepherd is in early alpha and under active development. APIs may still change between releases. Feedback and issues are very welcome!

Install | Quickstart | Permissions | Examples | Docs | Citation

Shepherd is a runtime substrate for agent work that needs inspection, reversibility, and supervision. It records agent runs as durable, inspectable execution traces, with retained workspace outputs that can be reviewed before they are selected, applied, released, or discarded.

Platforms. Shepherd requires Python 3.11+. OS-level grant enforcement is executed on both macOS (Seatbelt) and Linux (Landlock, in a privileged container). Windows is unsupported (enforcement would be advisory-only at best) — use WSL.

Installation

pip install shepherd-ai

Working on Shepherd itself? Install the local editable closure instead: python -m venv .venv && . .venv/bin/activate && pip install -r requirements-dev.txt (see CONTRIBUTING.md).

Quickstart

Shepherd is an agent framework: a task's implementation can be a sandboxed agent, and its work comes back as a reviewable proposal — nothing touches your files until you accept it. Here the whole body of a task is a Claude agent.

Needs the claude CLI — signed in (a Claude subscription works) or with an ANTHROPIC_API_KEY. Neither? Jump to the Offline Quickstart — it runs anywhere, keyless.

On a subscription, a sandboxed run is most reliable with a long-lived token: export CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token). A short-lived signed-in session can't be refreshed from inside the sandbox, so it may work interactively yet fail here — shepherd doctor claude (add --probe for a real auth round-trip under Shepherd's config, in the parent — not a jailed run) tells you which credential you have before you run. If Claude returns an org-policy error (HTTP 403), that's an account/organization limit, not a login problem — a different key or your org admin is the fix. And an outright claude CLI hang (e.g. a stale version) surfaces as a budget timeout, not an auth error.

A task is a plain Python function with no body; the signature and docstring are the contract the agent fulfils at runtime — including its permissions: repo: sp.GitRepo is the explicit writable workspace-handle grant that lets the agent write the repository (see Permissions):

def write_program(
    repo: sp.GitRepo,
    prompt: str,