todo.md

Install todo.md

todo.md ships as a single binary, todomd. This page takes you from nothing installed to your first approved task in about ten minutes.

Free for your first 100 dispatches. No signup, no card, fully offline.

Prerequisites

  • git. todo.md runs each agent in an isolated worktree and merges back with git. Verify with git --version.
  • cmux or tmux. Agent sessions run inside a terminal multiplexer, so one of the two must be on your PATH. cmux is best if you already use it for terminals; any modern tmux works (brew install tmux, apt install tmux). You pick one during todomd init.
  • A coding agent. Claude Code, Open Code, Pi, or Codex. todo.md dispatches tasks to the agent you already have.

Step 1: installing the binary

With Homebrew, on macOS or Linux:

brew tap harlley/tap
brew install todomd

Upgrade later with brew upgrade todomd.

Without Homebrew, download the binary for your platform directly. This command detects your OS and architecture and installs the latest release:

sudo curl -fsSL \
  "https://dl.todomd.dev/latest/todomd-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')" \
  -o /usr/local/bin/todomd \
  && sudo chmod +x /usr/local/bin/todomd

Supported targets are macOS and Linux on amd64 and arm64. Re-run the same command to upgrade; it always pulls the latest release. You can also fetch a target explicitly:

Verify the install:

todomd version

Step 2: wiring your coding agent

todomd init connects the binary to the coding agents on your machine. It runs once per machine and is required before todomd start.

todomd init

The wizard asks three questions: which runner to use (cmux or tmux), which agents to enable, and which runtimes get the /todomd-* commands. Each answer comes pre-filled with a sensible default, so pressing Enter three times works. Your choices are saved to ~/.todomd/config.yaml.

init detects Claude Code, Open Code, Pi, and Codex, and installs the commands into whichever ones are present. After it finishes, start a fresh session in your agent so the new commands register. In Claude Code, /reload-plugins works too.

Step 3: opening your first board

todo.md needs a git repo. Make a scratch one somewhere outside your real projects:

mkdir todomd-hello && cd todomd-hello
git init
echo "# Hello" > README.md
git add README.md
git commit -m "init"

Then, inside your coding agent, run:

/todomd-start

This spawns the todo.md daemon and, because the repo has noTODO.md yet, writes one for you: frontmatter populated from your todomd init answers, plus a Getting Started list that walks the loop you are about to run. You never hand-write the file or its frontmatter.

Open the board:

todomd open browser

The board renders the Getting Started list and watchesTODO.md. Any edit to the file re-renders it live.

Step 4: dispatching your first task

The Getting Started list opens with 1. Dispatch your first task. Grab its id, the six characters in the trailing<!-- id:… --> comment, and run:

/todomd-dispatch <id> claude

Replace claude with any agent you enabled during init. Prefer clicking? Every task on the board has agent buttons that do the same thing. Three things happen:

  1. The task flips to [~] (doing) in TODO.md.
  2. A sibling worktree is created at ../worktree-todomd-hello/<id>-…/.
  3. The agent starts in that worktree and writes a single tutorial file. Nothing in your project's source is touched.

The board shows the task as in progress. When the agent finishes, it commits its work on a task branch and marks the task [?] (review). The board updates live.

Step 5: reviewing the diff

Back in your agent, with the same id:

/todomd-review <id>

You get the worktree path, the committed diff, any uncommitted work, and a note if your main moved while the agent ran. For the tutorial task, you should see one new file and one commit.

If the diff looks wrong, /todomd-discard <id>throws away the worktree and branch and resets the task to [ ]. Try again with a clearer description.

Step 6: approving

/todomd-approve <id>

This squash-merges the task branch into your checked-out branch (usually main) and marks the task [x]. The commit subject carries the task id, so you can find it later with git log. Verify:

git log --oneline -1

That's your first approved task. The Getting Started list has a few more steps (discard, follow-up, writing your own task) that round out the loop. Work through them, delete the tutorial list, and start tracking real work.

After the free tier

Everything above runs on the free tier: your first 100 dispatches, every feature included, no account and no network calls. When you hit the cap, buy a license and the key arrives by email. Activate it on your machine:

todomd license activate <key>

The license binds to one machine at a time. There is no deactivation step: activate on a new machine and your seat moves there automatically.

Stuck at any step? Emailharlley@todomd.dev and a human reads it.