Self-hosted service
shepherd-agents/shepherd avatar
shepherd-agents/shepherd

Shepherd records an agent run as a trace and settles it with select, apply, or discard

A runtime substrate that turns an agent's execution into a reversible, Git-like trace, so meta-agents can observe, fork, replay, and revert any run. Couples agent and environments in a copy-on-write fork ~5x faster than docker commit, with ~95% KV-cache reuse on replay. Framework built for meta-agents to supervise, optimize, and train other agents

2,637 stars227 forksPythonMIT

At a glance

What is it?
Shepherd makes an agent task a Python function whose signature is its permission grant, runs it inside an OS level jail on macOS or Linux, and holds the produced file to one side until you accept it. The permission model is precise, the packaging tells two different stories, and the two headline speed numbers have no benchmark in reach.
Who is it for?
Shepherd fits teams whose real problem is that agent runs leave nothing behind to inspect, and who can live with a host restricted to macOS, Linux, or WSL, grants that apply per bound repository rather than per file, and a model default written only as a comment.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 67 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • shepherd-agents/shepherd2,637 ★ · +201
Star history
Repository2026-09-222026-11-15
shepherd-agents/shepherd2.4k2.6k

201 Stars in the last 54 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The signature is the permission surface

Every task is a plain Python function with no body at all. What the agent receives is the signature and the docstring, and those two are the contract it fulfils when it runs:

python
def write_program(
    repo: sp.GitRepo,
    prompt: str,
    output_path: str = "program.py",
) -> None:
    """Write a small, self-contained Python program that does what `prompt` asks.

    Save it to output_path. It must run with plain `python3`, read no input,
    and finish on its own within about ten seconds.
    """

The first parameter is the one that matters. `repo: sp.GitRepo` is an explicit grant of a writable workspace handle, declared in the type annotation rather than passed in as data. Remove the annotation and the same name becomes an ordinary value parameter the agent receives and may do nothing with. Authority lives in the type, not in a config file.

Grants can also be declared per bound repository, which is what you want when one task reaches into more than one tree:

python
from shepherd import task, May, GitRepo, ReadOnly, ReadWrite

@task
def apply_documented_fix(
    docs:    May[GitRepo, ReadOnly],   # read-only: writes refused at the OS
    backend: May[GitRepo, ReadWrite],  # writable root
    issue:   str,
) -> None: ...

`shepherd task show` renders that signature expanded, so the permission surface can be read without launching a run. What it will not show is a middle setting. `ReadOnly` and `ReadWrite` are whole profile choices applied to a binding, so a bound repository is entirely writable or entirely read only. A task that needs to edit one file inside an otherwise read only tree has no third answer to give it.

Grants compile to a syscall jail rather than a merge gate

On a jailed device each grant is compiled into that run's writable roots and enforced at the native syscall layer: Seatbelt on macOS, Landlock on Linux inside a privileged container. A write aimed at a `ReadOnly` repository, or at any managed path no `ReadWrite` grant covers, is refused by the platform rather than by Python, and it is refused before the last undo point. Nothing has to be inspected after the fact in order to notice.

Windows is out of scope, and the stated reason is worth keeping: enforcement there would be advisory only at best, which would collapse the whole signature based model into documentation. The supported route is WSL.

Which tree a grant applies to comes from the binding:

python
ws.bind(root="backend/", name="backend")

Bindings are whole profile, so the same directory cannot be bound twice under two different profiles. That reads as a clean unit of access if your boundaries are already repository shaped, and it is a hard stop if you want to hand a task a writable copy of a tree plus a read only copy of the same tree, because the profile belongs to the binding rather than to the path inside it.

Host requirements are Python 3.11 or newer, plus a platform that can confine the process. The quickstart does put `shepherd doctor claude` between workspace creation and the first run, and that command reports on the CLI, the credential, and the sandbox together, so the environment does get a checkpoint. It is a command you remember to run, not something the task runner resolves for you.

Credential failures arrive dressed as the wrong error

The agent lane needs the `claude` CLI, either signed in or with an `ANTHROPIC_API_KEY`. On a subscription, a sandboxed run is stated to be most reliable with a long lived token:

bash
export CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token)

The reason is a genuine trap. A short lived signed in session cannot be refreshed from inside the sandbox, so the same setup can work when you invoke `claude` by hand and then fail under a Shepherd run. What fails is the credential, and what you see is something else.

Three distinct problems show up wearing a borrowed error. An organization policy rejection from Claude arrives as HTTP 403, which reads like a rejected login but is an account or organization limit, and a different key or the org admin is the fix. An outright hang of the `claude` CLI, a stale version for instance, surfaces as a budget timeout. A session that needs refreshing just fails partway through the run.

The preflight for all of that is:

bash
shepherd doctor claude    # confirm claude CLI, sign-in/key, and sandbox are ready

