OPEN SOURCE · MIT · FREE FOREVER
A todo board your agents can work from too.
Shepherd is a terminal board backed by plain markdown files. Run it in any terminal or as a herdr plugin pane. It's greppable, hand-editable and easy to sync, and any agent that can run a shell can read and update it.
Plain markdown, all the way down
Every board is a markdown file in ~/.config/shepherd/, one file per board. Edit it in your editor, grep it, commit it or sync it with your dotfiles. Shepherd reloads changes made outside it on its own.
- Priority, category, tags, status, due and defer dates, links and notes on every item
- One level of subtasks, with completion that cascades both ways
- Done items sweep to a per-board archive you can still search
- [ ] (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 firstBuilt for agents, not bolted on
The command API is the whole integration. There's no server and no MCP: any agent that can run a shell uses the same verbs you do.
- Stable ids, so an agent's reference survives the board reordering
- A board lock, so parallel agents never lose each other's writes
watchstreams changes as JSON lines, so a coordinating agent reacts instead of polling- A bundled Claude Code skill, and an
AGENTS.mdfor Cursor, Codex, Zed and others
# read with a stable machine shape
shepherd list --json
# add, edit and finish by id
shepherd add "fix flaky test @ci !h" --json
shepherd edit 019f7390… "status:in-progress"
shepherd done 019f7390…
# react to changes as they happen
shepherd watchFast at the keyboard
Everything is a key or two away, and the footer shows which keys apply to what's selected.
One-line quick add
Type "deploy api @work #api !h due:tomorrow" and the category, tag, priority and due date are set in one go.
Five ways to look
Group by category, priority or tag, switch to a table, or use the lane view as a kanban board by status.
Many boards, one view
Give each project its own board, then press ga for a read-only view across all of them.
Undo and redo
Multi-level undo and redo, autosave after a short pause, and a clear saved or unsaved marker.
Due and defer dates
Overdue items pin to the top, and deferred items stay dimmed until their start date.
Stats in the terminal
Completion, priority load, aging, throughput and backlog trend, drawn as charts with shepherd stats.
Hand it to your agents
Press r on a task and your coding agent does it, in the board's repo, with the full log kept. With Shepherd Pro, along with GitHub issues, webhooks from any service, and jobs that run on their own.