DOCS
Using Shepherd
Shepherd is a todo board for the terminal, stored as plain markdown. You drive it with a few keys; scripts and coding agents drive the same board through its command API. This page covers both.
Install
Homebrew
The quickest way, on macOS or Linux:
brew install jwarykowski/tap/shepherd
shepherd --version
Sending tasks to your agent is part of Shepherd Pro and needs drover, the engine that runs it: brew install jwarykowski/tap/drover. See Send tasks to your agent.
From source
You need Go; with GOTOOLCHAIN=auto Go fetches the version the module asks
for.
git clone https://github.com/jwarykowski/shepherd
cd shepherd
GOTOOLCHAIN=auto go build -o bin/shepherd .
Put bin/shepherd somewhere on your PATH.
As a herdr plugin
In herdr, Shepherd opens as a pane next to your agents:
herdr plugin install jwarykowski/shepherd
The plugin can open the board as a split, tab, overlay or zoomed pane. Set the
default in config.toml with placement and, for splits, direction.
Getting started
Your first board
Run shepherd with no arguments to open the default board. It lives at
~/.config/shepherd/todo.md.
shepherd
Press a and type a task on one line. Tokens in the line set its fields, and
everything else becomes the text:
ship the release @work #api !h due:3d
That adds “ship the release” in the work category, tagged api, with high
priority, due in three days.
Keys to know first
Keys are named for what they do: d due, t tags, c category. Rarer
screen-level actions sit behind g: press g and the footer lists what can
follow, so gb is the board picker.
| Key | Does |
|---|---|
j / k | move down and up (gg / G for top and bottom) |
a | add an item |
A | add a subtask to the selected item |
e | edit the selected item’s text |
space | toggle done |
tab | cycle status: open, then any named statuses, then done |
enter | detail view, which is also an editor |
h m l | priority high, medium, low |
c t d s | category, tags, due date, start date |
y | copy the title, over SSH and in tmux too |
v | cycle views: category, priority, tag, table, lane |
/ | filter as you type |
u / ctrl+r | undo and redo |
gt | pick a colour theme, previewed live |
? | every key |
q | save and quit |
The footer shows the keys that apply to whatever is selected; gf hides it.
Every key can be rebound.
Saving
Shepherd saves when you quit, after a minute of idle edits, or when you press
w. The header shows ● unsaved or ● saved. If the file changes on disk and
you have no unsaved edits, the board reloads on its own, so changes from an
agent or a dotfiles sync just appear.
The board
Items and fields
Every item can carry a priority, a category, tags, a status, a due date, a defer (start) date, a link and a note. Items sort by category, then priority, then soonest due date. Overdue open items are pinned to the top.
Quick-add tokens
The same tokens work in the board’s add prompt and in the command API’s add,
sub and edit.
| Token | Sets |
|---|---|
@work | category (one per item; drives grouping) |
#api | adds a tag |
tags:api,docs | replaces all tags (tags: clears them) |
!h !m !l | priority |
due:3d | due date: today, tomorrow, 3d, 2w, 5m, 1y, or DD-MM-YYYY |
defer:1w | start date; the item stays dimmed until then |
link:https://… | a reference link (o opens it) |
status:in-progress | a named status |
note:call the vendor | a note; takes the rest of the line, so put it last |
Subtasks
Any item can hold one level of subtasks, each a full item with its own fields. Completion cascades both ways: finishing a parent finishes its subtasks, and finishing the last open subtask finishes the parent.
Views
v cycles five layouts. Category, priority and tag group the list
under headers; table shows every field in columns; lane is a kanban
board with one column per status, where ← and → switch columns and tab
moves a card along.
Boards and the global view
Give each project its own board. Named boards live in
~/.config/shepherd/boards/<name>.md; gb opens the board picker and ga
toggles a read-only view across every board.
shepherd --board web # or SHEPHERD_BOARD=web shepherd
shepherd --all # read-only view across every board
shepherd --filter work # start pre-filtered
Archive
C clears done: it sweeps every done item into a sibling archive.md. X
archives just the selected item, and gh browses the archive. It’s
append-only markdown, and / searches it too.
Command API
Any argument that isn’t a flag turns shepherd into a one-shot command: it
reads or changes a board and exits. The binary owns the file format, so every
write is valid markdown, and there’s no server and no MCP to run. Anything that
can run a shell can use it.
Addressing items
Every item has a stable id, shown by list --json. Commands that change an
item take either that id or the item’s 1-based index from list. Subtasks are
addressed by their own id, or as n.m (subtask m of item n).
Scripts and agents should use the id. The index changes whenever the board reorders (a new high-priority item, a date going overdue); the id never does.
Reading
shepherd list # items with their index
shepherd list --json # the stable machine shape, with each item's rev
shepherd list --filter release # only matches, real indexes kept
shepherd list --all --json # every board, with a board field per item
shepherd boards --json # boards with open and total counts
shepherd stats --json # board metrics as numbers
shepherd schema # the item JSON Schema
list --json returns an array of items:
[
{
"id": "019f7390ff8b0e369b6ed5540057c717",
"index": 1,
"done": false,
"priority": "H",
"text": "ship the release",
"category": "work",
"tags": ["api"],
"status": "in-progress",
"created": "10-07-2026 13:40",
"due": "2026-07-15",
"link": "https://github.com/org/repo/pull/1"
}
]
Items with subtasks carry them in a subtasks array. Indexes from list --all
are aggregate and can’t be used to change items: use the id with --board, or
list that board on its own.
Writing
shepherd add "ship the release @work !h due:3d" --json
shepherd sub <ref> "write the changelog !m"
shepherd edit <ref> "status:in-progress"
shepherd edit <ref> "!h note:blocked on the migration"
shepherd edit <ref> "due:" # a bare key clears the field
shepherd done <ref> <ref> <ref> # several in one atomic write
shepherd undone <ref>
shepherd archive <ref>
shepherd rm <ref> --dry-run # preview, then run without it
edit is the one setter for every field: it changes only the fields its tokens
name, and replaces the text only when the line has plain words. done and
undone are shorthands for status:done and status:open.
Add --json to any write to get the resulting item back in the list --json
shape. Errors then come back as {"error": "…"} on stdout.
Watching for changes
shepherd watch # NDJSON until killed
shepherd watch --interval 500ms # poll faster (default 1s)
The first line is a snapshot of the board, then one line per change, keyed by the item’s id:
{"type": "snapshot", "items": [ … ]}
{"type": "added", "item": { … }}
{"type": "updated", "item": { … }}
{"type": "removed", "item": { … }}
{"type": "archived", "item": { … }}
A coordinating agent can react to watch instead of polling list. It only
reads, so it never blocks a writer.
Boards
shepherd add "fix the login bug !h" --board web # any command, any board
shepherd board rename web webapp
shepherd board archive webapp # reversible
shepherd board unarchive webapp
shepherd board delete webapp --force
shepherd board dir web ~/src/web # the board's working directory
Flags go after the command. $SHEPHERD_BOARD sets the board for every command
in a shell.
Flags and exit codes
| Flag | Does |
|---|---|
--json | machine output, and errors as JSON |
-q, --quiet | drop a write’s confirmation line (never the data asked for) |
--no-input | accepted for scripts; the API never prompts |
-h, --help | a command’s flags |
Exit codes: 0 success, 2 a usage or input error (bad flag, unknown command,
unknown ref), 1 a runtime or IO failure.
Coding agents
The command API is the whole integration, so any agent that can run a shell can use your board. Point it at the contract in one of three ways:
Any tool:
shepherd helpprints the full contract. Nothing else is required.Claude Code: link the bundled skill once, and Claude uses it whenever a request is about your todos:
git clone https://github.com/jwarykowski/shepherd ~/src/shepherd ln -s ~/src/shepherd/skills/shepherd ~/.claude/skills/shepherdCursor, Codex, Zed and others: paste
AGENTS.mdinto the tool’s global rules or instructions.
Writes take a board lock, so several agents can work on one board at once without losing each other’s changes.
Safe writes
Three features keep an agent from mangling text or overwriting a change it hasn’t seen.
--text on add, sub and edit sets the text verbatim, so #123, @home
or due: inside it stay text. The other argument then holds only tokens:
shepherd add --text "fix #123 crash" "@work !h"
Every item in --json output carries a rev, a short hash of the item as
stored. --if-rev on edit, sub, claim, done, undone, rm and
archive writes only if the item hasn’t changed since; otherwise it exits 1
and writes nothing. On a conflict, read again and decide again:
shepherd list --json # note the item's id and rev
shepherd done <id> --if-rev 6d6b662e659f
claim marks an item as taken, so two agents don’t pick up the same work. It
sets the item in progress, and fails with exit 1 if someone else holds it or
it’s done. Finishing the item ends the claim, and the board shows who has it.
shepherd claim 3 --by agent-1 || echo "taken, pick another"
shepherd claim 3 --release --by agent-1
Send tasks to your agent
Press r (run) on a task and your coding agent (Claude Code or Codex) does it in the
board’s repo, with its full log kept. Nothing runs until you say go. This is part of
Shepherd Pro: activate a licence key first (see below).
Set up
shepherd agents setup # finds claude or codex, sets everything up, starts it
shepherd board dir web ~/src/web # where the agent works for the web board
agents setup watches every board and starts a small service in the
background (launchd on macOS, a systemd user service on Linux). Run it again any
time; it keeps a config you’ve already edited. Use --runner codex to choose
the agent.
Sending a task
Select a task and press r, or from a shell:
shepherd go 3 # or the item's id
Rows on the board show where each task stands:
| Mark | Means |
|---|---|
| waiting | a run is ready for this task and waits for your go |
| queued | you said go; it starts when your agent is free |
| running | your agent is working on it |
| failed | the agent couldn’t finish; r tries again |
| review | a run finished; check its work, then tick the task |
r on a waiting task releases it, on a failed one tries again, and on any other
open task starts a run now.
A subtask goes with its parent, so the agent knows what it’s one part of. Each
run works in its own copy of the repository (a git worktree) on its own branch,
so your checkout is never touched. In a repository with a remote, the agent
opens a pull request.
Retries and follow-ups
The runs of one job about one thing form a thread: they share a branch and a conversation. A retry, or a later event about the same thing (a review on the pull request the agent opened), carries on the same conversation on the same branch, and the agent is told what earlier runs did. A thread ends when its pull request merges or closes, or after 14 quiet days.
Every run in one place
Press gr for the agents view: every run on every board, plus GitHub and
webhook runs, one row per thread, grouped by what needs you first.
| Key | Does |
|---|---|
r | say go, or retry a failed run |
l | the run’s log: what the agent did and why it stopped |
o | open the pull request the run made, or its issue or error |
t | take over the conversation yourself, in the run’s worktree |
enter | jump to the run’s task |
X | archive a run: a finished one, or one you don’t want run |
C | clear every finished run into the archive |
e | the archive |
Subtask runs sit under their parent. A task’s detail view (enter) lists its runs,
and gl opens the latest one’s log. If agents aren’t running, the board says so.
The background service
shepherd agents status # running or stopped, and where the log is
shepherd agents stop
shepherd agents start
Under the hood
Shepherd runs your agent with drover, which it installs alongside. You never
need to touch it; its config lives in ~/.config/drover/drover.toml.
What the agent is told
Each kind of event has an action: what the agent is told, and whether it waits for your go.
shepherd agents actions # every action, on or off, and its prompt
shepherd agents action "sentry fix" off # or on, or edit to change its prompt
Shepherd Pro
Sending tasks to your agent is part of Pro, along with GitHub issues, webhooks from any service, and auto-release for the jobs you trust. You get a licence key by email:
shepherd pro activate <key>
shepherd pro status
The key is checked on your machine, offline. See Shepherd Pro.
Then add where tasks come from. Run these in the repository the agent should
work in, or pass --dir:
shepherd agents add github acme/web # open issues labelled agent
shepherd agents add webhook sentry # prints a URL to paste into Sentry
shepherd agents secret sentry # take only deliveries Sentry signed
shepherd agents sources # list them
shepherd agents remove sentry
Webhook services: sentry, linear (issues labelled agent), datadog,
alertmanager (Grafana, Prometheus), or webhook for anything else. The
service posts to a private URL that holds each delivery until your computer
collects it, encrypted to a key only your computer has, so nothing reaches your
machine from outside and the relay can’t read what it keeps. Tasks from GitHub
and webhooks are flagged external and always wait for your go.
Configuration
An optional ~/.config/shepherd/config.toml is shared by every board. Edit it
from the board with gs or ,, which writes changes straight back.
view = "category" # category | priority | tag | table | lane
density = "compact" # compact | comfort
autosave = 60 # idle seconds before saving; 0 turns it off
categories = ["work", "home", "personal"] # tab cycles them in the category prompt
statuses = ["open", "in-progress", "done"] # done is always kept, and always last
hidefooter = false
mouse = false # wheel scrolls, click selects, double-click opens
theme = "ansi" # ansi | catppuccin | dracula | gruvbox | nord | mono
Themes
ansi, the default, uses your terminal’s own colours. The others are fixed
palettes with light and dark variants, picked from your terminal’s background.
mono drops colour for bold and faint. gt previews each one live.
Override single colours on top of any theme with theme.<token>:
theme.accent = "#88c0d0" # group headers
theme.prio_high = "red"
Tokens: accent, ok, info, warn, rule, muted, cursor,
prio_high, prio_med, prio_low. A colour is #rrggbb, a palette index
(0-255), an ANSI name (red, bright-blue) or none.
Key bindings
Rebind any board key with key.<action>. Separate keys with commas; a space
makes a two-key sequence:
key.due = "t"
key.tags = "T"
key.boards = "g b, B"
key.prio = "1, 2, 3" # always three: high, medium, low
An override that clashes with another key, or names an unknown action, is
ignored and the footer says so. esc and q always back out and quit. The
key reference lists every
action, and a block that restores the old layout from 0.20 and earlier.
| Variable | Does |
|---|---|
SHEPHERD_BOARD | the board to open or act on |
SHEPHERD_FILTER | start the board filtered |
SHEPHERD_CONFIG | a different config.toml |
SHEPHERD_TODO_FILE | a different board file altogether |
Storage
A board is markdown you can read, grep and commit. Shepherd writes it; metadata rides as indented lines under each item:
- [ ] (H) ship the release
id: 019f7390ff8b0e369b6ed5540057c717
created: 10-07-2026 13:40
due: 2026-07-15
category: work
tags: api, docs
status: in-progress
link: https://github.com/org/repo/pull/1
note: block on the migration first
- [ ] (M) write the changelog
Dates are stored as YYYY-MM-DD so they sort, and shown day first. You can edit
the file by hand (ctrl+e opens it in $EDITOR), but let scripts and agents go
through the command API.
Tips and best practices
- One board per repo. Name boards after projects (
--board web) and set each one’s working directory withshepherd board dir, so tools that act on a task know where to run. - Address by id in anything automated. Indexes are for people at the keyboard; an id survives every reorder.
- Use categories for where, tags for what. A category is the one place an
item belongs and drives grouping; tags are a free-form set for cross-cutting
labels like
#apior#blocked. - Put intermediate states in
statuses. Addin-progressorreviewto the list and the lane view becomes a kanban board. - Defer what you can’t start yet.
defer:1wkeeps an item on the board but dimmed, so the list shows what’s actionable today. - Batch changes in one call.
shepherd done 3 5 8is a single atomic write, and safe to repeat. - Preview destructive commands.
rmandboard deletetake--dry-run. - React, don’t poll. An agent coordinating others should read
shepherd watchrather than callinglistin a loop. - Keep the board in your dotfiles. It’s plain text, so syncing it with git works, and an open board reloads when the file changes.
- Sweep regularly.
Cmoves finished work to the archive; it stays searchable with/, andshepherd statsstill counts it.