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
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
| Type | MCP server |
|---|---|
| License | MIT |
| Code health | 7.8 / 10 (Good) |
| Health rank | #81 of 4,000+ indexed repos |
| Last commit | Jul 8, 2026 |
| Bus factor | 1 |
| Size | 1,841 files, 378,878 lines |
Install shepherd
Commands copied from the README
- 1Clone the shepherd repository.
git clone https://github.com/shepherd-agents/shepherd.git - 2Move into the shepherd folder.
cd shepherd - 3Install Shepherd from PyPI.
pip install shepherd-ai - 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)
Explore shepherd
- DocumentationModule-by-module documentation, written from the source.
- ArchitectureDependency graph, layers and third-party dependencies.
- Code healthEvery file's score and the findings behind it.
- CommitsEach commit's effect on code health.
- OverviewEverything else the index found: contributors, decisions, what changed this week.
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
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.
Maintain shepherd-agents/shepherd?
Claim this page, add a badge to the README, or re-index it.
Claim this page
Sign in with GitHub and we check that you are an admin or maintainer of shepherd-agents/shepherd. Then add a badge to the README that links readers here.
Add a badge to your README
Readers click through to this page and can ask shepherd's code a question. A badge also re-indexes the repo every week and marks you as the verified maintainer.
[](https://repowise.dev/repo/shepherd-agents/shepherd?src=badge_ask)Paste it at the top of README.md, under the title.
Added it already? Verify to get the mark now instead of tomorrow.
Need HTML or the larger health card? More formatsHide more formats
This badge as HTML
<a href="https://repowise.dev/repo/shepherd-agents/shepherd?src=badge_ask"><img src="https://api.repowise.dev/badge/wiki/shepherd-agents/shepherd.svg?label=ask" alt="repowise: Ask this codebase"></a>Code health card
The score, its change since the last index, and when it was measured. Follows the reader's light or dark theme.
<a href="https://repowise.dev/repo/shepherd-agents/shepherd?src=badge_card"><picture><source media="(prefers-color-scheme: light)" srcset="https://api.repowise.dev/badge/health/shepherd-agents/shepherd.svg?style=card&theme=light"><img src="https://api.repowise.dev/badge/health/shepherd-agents/shepherd.svg?style=card" alt="repowise code health" width="500" height="168"></picture></a>