Todo — Claude Code Plugin
Capture follow-up work with full context during development, then process it automatically via remote Claude sessions.
Problem
During feature work you notice incidental things: stale flags, dead code, missing tests. Today this either scope-creeps your PR or gets lost. Todo Loop captures that context at discovery time and dispatches remote agents to process it.
Install
claude plugin marketplace add bestdan/todo-plugin
claude plugin install todo@todo-plugin
Or from a local clone:
git clone https://github.com/bestdan/todo-plugin.git
claude plugin install todo --plugin-dir ./todo-plugin
What you get
Skill
Claude automatically recognizes when you mention follow-up work, deferred cleanup, or TODO items during a session and offers to capture them as structured todo files.
Commands
| Command | Description |
|---|
/add-todo | Capture follow-up work — delivers it via the configured handler |
/process-todo | Process unclaimed todos — dispatches remote agents to do the work |
/list-todos | Show all todos with status, priority, and tags |
/todo-config | Configure where /add-todo delivers todos (repo PR, GitHub, Jira) |
How it works
Capture: /add-todo
While on a feature branch, run /add-todo Remove the stale foobar alias. The plugin:
- Gathers context (branch, diff, PR number)
- Drafts a structured todo with frontmatter + markdown
- Shows you the draft for review
- Resolves the configured handler and delivers the todo to it, reporting back the artifact URL
Capture is destination-agnostic — where the todo lands is decided by the handler (see Destinations). With no config, the default repo-pr handler reproduces the original behavior below.
Destinations
/add-todo delivers each todo via a handler named in a repo-committed config file, dev_docs/todos/.todo-config.yml. Run /todo-config to set it up. No config → repo-pr.
| Handler | Lands as | Prerequisites |
|---|
repo-pr | Markdown file via a todo-add PR (default) | gh auth (falls back to local staging) |
gh-issue | A GitHub Issue | gh auth |
jira | A Jira work item under an epic | Atlassian MCP connected in Claude Code |
# dev_docs/todos/.todo-config.yml — pick one handler
handler: gh-issue
gh-issue:
repo: owner/name # optional; defaults to current repo
labels: [follow-up] # optional
assignees: [] # optional
handler: jira
jira:
site: mycompany.atlassian.net
project: PLAT # required
issue_type: Task # default Task
default_epic: PLAT-100 # optional; skips the epic prompt
labels: []
The file is committed and shared by the team, so everyone in the repo files to the same place. Unknown handler value → /add-todo stops and points you to /todo-config (no silent fallback). /process-todo and /list-todos operate only on file-based repo-pr todos; with the external handlers, tracking lives in GitHub or Jira.
repo-pr handler (default)
Dispatches a remote Claude session (claude --remote) that:
- Creates branch
todo/add/<slug> from main
- Writes the todo file to
dev_docs/todos/<slug>.md
- Opens a PR labeled
todo-add
Zero local impact. No files staged, no branches touched. You keep working. The todo lands on main via auto-merge, completely decoupled from your feature PR.
Fallback modes (repo-pr only): --remote (cloud VM) → --subagent (creates PR via GitHub API without touching local git) → --local (stages into current branch). Force a mode with the corresponding flag. The gh-issue and jira handlers are single foreground calls and don't use this cascade.
Adding a new handler
A handler is a markdown file at commands/handlers/<name>.md (loaded lazily by /add-todo after handler resolution) plus an entry in the valid-handler list in commands/add-todo.md step 6. The deferred MCP-backed destinations (Linear, Asana, Todoist, Notion) follow one common pattern: a remote Streamable-HTTP MCP server added with claude mcp add --transport http <name> <url> then authenticated with /mcp. The handler should look up the create-tool at runtime (tools/list) and match by name/description rather than hardcoding it, since vendors rename tools. Verified endpoints for when these are built:
