shepherd

module

v0.1.1 Latest Latest Go to latest Published: Jun 26, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/JacobRWebb/shepherd

Links

Open Source Insights

README ¶

Shepherd 🐑

Shepherd is a Go CLI for agentic git operations. It spins up isolated git worktrees, launches Claude coding agents in them (one at a time or a parallel crew), runs a configurable validation pipeline, and ships/babysits pull requests on GitHub or Bitbucket.

It is cross-platform (Windows, macOS, Linux) and agent-friendly: every command supports --json.

Why

Isolation by default — all agent work happens in disposable worktrees, never in your main working tree.
One tool, end to end — create a workspace, run an agent, validate, open a PR, and keep CI green.
Pluggable — choose your session backend (native processes or tmux) and your forge (GitHub via gh, or Bitbucket via REST) in config.

Install

One-line install (prebuilt binary):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/JacobRWebb/shepherd/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/JacobRWebb/shepherd/main/install.ps1 | iex

With Go:

go install github.com/JacobRWebb/shepherd/cmd/shepherd@latest

From source:

git clone https://github.com/JacobRWebb/shepherd && cd shepherd
make install      # builds with version info into $GOBIN

Or download a binary for your platform from the latest release.

Requirements on PATH: git, the claude CLI, and — for the GitHub forge — gh. tmux is optional (used by the tmux session backend on Linux/macOS/WSL).

Quick start

shepherd init                       # scaffold .shepherd.yaml + the Claude skill
shepherd new "fix the login timeout" # worktree + interactive agent
shepherd new "#123" --headless      # worktree + autonomous agent, from an issue
shepherd ship <branch> --no-push    # run the validation gate (dry run)
shepherd ship <branch>              # validate, push, open a PR
shepherd crew "refactor billing" -n 3   # 3 parallel agents, one worktree each
shepherd babysit 42                 # watch PR #42's CI, auto-fix safe failures
shepherd status                     # list worktrees, sessions, PRs
shepherd                            # interactive dashboard (TUI)

Commands

Command	Purpose
`init`	Scaffold `.shepherd.yaml`, the skill, and optional git hooks
`new <issue-or-task>`	Create a worktree and launch an agent (interactive or `--headless`)
`crew <description>`	Decompose work into N parallel agents, one worktree each
`ship <branch-or-task>`	Run the validation gate, push, open a PR (`--auto-fix` to self-heal)
`babysit <pr-number>`	Watch CI, auto-fix safe failures, notify on the rest
`status`	Show worktrees, sessions, and PRs (`--prs`, `--prune`)
`update`	Self-update to the latest release (`--check` to only check)
`tui` (or no args)	Interactive dashboard

Run shepherd <command> --help for flags. See docs/commands.md for the full reference and the --json output schemas.

Configuration

Configuration lives in .shepherd.yaml (auto-discovered by walking up from the working directory). Env overrides use SHEPHERD_ with __ for nesting, e.g. SHEPHERD_CLAUDE__MODEL=opus. See docs/configuration.md.

Architecture

cmd/shepherd        → tiny entrypoint
internal/cli        → cobra commands, --json rendering
internal/app        → composition root (wires the managers)
internal/worktree   → git worktree management
internal/agent      → claude CLI invocation (interactive + headless)
internal/session    → pluggable backends: native processes, tmux
internal/forge      → pluggable providers: GitHub (gh), Bitbucket (REST)
internal/pipeline   → validation steps + the clean push gate
internal/ship       → validate → push → open PR
internal/babysit    → poll CI, auto-fix, notify
internal/crew       → plan → fan out agents → monitor
internal/tui        → Bubble Tea dashboard
internal/{config,domain,output,logging,notify,gitutil,paths}

See docs/architecture.md for the layering and seams, and AGENTS.md for how an agent should drive Shepherd.

License

