shepherd

shepherd is a Python framework that records agent runs as reversible traces, so developers can review, undo, or discard what an agent changed.

What it is good for

  • Reviewing an AI agent's file changes before accepting them
  • Undoing or discarding a coding agent's work after a run
  • Limiting which folders an AI agent can write to
  • Replaying and comparing agent runs to improve them

At a glance

Who it is for
Setup difficulty
Developer ยท Requires programming

Level 5 of 5. You need to write code to use it.

Cost
Free and open source
Type
Framework or SDK
Tasks
Works with
Claude, Git, macOS, Linux

How to get started with shepherd

  1. Install it with pip install shepherd-ai on Python 3.11 or newer.
  2. Create a scratch folder and run shepherd init to turn it into a workspace.
  3. Run shepherd doctor claude to check the Claude CLI, sign-in, and sandbox are ready.
  4. Fetch the demo with shepherd demo write agent-task > agent_task.py, then run python agent_task.py.
  5. Review the result with shepherd run changeset --latest --read donut.py, then keep or discard it.

From the project's own documentation. If a step does not match what you see, the official pages have the latest instructions.

Before you try it

  • It is in early alpha, so APIs may change between releases.
  • Windows is unsupported; use WSL.
  • The agent demo needs the claude CLI, signed in or with an ANTHROPIC_API_KEY.
  • An offline quickstart runs without an API key, using a deterministic provider.

Momentum

Rank this week
#25 in builder tools
Best rank
#25 week 46, 2026
Stars gained last week
+130
GitHub stars
2,637

GitHub numbers as of Nov 16, 2026. Updated weekly.

2,419 2,536 2,653 Sep 24, 2026 Nov 16, 2026
GitHub stars for shepherd: 2,435 on Sep 24, 2026, 2,637 on Nov 16, 2026. Source: GitHub.

Ranking history

First ranked in week 46, 2026.

Questions

Is shepherd free?
Yes. It is free and open source (MIT license).
Do I need to know how to code to use shepherd?
Yes. You need to write code to use it.
What does shepherd work with?
According to its own documentation, it works with Claude, Git, macOS, and Linux.
How do I get started with shepherd?
1. Install it with pip install shepherd-ai on Python 3.11 or newer. 2. Create a scratch folder and run shepherd init to turn it into a workspace. 3. Run shepherd doctor claude to check the Claude CLI, sign-in, and sandbox are ready. 4. Fetch the demo with shepherd demo write agent-task > agent_task.py, then run python agent_task.py. 5. Review the result with shepherd run changeset --latest --read donut.py, then keep or discard it.
What should I know before trying shepherd?
It is in early alpha, so APIs may change between releases. Windows is unsupported; use WSL. The agent demo needs the claude CLI, signed in or with an ANTHROPIC_API_KEY. An offline quickstart runs without an API key, using a deterministic provider.
What is shepherd good for?
Reviewing an AI agent's file changes before accepting them, undoing or discarding a coding agent's work after a run, limiting which folders an AI agent can write to, and replaying and comparing agent runs to improve them.

Similar agents to shepherd

  • claw-orchestrator

    Runs several coding agents behind one API and checks work with tests, rather than recording reversible traces.

  • Strands Agents

    Gives a ready-made agent loop for building agents, without focus on reversible traces or review.

  • Agent Development Kit (ADK)

    General code library to build, test, and deploy agents, not centered on undoable runs.

  • crewAI

    Builds teams of agents that split up multi-step work, with no focus on reverting runs.

  • Claude Code Action

    Runs Claude on GitHub pull requests and issues instead of a local sandboxed runtime.

  • headroom

    headroom is a library and proxy that shrinks tool outputs, logs, and files before they reach the AI model, cutting token costs for coding agent users.

Last updated Nov 16, 2026. Tracked since Oct 28, 2026. Parts of this summary required judgment because the source material was brief. Spotted an error? Tell us.