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 shipped wheel, offline (after `shepherd init`)
import shepherd as sp

workspace = sp.open(".")  # run `shepherd init` here first

# A task is a signature + docstring: the contract a sandboxed agent fulfils.
# The grant on `repo` is what lets it write the repository.
workspace.tasks.register_source(
    task_id="quickstart.write_note",
    module="quickstart_tasks",
    source_text='''
import shepherd as sp

def write_note(repo: sp.May[sp.GitRepo, sp.ReadWrite], topic: str,
               output_path: str, output_text: str):
    """Write one note about `topic` into the repository."""
''',
    entrypoint="write_note",
    may_default="ReadWrite",
)

run = workspace.run(
    "quickstart.write_note",
    repo=workspace.git_repo(),
    args={"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(output.changeset().inspect()["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()
workspace.close()

Find your path

  • Run the quickstart

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

    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

    The honest map: the Settlement Core that ships in 0.2.0, and the named Dataflow road (returned handles, task-as-value delegation) ahead.

    Settlement Core / Dataflow

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, release, or discard — exactly once.

The composable meta-agent surface — tasks passed to tasks, supervised retries — is the product's north star and is not in 0.2.0; the honest map is the roadmap.


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.