# Shepherd (AI) Shepherd is an open-source (MIT) Python runtime that makes agent execution **reversible**. Every run becomes a durable, Git-like trace you can inspect, fork, replay, and roll back — and agents never touch your files directly. Their work lands as *proposals* you review, then accept, apply, or discard. The framing: today's agents edit the filesystem as they go, so supervising them means watching them. Shepherd flips that. The agent works in a jail; you merge its output like a pull request. ## How it works - **Tasks are Python functions.** The signature and docstring define the agent's contract; declared grants (read-only or read-write per repository) become OS-enforced permissions via Seatbelt (macOS) or Landlock (Linux). - **Execution traces** record everything, enabling fork/replay/reverse of any run. - **Meta-agents** supervise other agents programmatically — the runtime is built for agents watching agents. - Agents can be Claude-powered or deterministic providers. ## Performance tricks worth noting - Copy-on-write forking ~5x faster than `docker commit` - ~95% KV-cache reuse on replay, so re-running a trace is cheap ## Status Early alpha, active development, APIs still moving. `pip install shepherd-ai`, Python 3.11+, macOS and Linux (WSL on Windows). ## My take The proposal model is the interesting part. It's the same trust boundary [[Claude Code]] draws with permission prompts, but enforced at the OS level and made replayable. If agent supervision becomes a real discipline, "reversible by construction" beats "watched closely". ## References - [Shepherd on GitHub](https://github.com/shepherd-agents/shepherd) - [Launch thread by Akshay Pachaar on X](https://x.com/akshay_pachaar/status/2086079311279493389) ## Related - [[AI Agents]] — what it supervises - [[AI Agent Harness]] — adjacent category; Shepherd is the safety/runtime layer - [[Claude Code]] — permission-prompt approach to the same trust problem - [[Docker Sandboxes]] — container-level isolation alternative