repowiserepowise

MCP server

shepherd-agents / shepherd

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,637stars on GitHubPythonMIT

This connects Repowise to shepherd-agents/shepherd's code. It does not install shepherd.

Repowise maps public repos from their source. Not affiliated with shepherd-agents. What is Repowise?

github.com/shepherd-agents/shepherdIndexed at 8e703a6

What is shepherd?

Shepherd is a runtime substrate for agent work that needs inspection, reversibility, and supervision. It records each agent run as a durable, inspectable execution trace, and the workspace outputs of a run are held as retained outputs that can be selected, applied, released, or discarded. Shepherd is written in Python and requires Python 3.11 or later. To install it, run git clone https://github.com/shepherd-agents/shepherd.git and follow the steps below. Its code health is 7.8 out of 10 (Good), ranked #81 of 4,000+ indexed repos. The last commit to shepherd was on Jul 8, 2026.

As of commit 8e703a6, indexed Jul 8, 2026. What it is comes from a model reading the README; the rest is measured from the source and git history, not from the maintainer.

For agentsshepherd.md

Repo facts: type, license, health, rank, contributors
shepherd facts
TypeMCP server
LicenseMIT
Code health7.8 / 10 (Good)
Health rank#81 of 4,000+ indexed repos
Last commitJul 8, 2026
Bus factor1
Size1,841 files, 378,878 lines

Install shepherd

Commands copied from the README

  1. 1Clone the shepherd repository.
    git clone https://github.com/shepherd-agents/shepherd.git
  2. 2Move into the shepherd folder.
    cd shepherd
  3. 3Install Shepherd from PyPI.
    pip install shepherd-ai
  4. 4Create a scratch directory and move into it.
    mkdir /tmp/shepherd-quickstart && cd /tmp/shepherd-quickstart

Releases on GitHub (latest v0.3.1, Sep 9, 2026)

Full install notes on GitHub

Explore shepherd

Ask about this code in your agent

This connects Repowise to shepherd's code. It does not install shepherd. To install shepherd, use the install steps.

Useful if you want to change or fork shepherd: your agent can ask how it is put together and get answers that cite its files.

Ask about shepherd

Answers come from shepherd's README and source, with the files they cite. Two free answers a day without an account.

Want this for your own codebase? Map your repo free

About this page

Get a page like this for your own codebase

Repowise built this map of shepherd-agents/shepherd from its source and git history. It parses every symbol, draws the dependency graph, scores each file's health from complexity, duplication, coverage and churn, finds hotspots and owners in the history, and writes documentation for every module. Your coding agent reads the same index over MCP, so its answers cite real files.

Free for 2 public repos, with a page like this one. No card. See how Repowise works

Prefer local? pip install repowise && repowise init indexes your own checkout, no account needed. Star Repowise on GitHub

shepherd-agents/shepherd FAQ

What is Shepherd?

Shepherd is a runtime substrate for agent work that needs inspection, reversibility, and supervision. It records agent runs as durable, inspectable execution traces that can be reviewed.

How does Shepherd work?

Shepherd runs each task inside a workspace and records the run as a trace. Outputs written by the run are kept as retained outputs that can be selected, applied, released, or discarded.

How do I install Shepherd?

Shepherd is installed from PyPI with pip install shepherd-ai. It requires Python 3.11 or later. See the install steps

What language is Shepherd written in?

Shepherd is written mainly in Python. Smaller parts are written in shell, Makefile, Dockerfile, JavaScript and C.

How is the Shepherd code organized?

Shepherd code is split into modules, the largest being shepherd with 1113 files, followed by vcs-core with 450 files and commons-vcs with 31 files. The shepherd module contains workspace control code under packages/dialect.

Who is Shepherd for?

Shepherd is for agent work that needs inspection, reversibility, and supervision. Its retained outputs let you review what an agent wrote before anything is applied to your files.

What license does Shepherd use?

Shepherd uses the MIT license, identified as MIT in its metadata.

Code health

7.7out of 10Good

Hotspots average 6.4, the place fixes pay off most.

On the leaderboards:#18 of 71 Python repos

Key features of shepherd

  • Records agent runs as durable, inspectable execution traces.
  • Keeps workspace outputs as retained outputs that can be reviewed before they are selected, applied, released, or discarded.
  • Lets a task declare read-only or read-write grants per bound repository in its signature.
  • Enforces write grants at the native syscall jail on macOS Seatbelt, with Linux Landlock enforcement gated by container use.
  • Applies a retained candidate onto a workspace that has moved on by three-way merge when the changes touch disjoint paths.

How shepherd-agents/shepherd works

Work enters through a task, which is a plain Python function whose signature declares per repository whether it has ReadOnly or ReadWrite access to a GitRepo. The shepherd module, the largest module with 1113 files, holds the Python surface, and shepherd/packages/dialect/src/shepherd_dialect/workspace_control/workspace.py is a hotspot file in its workspace control code, where bindings are created and runs are started. The vcs-core module, with 450 files, provides the version control layer, and vcs-core/packages/core/src/vcs_core/_world_storage_manager.py is a hotspot file in it that manages world storage. shepherd/packages/dialect/src/shepherd_dialect/providers.py is another hotspot file in the shepherd module, and the commons-vcs module is a separate package with its own pyproject.toml. On a jailed device, the grants of a run are compiled to its writable roots and enforced at the native syscall jail on macOS Seatbelt, while Linux Landlock enforcement is container-gated. The output of each run is kept per binding and settled once with select, apply, release, or discard.

The codebase has 1,841 files and 27,182 symbols in 12 modules, led by Python, Shell and Makefile. Code health is 7.7 out of 10, rated good.