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
- Install it with
pip install shepherd-aion Python 3.11 or newer. - Create a scratch folder and run
shepherd initto turn it into a workspace. - Run
shepherd doctor claudeto check the Claude CLI, sign-in, and sandbox are ready. - Fetch the demo with
shepherd demo write agent-task > agent_task.py, then runpython agent_task.py. - 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.
Ranking history
Official links
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.