`shepherd doctor claude --probe` performs a real authentication round trip, and the docs place it deliberately: in the parent, not in a jailed run. That keeps the diagnostic out of the jail, which is the safe choice, and it also means the probe cannot reproduce the failure mode it exists to catch.

A run ends in a file you can pipe before it ends in your tree

Set up a scratch workspace, then let the agent work:

bash
mkdir /tmp/agent-task && cd /tmp/agent-task
shepherd init             # turn this directory into a Shepherd workspace
shepherd doctor claude    # confirm claude CLI, sign-in/key, and sandbox are ready
bash
shepherd demo write agent-task > agent_task.py
python agent_task.py

The agent writes `donut.py`, but not into your directory. It lands as a retained output, held to one side, and you can run it before applying anything:

bash
shepherd run changeset --latest --read donut.py | python3 -

That pipes the retained file straight into the interpreter, so the effect is visible with zero changes to the workspace. Whether you keep it or throw it away, the trace records the decision:

bash
shepherd run select <run-ref>     # keep it
shepherd run apply  <run-ref>     # ...or merge it onto a workspace that moved on
shepherd run discard <run-ref>    # ...or not

`apply` carries the only stated precondition of the three: it merges onto a workspace that moved on since the run, which is exactly the situation where a merge can conflict and exactly the case the retained output was meant to make reviewable. `run list` and `run show --latest` print status and the full record, and any read command accepts `--json` for a durable machine payload. The retention model is the part of this project with the most detail behind it in the quickstart, and it is the part that works with no key.

The offline lane keeps the machinery and drops the agent

No API key required, and the same retained output path runs against Shepherd's deterministic provider:

bash
mkdir /tmp/shepherd-quickstart && cd /tmp/shepherd-quickstart

shepherd init                                  # turn this directory into a workspace
shepherd demo write quickstart > quickstart_demo.py
python quickstart_demo.py                      # register + run a task, retaining its result

shepherd run list                              # the run and its status
shepherd run changeset --latest                # what it wrote, kept as a retained output

The agent lane is the only thing removed here. Registration, execution, retention, and the inspect commands are unchanged, which makes this the cheapest way to decide whether the trace model is the thing you wanted before spending anything on credentials or a subscription.

Backend selection and the complete `run` surface are pointed at an external documentation site rather than kept in the tree, so the offline path is also the path where the repo tells you the least. Examples under `examples/` fill part of that gap, with `quickstart/`, `workspace-handles/` for the binding syntax, `notebooks/`, and `citation-checker/`, which matches the v0.3.1 release note about citation checking becoming a packaged workflow.

shepherd-ai on PyPI, shepherd-workspace on disk

The one line install is `pip install shepherd-ai`. Working on the project itself means a different closure:

bash
python -m venv .venv && . .venv/bin/activate && pip install -r requirements-dev.txt

The distribution and the project file disagree about what the thing is called. `pyproject.toml` declares `name = "shepherd-workspace"` at `version = "0.3.1"`, which lines up with the v0.3.1 tag, while the package people install is `shepherd-ai`. That gap is ordinary for a monorepo publishing a facade, and the practical effect is that the version in the tree is not the version that tells you what you have installed.

Almost nothing in that project file is fetched. Every runtime dependency is a workspace member resolved from the local tree: `shepherd`, `shepherd-core`, `shepherd-runtime`, `shepherd-providers`, `shepherd-contexts`, `shepherd-sandboxes`, `shepherd-authoring`, `shepherd-transform`, `shepherd-export`, `shepherd-banking`, `shepherd-coding`, `shepherd-citation-checker`, `shepherd-tests`, `shepherd-kernel-v3-reference`, plus `vcs-core` and `commons-vcs`. Test tooling sits in the same list as runtime, including `pytest-xdist`, `pytest-asyncio`, `hypothesis` for property based testing, and `RestrictedPython` for secure task reconstruction tests, so a development install and a plain install resolve to nearly the same tree.

Two constraints carry their own comments. `ruff` is held below 1.0.0 so that `uv run ruff` resolves to the locked workspace tool instead of whatever sits on PATH. `pyyaml` is required for eval scenario generation, which nothing in the quickstart ever shows. The notebook group, holding `jupyterlab`, `ipykernel`, and `shepherd-trace-viewer`, is kept out of core runtime dependencies on purpose, so a plain framework install does not pull in JupyterLab.

The version also sets expectations. The README opens with an early alpha banner saying APIs may still change between releases, and 0.3.1 with three published tags is consistent with that.

The sample env file still answers to ai-runner

The environment sample at the repository root calls itself the ai-runner configuration, and every variable in it carries that prefix:

code
# ai-runner environment configuration
# Copy this file to .env and fill in the values

# Required: Anthropic API key for Claude interactions
ANTHROPIC_API_KEY=sk-ant-api03-...