MIT (see LICENSE).

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
shepherd command
internal
agent Package agent launches the `claude` CLI inside a worktree, either interactively (inheriting the terminal) or headlessly (`claude -p`, capturing output).	Package agent launches the `claude` CLI inside a worktree, either interactively (inheriting the terminal) or headlessly (`claude -p`, capturing output).
app Package app is the composition root: it resolves the repo, paths, and config into the concrete managers (worktree, session backend, agent launcher, forge) that the CLI commands consume.	Package app is the composition root: it resolves the repo, paths, and config into the concrete managers (worktree, session backend, agent launcher, forge) that the CLI commands consume.
babysit Package babysit watches a PR's checks, auto-fixes safe failures by re-invoking claude in the PR's local worktree, and notifies on anything it cannot fix.	Package babysit watches a PR's checks, auto-fixes safe failures by re-invoking claude in the PR's local worktree, and notifies on anything it cannot fix.
cli Package cli wires the cobra command tree, loads configuration, and renders results/errors via internal/output (machine output on stdout, logs on stderr).	Package cli wires the cobra command tree, loads configuration, and renders results/errors via internal/output (machine output on stdout, logs on stderr).
config Package config loads and validates Shepherd configuration.	Package config loads and validates Shepherd configuration.
crew Package crew decomposes a task description into parallel subtasks, creates one worktree per subtask, launches an agent in each via the session backend, and monitors them to completion.	Package crew decomposes a task description into parallel subtasks, creates one worktree per subtask, launches an agent in each via the session backend, and monitors them to completion.
domain Package domain defines Shepherd's core entities and sentinel errors.	Package domain defines Shepherd's core entities and sentinel errors.
forge Package forge abstracts over git hosting providers (GitHub via the gh CLI, Bitbucket via REST).	Package forge abstracts over git hosting providers (GitHub via the gh CLI, Bitbucket via REST).
forge/bitbucket Package bitbucket implements the forge operations over the Bitbucket Cloud REST API v2.	Package bitbucket implements the forge operations over the Bitbucket Cloud REST API v2.
forge/github Package github implements the forge operations over the gh CLI.	Package github implements the forge operations over the gh CLI.
gitutil Package gitutil provides small read-only helpers over the git CLI for repository metadata (root, current/default branch, cleanliness).	Package gitutil provides small read-only helpers over the git CLI for repository metadata (root, current/default branch, cleanliness).
logging Package logging configures the process-wide zerolog logger.	Package logging configures the process-wide zerolog logger.
notify Package notify delivers events to the terminal, a webhook, and/or an arbitrary command, selected by configuration.	Package notify delivers events to the terminal, a webhook, and/or an arbitrary command, selected by configuration.
output Package output renders command results to stdout, choosing human text or JSON based on the --json flag.	Package output renders command results to stdout, choosing human text or JSON based on the --json flag.
paths Package paths resolves the on-disk locations Shepherd uses for a repository: the runtime state directory (.shepherd), native session logs, the session registry file, and the worktrees root (which may live outside the repo).	Package paths resolves the on-disk locations Shepherd uses for a repository: the runtime state directory (.shepherd), native session logs, the session registry file, and the worktrees root (which may live outside the repo).
pipeline Package pipeline runs the configurable validation steps inside a worktree and implements the "clean push gate": a push is allowed only when every required step passes.	Package pipeline runs the configurable validation steps inside a worktree and implements the "clean push gate": a push is allowed only when every required step passes.
session Package session hosts agent processes behind a pluggable SessionBackend.	Package session hosts agent processes behind a pluggable SessionBackend.
ship Package ship implements the validate -> push -> open-PR flow with an optional bounded auto-fix loop.	Package ship implements the validate -> push -> open-PR flow with an optional bounded auto-fix loop.
tui Package tui is the interactive Bubble Tea dashboard: a polled list of worktrees/agents and a live log viewer that tails a session's output.	Package tui is the interactive Bubble Tea dashboard: a polled list of worktrees/agents and a live log viewer that tails a session's output.
updater Package updater implements `shepherd update`: it checks the latest GitHub release, downloads the matching release archive, verifies its checksum, and atomically replaces the running executable.	Package updater implements `shepherd update`: it checks the latest GitHub release, downloads the matching release archive, verifies its checksum, and atomically replaces the running executable.
worktree Package worktree manages isolated git worktrees by shelling out to `git worktree`.	Package worktree manages isolated git worktrees by shelling out to `git worktree`.