Our take
Newless than six months old- Activity
- 50
- Community
- 32
- Issues
- 21
- Pull requests
- 62
+155 stars in the last 30 days
Shepherd is a promising, actively released but early-alpha framework for teams that need reversible agent work, with adoption risk concentrated in a small contributor base.
Good fit if
- You are building Python agent workflows where proposed file changes must be inspected and settled explicitly.
- Your deployment targets macOS or Linux and can accommodate native sandbox enforcement, including a privileged container on Linux.
- You value a permissive MIT license and can work with an API that may change during alpha.
Look elsewhere if
- You need Windows-native OS-level permission enforcement, which Shepherd does not support.
- You need a mature project with a broader contributor base: it is less than six months old, and most contributions come from one person.
- Your workflow does not need retained, reversible traces or per-repository access grants.
All health signals
| Last commit | 2026-09-09 (2 months ago) |
|---|---|
| Commits, last 90 days | 6 |
| Releases, last 12 months | 5 (latest v0.3.1, 2026-09-09) |
| Contributors | 5 (top contributor: 79% of commits) |
| Issues closed, last 90 days | 0 |
| Pull requests merged, last 90 days | 6 (typically merged in 0 days) |
| Project age | 4 months |
Checked on 2026-11-03 with the GitHub API.
Project history
Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.
Stars
2,638Forks
227Change since Nov 16, 2026: +1 stars·0 forks
Overview
Shepherd is a Python runtime substrate built around Git-like execution traces and copy-on-write workspaces. It records agent work as durable, inspectable proposals, so teams can review, replay, fork, select, apply or discard changes instead of letting an agent modify files without a reversible record. Its permission model uses native OS enforcement on macOS and Linux.
It is aimed at developers building meta-agents or supervising agents that need to operate on code and other workspace files. The runtime is model-provider-independent in the README's framing; its quickstart demonstrates a sandboxed agent using the Claude CLI, while a deterministic provider supports an offline walkthrough.
Key Features
- Records agent runs as durable traces that can be inspected and replayed.
- Keeps workspace changes as retained proposals until a user selects, applies, releases or discards them.
- Supports copy-on-write forks of agent and environment state.
- Declares repository access in task signatures, including read-only and read-write grants per named repository binding.
- Enforces grants at the OS level with macOS Seatbelt or Linux Landlock in a privileged container.
- Provides a CLI and Python task framework, plus a deterministic offline demo.
Use Cases
- A developer can ask an agent to edit a repository, then inspect and test its proposed changes before applying them.
- A team building meta-agents can branch and replay executions to compare alternative agent actions.
- A maintainer can give an agent read-only access to documentation and write access to a separate code repository.
- Researchers can use the framework to supervise or train agents and reproduce paper experiments using the companion experiments repository.
What you need
Detected in the repository
- Python >=3.11 (from pyproject.toml)
- Automated checks on GitHub Actions
License in plain words
MITpermissive
- Commercial use: yes
- Modify and redistribute: yes
- You must keep: the copyright and license notice
- Share your changes: no
A summary, not legal advice: the LICENSE file is what applies.
Getting Started
Requires Python 3.11 or later. Install the package:
pip install shepherd-ai
See the README and documentation for setup, sandbox checks and examples.
Considerations
Shepherd is explicitly in early alpha, so APIs may change. The project is new, has a small contributor group with work concentrated mostly in one person, and has not closed issues in the measured recent period, despite recent commits, merged pull requests and releases. Treat its current pace as encouraging, not as evidence of long-term maintenance capacity.
OS-level grant enforcement is supported on macOS and Linux only; Linux enforcement runs in a privileged container, and Windows is unsupported. The README does not claim that every agent provider is built in: the Claude CLI quickstart requires suitable Claude credentials, while the deterministic provider is for an offline demo. The project uses the MIT license.
Found this useful?
Share it with someone who would like shepherd.