SHEPHERD: Programmable Meta-Agents via Reversible Agentic Execution Traces
Your harness is just another agent.
1Northeastern University 2Stanford University · *equal contribution
@task code. The same substrate powers three meta-agents: runtime intervention, counterfactual optimization, and tree-search RL.Abstract
As LLM agent systems take on more complex tasks, they increasingly rely on meta-agents: higher-order agents that create, operate on and manage other agents. Meta-agent operations such as coordinating agents, halting risky actions before execution, or repairing failed runs require runtime manipulation of agentic execution. Yet existing agentic substrates make this difficult: they expose only transcripts and environment snapshots, forcing meta-agents to build ad hoc tooling to reconstruct and operate over full execution state.
Therefore, we introduce SHEPHERD, a Python substrate grounded in functional programming
principles, where an agent's execution is itself a first-class object that a meta-agent
can easily inspect and transform. Every model action, tool call, and environment change becomes a
structured event in a reversible, Git-like execution trace, where any past state can be reverted
5× faster than docker commit and fork. Three example use cases show SHEPHERD's
versatility: (1) a supervisor meta-agent prevents conflicts among parallel coding agents, lifting
pair-coding pass rate from 28.8% to 54.7% on CooperBench; (2) a counterfactual optimization
meta-agent repairs agent workflows by proposing edits and replaying runs from the point of changed
behavior, outperforming MetaHarness on Terminal-Bench 2.0 by 12.8% with 58% lower wall-clock;
(3) a training meta-agent picks fork points during rollouts to improve credit assignment in
long-horizon agentic RL, doubling GRPO's uplift on Terminal-Bench 2.0. We open-source SHEPHERD to
enable principled and efficient operations over agentic execution for both users and meta-agents.
The idea: execution becomes data
A meta-agent creates a worker, observes its execution without perturbing it, and
intercepts a bad action before it lands, then forks a patched branch and reverts the
buggy one. Because the whole run is a reversible, Git-like trace, all of this is ordinary
@task code.
# worker @task def implement(repo, feature): "Implement the feature in the repo"
# meta-agent @task def oversee(worker, repo, feature): "If tests break, revert the worker and retry"
# the meta-agent manages the worker with workspace(model=claude("sonnet-4-5")): implemented = oversee(implement, repo, "login")
Try it yourself: fork and rewind your agent
Write your agent as a plain Python task and run it. Every step it takes becomes a commit on a reversible, Git-like trace — and its work comes back as a held proposal, not as edits to your files.
The demo below is real: a Claude agent writes a working program from a one-line prompt.
Inspect what it did with shepherd run trace, then decide. A meta-agent can
rewind the agent and its files to any earlier step, byte-for-byte — or fork
from there and try a different path.
Needs the claude CLI, signed in. No key? The
repo's
offline quickstart runs the same machinery, keyless — and the blog
has the full walkthrough.
$ pip install shepherd-ai
# let a real agent do a real task — in custody, not in your files
$ shepherd init
$ shepherd demo write agent-task > agent_task.py
$ python agent_task.py
# every step is on the trace; the work is held for review
$ shepherd run trace --latest
# keep it — or not; the trace remembers either way
$ shepherd run select <run-ref>BibTeX
@misc{yu2026shepherdruntimesubstrateempowering,
title={Shepherd: A Runtime Substrate Empowering Meta-Agents with a Formalized Execution Trace},
author={Simon Yu and Derek Chong and Ananjan Nandi and Dilara Soylu and Jiuding Sun and Christopher D Manning and Weiyan Shi},
year={2026},
eprint={2605.10913},
archivePrefix={arXiv},
primaryClass={cs.AI},
url={https://arxiv.org/abs/2605.10913}
}