# shepherd-agents/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.

Source: https://github.com/shepherd-agents/shepherd
Indexed: commit 8e703a6 on 2026-07-08 by Repowise. Facts come from the source and git history, not from the maintainer.

## Facts

- Type: MCP server
- Language: Python
- Stars: 2,637 at index time
- License: MIT
- Code health: 7.8/10, Good
- Last commit: 2026-07-08

## Install

From the README: https://github.com/shepherd-agents/shepherd#installation

Clone the shepherd repository.
    git clone https://github.com/shepherd-agents/shepherd.git

Move into the shepherd folder.
    cd shepherd

Install Shepherd from PyPI.
    pip install shepherd-ai

Create a scratch directory and move into it.
    mkdir /tmp/shepherd-quickstart && cd /tmp/shepherd-quickstart

## How it 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.

- docs/_src/shepherd/tutorials/first_app/app.py: entry point
- docs/_system/run.py: entry point
- docs/shepherd/concepts/index.md: entry point
- docs/shepherd/guides/index.md: entry point
- docs/shepherd/index.md: entry point
Modules: shepherd, vcs-core, docs, shepherd2, commons-vcs, examples, integration-tests, root. 1,841 files, 378,878 lines, 27,182 symbols.

## Code health

- Score: 7.8/10 (Good)
- Rank: #81 of 4,000+ indexed repos
- Hotspots: shepherd/packages/dialect/src/shepherd_dialect/workspace_control/workspace.py, shepherd/packages/dialect/src/shepherd_dialect/providers.py, vcs-core/packages/core/src/vcs_core/_world_storage_manager.py, shepherd/packages/dialect/tests/test_providers.py, vcs-core/packages/core/tests/integration/session/test_seal_lifecycle.py
- Lowest file: vcs-core/packages/core/src/vcs_core/_vcscore_runtime.py
- Dead code: 173 findings

## Maintenance

- Last commit 2026-07-08
- bus factor 1

## Security

- Security findings are shown to signed-in users at https://repowise.dev/repo/shepherd-agents/shepherd/security

## More

- Page: https://repowise.dev/repo/shepherd-agents/shepherd
- Ask this codebase: https://repowise.dev/repo/shepherd-agents/shepherd/chat
- Docs: https://repowise.dev/repo/shepherd-agents/shepherd/docs
- MCP (signs in with Repowise on first use):
    claude mcp add --transport http repowise https://api.repowise.dev/mcp/shepherd-agents/shepherd
