{"name":"Shepherd: Reversible Execution Traces for Programmable Meta-Agents","description":"Shepherd is a Python runtime substrate designed for agent work requiring inspection, reversibility, and supervision. It records agent runs as durable, inspectable execution traces, enabling meta-agents to observe, fork, replay, and revert any operation. This framework couples agents and environments using a copy-on-write fork, offering significant performance benefits and robust permission enforcement.","github":"https://github.com/shepherd-agents/shepherd","url":"https://osrepos.com/repo/shepherd-agents-shepherd","source":"osrepos.com","sourceDescription":"This repository profile is provided by osrepos.com, an open source repository discovery platform.","repositoryProfile":"https://osrepos.com/repo/shepherd-agents-shepherd","generatedFor":"open source discovery and AI-assisted research","markdown":"https://osrepos.com/repo/shepherd-agents-shepherd.md","json":"https://osrepos.com/repo/shepherd-agents-shepherd.json","topics":["Python","AI","Agent Framework","Meta-Agents","Reversible Execution","Runtime Supervision","Workflow Automation","Machine Learning"],"keywords":["Python","AI","Agent Framework","Meta-Agents","Reversible Execution","Runtime Supervision","Workflow Automation","Machine Learning"],"stars":null,"summary":"Shepherd is a Python runtime substrate designed for agent work requiring inspection, reversibility, and supervision. It records agent runs as durable, inspectable execution traces, enabling meta-agents to observe, fork, replay, and revert any operation. This framework couples agents and environments using a copy-on-write fork, offering significant performance benefits and robust permission enforcement.","content":"## Introduction\nShepherd is an innovative Python framework that provides a runtime substrate for agents, focusing on enabling programmable meta-agents through reversible execution traces. It transforms an agent's execution into a Git-like trace, allowing for deep inspection, replay, and reversion of any run. This capability is crucial for developing sophisticated meta-agents that can supervise, optimize, and train other agents effectively.\n\n## Why use and benefits\nShepherd offers several compelling advantages for agent development and supervision. Its core strength lies in turning agent execution into a reversible, inspectable trace, which is invaluable for debugging, auditing, and understanding agent behavior. The framework boasts impressive performance, coupling agents and environments in a copy-on-write fork that is approximately 5x faster than `docker commit`, with about 95% KV-cache reuse on replay. Furthermore, Shepherd provides robust security through OS-level grant enforcement for permissions, ensuring that agents operate within defined boundaries on macOS (Seatbelt) and Linux (Landlock). This makes it an ideal tool for building reliable and observable agent systems.\n\n## Installation\nTo get started with Shepherd, ensure you have Python 3.11+ installed. You can install the `shepherd-ai` package using pip:\n\nbash\npip install shepherd-ai\n\n\n## Examples\nShepherd provides a straightforward quickstart to demonstrate its capabilities. You can set up a workspace, run an agent task, and then inspect or apply its retained output. The framework allows agents to propose changes, which you can review and decide to keep or discard, without directly modifying your files until accepted. For a practical example, the `write_program` task demonstrates how an agent can generate code in a sandboxed environment. Offline quickstart options are also available, requiring no API keys. More detailed examples, including a citation-checker package and visual artifact notebooks, are available in the repository.\n\n## Links\n*   [GitHub Repository](https://github.com/shepherd-agents/shepherd){:target=\"_blank\"}\n*   [Official Homepage](https://shepherd-agents.ai/){:target=\"_blank\"}\n*   [Documentation](https://docs.shepherd-agents.ai/){:target=\"_blank\"}\n*   [Research Paper (arXiv)](https://arxiv.org/abs/2605.10913){:target=\"_blank\"}","metrics":{"detailViews":0,"githubClicks":1},"dates":{"published":null,"modified":"2026-10-02T08:42:16.000Z"}}