# Optional: Default model to use (defaults to claude-sonnet-4-20250514)
# ANTHROPIC_MODEL=claude-sonnet-4-20250514

# Optional: Maximum budget per run in USD (defaults to no limit)
# AI_RUNNER_MAX_BUDGET_USD=10.0

# Optional: Run root directory for storing run records (defaults to .runs)
# AI_RUNNER_RUN_ROOT=.runs

Three things follow from this file. The configuration surface still answers to a runner that is not the name anything is published under. Run records default to `.runs` inside your own workspace, a location none of the retention commands above mentioned, so traces and retained outputs are not guaranteed to sit in the same directory and nothing in the quickstart connects them.

The model default, claude-sonnet-4-20250514, exists only as a comment, so no code pins it and nothing will tell you when it stops being current. The budget line is commented out and its stated default is no limit, which makes the only cost ceiling on a run one you add yourself before the first expensive mistake. And the key is a placeholder showing the `sk-ant-api03-` prefix, useful as an illustration of the shape and not a template for anything else.

Because the file sits at the root next to `.gitignore` and `.pre-commit-config.yaml`, the settings a run depends on are documented in the repository while their actual values are expected to live in a copy nobody commits.

Two VCS cores, two Shepherd generations, one v3 reference kernel

The repository root carries `shepherd/`, `shepherd2/`, `vcs-core/`, and `commons-vcs/` side by side, alongside `packaging/`, `experiments/`, `integration-tests/`, `containers/`, `commons-vcs/`, and a `check_paper.py` sitting near `CONTRIBUTING.md` and `SECURITY.md`. The published dependency list names both `vcs-core` and `commons-vcs`, and the lint targets in the Makefile walk `shepherd/packages/*/src`, `shepherd2/src`, `vcs-core/packages/*/src`, and `commons-vcs/src` as four separate roots.

One of those runtime dependencies is `shepherd-kernel-v3-reference`. It sits in the install path rather than a development extra, so anyone who installs the framework gets a dependency whose name marks it as a reference implementation. There is a second Shepherd generation in the tree and two version control cores, both of which the workspace members list treats as first class.

Release cadence is quick. v0.2.1 and v0.3.0 landed two days apart in July 2026, and v0.3.1 arrived on 2026-09-09, the same day as the last push to the repository. Feature scope is also visible in the dependency names: `shepherd-banking`, `shepherd-coding`, and `shepherd-citation-checker` are packaged workflows living beside the runtime, which is what turns the generic task model into a specific tool rather than a substrate.

The build surface is a plain Makefile whose default target is install, with separate phony targets for lint, format, typecheck, and about a dozen per package test targets. There is a `lock-check` and a `verify` target, so the uv lock is treated as something to police rather than regenerate casually.

Editorial conclusion

Shepherd fits teams whose real problem is that agent runs leave nothing behind to inspect, and who can live with a host restricted to macOS, Linux, or WSL, grants that apply per bound repository rather than per file, and a model default written only as a comment. Verify three things before building on it: the project's own description claims a copy-on-write fork about 5x faster than docker commit and about 95% KV-cache reuse on replay, and nothing in the quickstart produces either number; cost has no default ceiling, since the sample environment file leaves the budget variable unset; and a missing type annotation quietly turns a permission grant back into an ordinary value. Anyone who needs per-path controls, a Windows host, or a dependency graph with one version line should look elsewhere.

Frequently asked questions

Does Shepherd need an Anthropic API key to run a task?

Only the agent lane does, since it needs the `claude` CLI signed in or an `ANTHROPIC_API_KEY`. The offline quickstart needs neither and runs the same retained output machinery through Shepherd's deterministic provider.

Which operating systems can Shepherd enforce its grants on?

macOS through Seatbelt and Linux through Landlock inside a privileged container. Windows is unsupported because enforcement there would be advisory only, and the documented alternative is WSL.

How does Shepherd decide what an agent may write?

The task function's signature is the permission surface. A `repo: sp.GitRepo` parameter is a writable handle grant, `May[GitRepo, ReadOnly]` gets writes refused at the OS, and an unannotated `repo` parameter is just an ordinary value.

What happens to a file an agent writes before I accept it?

It is kept as a retained output instead of landing in your directory. You can read it with `shepherd run changeset --latest --read`, then settle the run with `shepherd run select`, `shepherd run apply`, or `shepherd run discard`.

Does Shepherd put a ceiling on what one run can cost?

Not by default. The sample environment file comments out `AI_RUNNER_MAX_BUDGET_USD` and states that the default is no limit, so a budget is something you set yourself before the first run.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. shepherd-agents/shepherd on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/shepherd-agents-shepherd.svg)](https://hysenlabs.com/projects/shepherd-agents-shepherd)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/shepherd-agents-shepherd.svg)](https://hysenlabs.com/projects/shepherd-agents-shepherd)

Was this useful?