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 first

Built 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
  • watch streams changes as JSON lines, so a coordinating agent reacts instead of polling
  • A bundled Claude Code skill, and an AGENTS.md for 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 watch

Fast 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.