shepherd-agents/shepherd

Health v2 · maintenance only

Flags: young

Adoption not part of the score

2376 stars · 205 forks observed · 2026-08-28

What it is AI-extracted, prompt v1, taxonomy v1, 2026-08-30, confidence not recorded

Shepherd is a Python runtime substrate that records LLM agent executions as reversible, Git-like traces so meta-agents can inspect, fork, replay, and revert any run. It couples agents with copy-on-write forked environments and enforces OS-level permissions, enabling supervision, counterfactual optimization, and tree-search RL over other agents.

Use cases

• supervise and intercept risky actions from parallel coding agents
• replay agent runs from a past state to test workflow edits
• fork agent execution to explore alternative trajectories
• train agents with tree-search reinforcement learning over execution traces
• run sandboxed agent tasks whose file changes arrive as reviewable proposals
• revert an agent's environment to any prior state quickly
• build meta-agents that coordinate, halt, or repair other agents

When to choose

• you need runtime observability and reversibility over LLM agent executions
• you are building meta-agents that manage, optimize, or train other agents
• you want sandboxed agent tasks with OS-enforced permission grants and reviewable changesets
• you need fast forking/replay of agent environments for counterfactual or RL experiments

When to avoid

• you need Windows support (only macOS and Linux enforce grants; use WSL)
• you need a production-stable framework (it is early alpha with changing APIs)
• you just want a simple chatbot or agent loop without trace/replay machinery

Facets

framework · maturity experimental

agent-framework workflow-automation mcp tracing llm-inference reinforcement-learning large-language-models developer-tools reinforcement-learning python cli meta-agents execution-traces reversibility copy-on-write kv-cache-reuse agent-supervision tree-search-rl counterfactual-optimization permissions sandboxed-agents sandboxing replay ai-agents automation macos linux

Member repositories

For agents

markdown · JSON · MCP: product_card(name="shepherd-agents/shepherd")