Skip to content

Program meta-agents in Python

Agent work arrives as a reviewable, reversible proposal: typed tasks, permissions in the signature, and retained runs you inspect before you decide.

Get started

hero.py — runs on the installed package, offline (after `shepherd init`)
import shepherd as sp


# A task is a signature + docstring: the contract a sandboxed agent fulfils.
# The `repo` parameter is the whole permission surface — a writable workspace
# handle. Narrow it with sp.May[sp.GitRepo, sp.ReadOnly] when writes aren't needed.
@sp.task
def write_note(repo: sp.GitRepo, topic: str, output_path: str, output_text: str) -> None:
    """Write one note about `topic` into the repository."""


with sp.open(".") as workspace:  # run `shepherd init` here first
    workspace.tasks.register(write_note)
    run = workspace.run(
        write_note,
        repo=workspace.git_repo(),
        topic="shepherd",
        output_path="NOTE.txt",
        output_text="Hello from a Shepherd retained output.\n",
        runtime={"provider": "static"},  # deterministic, offline; "claude" = live agent
    )

    output = run.output()                          # a proposal, held to one side
    print(list(output.changeset().changed_paths))  # what it wants to change
    print(output.read_text("NOTE.txt"), end="")    # read it before deciding
    output.select()                                # record your decision — or .discard()

Find your path

  • Run the quickstart

    Initialize a workspace, run a task, inspect its retained changeset, and settle it. Offline and deterministic, on the installed package.

    Getting Started

  • Permissions in the signature

    Per-repository read-only / read-write grants declared on the task's parameters — enforced at the OS on a jailed placement.

    Grant a task repo access

  • What ships vs. what's on the road

    Exactly what ships in 0.3.0 — and what's ahead: returned handles and task-to-task delegation are on the roadmap, not in this release.

    Roadmap

Why Shepherd

  • Typed. A task is a Python function: signature, docstring, and — right on the parameters — its permission grants. Reading the signature is reading the permission surface.
  • Observable. Every run leaves a durable trace; shepherd run trace reads back exactly what happened, so you debug by reading a record, not guessing.
  • Reviewable. A run's work lands as a retained output beside your files, inspected per binding and settled explicitly — select, apply, release, or discard — exactly once. apply three-way-settles a kept output onto a workspace that has moved on, and fails closed on any overlap.

The composable meta-agent surface — tasks passed to tasks, supervised retries — is where Shepherd is headed and is not yet shipped; the roadmap says exactly what is.


Important

Shepherd is an early development preview - ready to explore and build with, but not yet to depend on. Expect breaking changes between releases and rough edges as the design settles, and please don't build production or business-critical workflows on it yet. Support is best-effort, and nothing is guaranteed to be stable while we're pre-1.0. If something is missing, confusing, or broken, please let us know.