[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"readme:shepherd":3},"\u003Cdiv align=\"center\">\n\u003Cimg src=\"https:\u002F\u002Fshepherd-agents.ai\u002Fassets\u002Flogo-shepherd.png\" alt=\"Shepherd\" width=\"140\" \u002F>\n\u003Ch1>Shepherd: Programmable Meta-Agents via Reversible Execution Traces\u003C\u002Fh1>\u003Cp>\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fstatus-alpha-orange?style=for-the-badge\" alt=\"Status: Alpha\" \u002F> \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fshepherd-ai\u002F\" rel=\"nofollow ugc noopener\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fshepherd-ai?style=for-the-badge&logo=pypi&logoColor=white\" alt=\"PyPI\" \u002F>\u003C\u002Fa> \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fshepherd-ai\u002F\" rel=\"nofollow ugc noopener\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fpyversions\u002Fshepherd-ai?style=for-the-badge&logo=python&logoColor=white&label=\" alt=\"Python\" \u002F>\u003C\u002Fa> \u003Ca href=\"https:\u002F\u002Fshepherd-agents.ai\u002F\" rel=\"nofollow ugc noopener\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FHomepage-4d8cd8?style=for-the-badge&logo=google-chrome&logoColor=white\" alt=\"Homepage\" \u002F>\u003C\u002Fa> \u003Ca href=\"https:\u002F\u002Fdocs.shepherd-agents.ai\u002F\" rel=\"nofollow ugc noopener\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDocs-4d8cd8?style=for-the-badge&logo=materialformkdocs&logoColor=white\" alt=\"Docs\" \u002F>\u003C\u002Fa> \u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2605.10913\" rel=\"nofollow ugc noopener\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPaper-2605.10913-red?style=for-the-badge\" alt=\"Paper\" \u002F>\u003C\u002Fa> \u003Ca href=\"https:\u002F\u002Fshepherd-agents.ai\u002Fblog\" rel=\"nofollow ugc noopener\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBlog-4d8cd8?style=for-the-badge\" alt=\"Blog\" \u002F>\u003C\u002Fa>\u003C\u002Fp>\n\u003C\u002Fdiv>\u003Chr \u002F>\n\u003Cblockquote>\n\u003Cp>[!IMPORTANT]\n\u003Cstrong>Shepherd is in early alpha\u003C\u002Fstrong> and under active development.\nAPIs may still change between releases. Feedback and issues are very welcome!\u003C\u002Fp>\n\u003C\u002Fblockquote>\n\u003Cp align=\"center\">\n  \u003Ca href=\"#installation\" rel=\"nofollow ugc noopener\">Install\u003C\u002Fa> |\n  \u003Ca href=\"#quickstart\" rel=\"nofollow ugc noopener\">Quickstart\u003C\u002Fa> |\n  \u003Ca href=\"#permissions-the-signature-is-the-permission-surface\" rel=\"nofollow ugc noopener\">Permissions\u003C\u002Fa> |\n  \u003Ca href=\"#examples\" rel=\"nofollow ugc noopener\">Examples\u003C\u002Fa> |\n  \u003Ca href=\"https:\u002F\u002Fdocs.shepherd-agents.ai\u002F\" rel=\"nofollow ugc noopener\">Docs\u003C\u002Fa> |\n  \u003Ca href=\"#citation\" rel=\"nofollow ugc noopener\">Citation\u003C\u002Fa>\n\u003C\u002Fp>\u003Cp>\u003Cstrong>Shepherd\u003C\u002Fstrong> is a runtime substrate for agent work that needs inspection,\nreversibility, and supervision. It records agent runs as durable, inspectable\nexecution traces, with retained workspace outputs that can be reviewed before\nthey are selected, applied, released, or discarded.\u003C\u002Fp>\n\u003Cblockquote>\n\u003Cp>\u003Cstrong>Platforms.\u003C\u002Fstrong> Shepherd requires \u003Cstrong>Python 3.11+\u003C\u002Fstrong>. OS-level grant enforcement\nis executed on \u003Cstrong>both macOS\u003C\u002Fstrong> (Seatbelt) and \u003Cstrong>Linux\u003C\u002Fstrong> (Landlock, in a privileged\ncontainer). \u003Cstrong>Windows is unsupported\u003C\u002Fstrong> (enforcement would be\nadvisory-only at best) — use \u003Cstrong>WSL\u003C\u002Fstrong>.\u003C\u002Fp>\n\u003C\u002Fblockquote>\n\u003Ch2>Installation\u003C\u002Fh2>\n\u003Cpre>\u003Ccode class=\"language-bash\">pip install shepherd-ai\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>Working on Shepherd itself? Install the local editable closure instead:\n\u003Ccode>python -m venv .venv && . .venv\u002Fbin\u002Factivate && pip install -r requirements-dev.txt\u003C\u002Fcode>\n(see \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fshepherd-agents\u002Fshepherd\u002Fblob\u002Fmain\u002FCONTRIBUTING.md\" rel=\"nofollow ugc noopener\">CONTRIBUTING.md\u003C\u002Fa>).\u003C\u002Fp>\n\u003Ch2>Quickstart\u003C\u002Fh2>\n\u003Cp>Shepherd is an agent framework: a task's implementation can be a sandboxed\nagent, and its work comes back as a \u003Cstrong>reviewable proposal\u003C\u002Fstrong> — nothing touches\nyour files until you accept it. Here the whole body of a task \u003Cem>is\u003C\u002Fem> a Claude\nagent.\u003C\u002Fp>\n\u003Cblockquote>\n\u003Cp>Needs the \u003Ccode>claude\u003C\u002Fcode> CLI — signed in (a Claude subscription works) or with an\n\u003Ccode>ANTHROPIC_API_KEY\u003C\u002Fcode>. Neither? Jump to the\n\u003Ca href=\"#offline-quickstart\" rel=\"nofollow ugc noopener\">Offline Quickstart\u003C\u002Fa> — it runs anywhere, keyless.\u003C\u002Fp>\n\u003Cp>On a subscription, a sandboxed run is most reliable with a long-lived token:\n\u003Ccode>export CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token)\u003C\u002Fcode>. A short-lived signed-in\nsession can't be refreshed from inside the sandbox, so it may work\ninteractively yet fail here — \u003Ccode>shepherd doctor claude\u003C\u002Fcode> (add \u003Ccode>--probe\u003C\u002Fcode> for a real\nauth round-trip under Shepherd's config, in the parent — not a jailed run) tells\nyou which credential you have before you run. If Claude returns an org-policy\nerror (HTTP 403), that's an account\u002Forganization limit, not a login problem — a\ndifferent key or your org admin is the fix. And an outright \u003Ccode>claude\u003C\u002Fcode> CLI hang\n(e.g. a stale version) surfaces as a budget timeout, not an auth error.\u003C\u002Fp>\n\u003C\u002Fblockquote>\n\u003Cp>A task is a plain Python function with \u003Cstrong>no body\u003C\u002Fstrong>; the signature and docstring\nare the contract the agent fulfils at runtime — including its permissions:\n\u003Ccode>repo: sp.GitRepo\u003C\u002Fcode> is the explicit writable workspace-handle grant that lets the\nagent write the repository (see\n\u003Ca href=\"#permissions-the-signature-is-the-permission-surface\" rel=\"nofollow ugc noopener\">Permissions\u003C\u002Fa>):\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-python\">def write_program(\n    repo: sp.GitRepo,\n    prompt: str,\n\u003C\u002Fcode>\u003C\u002Fpre>\n",1784240408043]