Shepherd: Programmable Meta-Agents via Reversible Execution Traces

Install | Quickstart | 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, released, or discarded.

Installation

Once the public package is published:

pip install shepherd-ai

For the current pre-launch checkout, install the local editable closure from the repository root:

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

The Python import is:

import shepherd as sp

The CLI is:

shepherd --help

Quickstart

Create a scratch project, initialize Shepherd's workspace-control substrate, run a deterministic retained-output demo, and inspect the resulting trace:

mkdir /tmp/shepherd-quickstart
cd /tmp/shepherd-quickstart

shepherd init --backend auto
shepherd demo write quickstart > quickstart_demo.py
python quickstart_demo.py

shepherd run list
shepherd run show --latest
shepherd run trace --latest --events
shepherd run changeset --latest

The demo registers a task, runs it through Shepherd's workspace-control world channel, stores the result as a retained workspace output, and releases that output explicitly. Add --json to read commands when you need the durable machine payload:

shepherd run show --latest --json

--backend auto asks Shepherd to select the available workspace carrier. If you need to be explicit, use --backend clonefile on macOS or --backend fuse / --backend kernel on Linux.

Python Surface

Shepherd's day-one public Python surface is deliberately small:

import shepherd as sp


@sp.task
def draft_release_note(component: str, change: str) -> str:
    return f"{component}: {change}"


sp.workspace(model={"name": "offline-demo"}, root=".")
print(draft_release_note("world channel", "retained outputs are inspectable"))

For provenance-backed workspace runs, open an initialized workspace:

import shepherd as sp

workspace = sp.open(".")
try:
    repo = workspace.git_repo()
    # Register and run workspace-control tasks against repo handles.
finally:
    workspace.close()

Optional Claude Lane

On a host with native jail support, the local claude CLI, and ANTHROPIC_API_KEY:

shepherd doctor claude --backend auto
shepherd demo write claude-readme > claude_readme.py
python claude_readme.py

This lane uses runtime={"provider": "claude"} through the same retained-output workspace-control path. It is optional and not required for the deterministic quickstart.

Examples

Checked-in quickstart examples live in:

• examples/quickstart/offline_task.py
• examples/quickstart/world_channel.py
• examples/quickstart/claude_readme.py

The visual-artifact notebooks live in:

• examples/notebooks/visual_artifact/notebooks/

Launch them with:

make notebooks

Development

Useful local gates:

make dev-install
uv run pytest integration-tests/test_quickstart_core.py -q
make baseline

Documentation

Full documentation lives at docs.shepherd-agents.ai. In this repository the docs are authored under docs/shepherd/:

• Quickstart guide
• Runtime substrate and the world channel
• Concepts — tasks, effects, scopes, permissions, and the trace
• Examples

Reproducing Paper Results

The full experiment code — the meta-agent applications and the framework-performance microbenchmarks — lives in a companion repository: shepherd-agents/shepherd-experiments. It bundles the frozen substrate snapshot used for the paper, so the numbers stay reproducible against the exact version that produced them.

Citation

@misc{yu2026shepherdenablingprogrammablemetaagents,
      title={Shepherd: Enabling Programmable Meta-Agents via Reversible Agentic Execution Traces},
      author={Simon Yu and Derek Chong and Ananjan Nandi and Dilara Soylu and Jiuding Sun and Christopher D Manning and Weiyan Shi},
      year={2026},
      eprint={2605.10913},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2605.10913},
}

License

This project is licensed under the MIT License — see the LICENSE file for details.