shepherd-agents

shepherd: Supervise Agents with Reversible Git-Like Traces

Shepherd is a Python runtime for supervising agent work through durable, reversible Git-like execution traces. It retains outputs for review, replay, selection or discard, with OS-enforced permissions on macOS and Linux; Windows is unsupported.

Stars
2.5k
Forks
219
Stars, last 30 days
+155
Last commit
2 months ago
Contributors
5

Our take

Newless than six months old

Health score

41/100

How it is scored
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 commit2026-09-09 (2 months ago)
Commits, last 90 days6
Releases, last 12 months5 (latest v0.3.1, 2026-09-09)
Contributors5 (top contributor: 79% of commits)
Issues closed, last 90 days0
Pull requests merged, last 90 days6 (typically merged in 0 days)
Project age4 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.

Selected snapshot

Stars

2,638

Forks

227

Change 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.

Comparisons