shepherd-agents/shepherd

Shepherd is a framework for running AI agents in a way that can be inspected, undone, and reviewed before anything actually changes your files. When an agent completes a task, its work is not written directly into your project. Instead it comes back as a proposal that sits to one side, which you can look at, run, and only apply to your real files once you have decided you actually want it. The core idea is that a task is written as a plain Python function with no body at all. Its name, its parameters, and its docstring describe what the agent should do, and those parameters also define exactly what the agent is allowed to touch. For example, marking a parameter as a writable repository handle grants the agent permission to write to that specific location, while marking it read only means any attempt by the agent to write there is blocked at the operating system level, on both macOS and Linux. This means you can read a task's function signature and know precisely what it is and is not permitted to do, before it ever runs. Every agent run is recorded as a durable trace, so its outputs can be selected and merged in, applied on top of a workspace that has since changed, or discarded entirely, with the record kept either way. Shepherd includes an offline quickstart that needs no API key and runs the same underlying machinery using a deterministic built in provider instead of a real AI model, useful for trying the system out. There is also a live quickstart that uses the Claude command line tool, which requires either a Claude subscription or an Anthropic API key. The project describes itself as being built specifically so that meta-agents, meaning higher level agents, can supervise, optimize, and train other agents by observing, forking, and replaying their execution. It is installed with pip, requires Python 3.11 or newer, and the README states plainly that it is in early alpha with APIs that may still change between releases. Windows is not supported directly, and the documentation recommends using WSL instead.