Summary

Shepherd provides a runtime substrate for agent execution, transforming runs into reversible, Git-like traces. It enables meta-agents to inspect, fork, replay, and revert agent actions, offering significant performance gains over traditional container commits and high KV-cache reuse. This framework is designed for supervising, optimizing, and training AI agents.

How It Works

Shepherd records agent executions as durable, inspectable traces, retaining workspace outputs for review before commitment. Its core innovation lies in a copy-on-write fork mechanism, achieving speeds approximately five times faster than docker commit and enabling around 95% KV-cache reuse upon replay. Agents and environments are tightly coupled, with tasks defined as sandboxed agents whose permissions are declared via function signatures and enforced at the OS syscall level using technologies like macOS Seatbelt and Linux Landlock.

Quick Start & Requirements

Installation is straightforward via pip: pip install shepherd-ai. Prerequisites include the Claude CLI for specific agent integrations (requiring sign-in or an ANTHROPIC_API_KEY), though an offline, keyless quickstart is available using a deterministic provider. The project provides demo scripts for immediate testing, with setup and execution typically taking around a minute. Official documentation, a research paper, and blog posts are available online.

Highlighted Details

• Achieves ~5x faster execution for agent runs compared to docker commit.
• Reuses approximately 95% of KV-cache on replay, optimizing performance.
• Enforces granular permissions declared in task signatures at the OS syscall level (macOS Seatbelt, Linux Landlock).
• Provides Git-like reversibility for agent execution traces, allowing for observation, forking, and rollback.

Maintenance & Community

Shepherd is currently in an early alpha stage, marked by active development and potential API changes. Feedback and issue reporting are encouraged. Key contributors are listed in the associated research paper. No specific community channels (e.g., Discord, Slack) are detailed in the README.

Licensing & Compatibility

The project is licensed under the permissive MIT License, facilitating broad compatibility for commercial use and integration into closed-source projects.

Limitations & Caveats

As an alpha project, Shepherd is under active development, and its APIs are subject to change. Advanced permission features like sub-root grants (where(path=…) ) are not yet implemented. Enforcement of Linux Landlock permissions is currently container-gated.