shepherd
the orchestrator for your coding agents. build teams of claude, codex and gemini agents, give them roles, and let them work in parallel, each in its own git worktree.
git clone https://github.com/Rivaldito/shepherd.git
an orchestrator and a coder at work in the terminal (sample data). the native app is a desktop window over the same server. ctrl+shift+s switches between them.
running several agents at once works for a while. then it gets messy.
shepherd keeps every agent in its native terminal and adds the layer above: who works on what, in which worktree, and how the agents talk to each other.
agents with roles, not just panes.
patterns
agent teams as yaml. four ready-made topologies, and you can create your own.
roles
brain, coder, reviewer, docs, tester out of the box, plus your own with their own vendor, model and skills.
a worktree per agent
each coder gets its own branch, so agents never step on each other. you merge with plain git; shepherd never merges or pushes.
an event bus
topics, partitions, consumer groups and replay. publishing wakes idle agents.
tasks and gates
specs and acceptance criteria, plan approval, and publishing only with your explicit ok.
snapshots
automatic safety copies of every worktree in hidden git refs, with diff and safe restore.
terminal, app and cli
a shepherd section in the terminal (ctrl+b a), a desktop app, and a --json cli, all on the same server.
one rust binary
no electron. runs in whatever terminal you already use, and everything stays local.
your agent team, in one yaml file.
a pattern says which agents, which roles, which topics they use to talk, and who starts. four ship built in. patterns live in your repo (.shepherd/patterns/), so the team is versioned with the code.
shepherd pattern list # the four built-ins, plus your own shepherd pattern new api-team --from orchestrator-worker # copy a template into .shepherd/patterns/ shepherd pattern validate api-team # pattern is valid shepherd pattern run api-team --task "Add GET /health and GET /version, with tests"
validation catches mistakes before agents start: unknown roles, topics nobody reads, a market with one solver, and more. edit it as yaml, in the terminal section, or in the native app's graph editor.
who does what, with which model.
a role is a job description: the default vendor and model, whether it gets its own worktree, whether it may start other agents, and which skills it receives. a reviewer can be forced onto a different vendor than the coder, so a model never grades its own work.
| ROLE | DEFAULT VENDOR | DOES | WORKTREE |
|---|---|---|---|
| brain | claude / opus | plans, splits work, aggregates | no |
| coder | codex (falls back to gemini, claude) | implements | yes |
| reviewer | gemini (always ≠ coder's vendor) | reviews code and security | no |
| docs | gemini | documentation and docs questions | no |
| tester | claude / sonnet | tests and debugging | no |
# .shepherd/config.yaml — write only what changes roles: migrator: vendor: claude model: sonnet worktree: true skills: [lang-go, debug] prompt: You write and review database migrations.
$ shepherd roles list brain claude/opus coder codex/default docs gemini/default migrator claude/sonnet <- yours reviewer gemini/default tester claude/sonnet
the terminal and ten views over one server.
what you create in the terminal, the native app or the cli appears in the other two.
everything herdr gives you, plus coordination.
| PLAIN TERMINAL MULTIPLEXER | SHEPHERD | |
|---|---|---|
| agent terminals, detection, sessions | yes | yes (herdr's) |
| role-based routing and vendor fallbacks | no | yes |
| isolated worktree per agent | by hand | automatic per role |
| team layouts | by hand | yaml patterns with validation |
| agent-to-agent messaging | copy and paste | event bus with partitions and groups |
| plan approval and publish gates | no | yes |
| rollback of an agent's edits | no | snapshots with safe restore |
| skills per role | no | yes |
what shepherd deliberately does not do
from an empty machine to a team of agents.
about ten minutes plus the first build. you need git, rust 1.96.1+, zig 0.16.0 (to build the vendored terminal library) and at least one agent cli: claude, codex or agy.
build it
shepherd is in beta and ships no binaries yet.
git clone https://github.com/Rivaldito/shepherd.git cd shepherd ./cargo-fork.sh build --release export PATH="$PWD/target/release:$PATH"
turn the orchestrator on
then check the config.
mkdir -p ~/.config/shepherd
printf '[shepherd]\nenabled = true\n' > ~/.config/shepherd/config.toml
shepherd config check # config: okmake a repo to play in
shepherd works on git repositories with at least one commit.
mkdir ~/shepherd-playground && cd ~/shepherd-playground git init -q && git commit -q --allow-empty -m "init" shepherd roles list && shepherd vendors list
run one agent
run shepherd, press ctrl+b a for the shepherd section, then in a second terminal:
shepherd spawn coder "Create hello.txt containing 'hi' and commit it." \
--vendor claude --model haiku
shepherd agents # starting → working → idle
shepherd attach coder-1run a team
the agent works on a branch named shep/<n>-…; merge it yourself with git merge. then copy a built-in pattern and run a whole team:
shepherd pattern new api-team --from orchestrator-worker
shepherd pattern validate api-team
shepherd pattern run api-team --task "Create a.txt containing A and b.txt containing B, one worker each. Commit."
shepherd pattern runs # state of the run
shepherd topic tail results(cd native && cargo build --release -p shepherd-native), then native/dev/demo.sh opens the window against a throwaway server with sample data. to explore without touching your own config, use scripts/shepherd-iso.sh start.every piece, in detail.
a fork, kept close to upstream.
shepherd would not exist without herdr (herdr.dev). the terminal multiplexer, pty management, session persistence, agent detection, client/server protocol, socket api and plugin system are the herdr contributors' work, under apache-2.0.
forked from herdr 0.9.5 at upstream commit ee5bfb5, history preserved, upstream merged with a repeatable routine. shepherd is an independent fork, not affiliated with or endorsed by the herdr project.
- focus. herdr manages agent panes; shepherd adds coordination: roles, worktrees, patterns, bus, tasks and snapshots.
- separate config and state.
~/.config/shepherd, with a read-only fallback to herdr'sconfig.toml. - no upstream auto-update. update checks against herdr's channels are off, so they never replace the shepherd binary.
- human gates. changes and git publishing need explicit confirmation unless you override it.
ONE TERMINAL.
THE WHOLE FLOCK.
contributions welcome: bug reports, ideas, docs, patterns, roles and code.