Skip to main content
uv

Todos for Agents

v0.3.0
00

@nimblebraininc/todosforagents

To-do boards for AI agents, kept in one SQLite file on your own machine. No account, no cloud service.

uvMIT

README

Todos for Agents

To-do boards for AI agents, served as an MCP server. An agent lays out a plan, moves each to-do through its status, records why one is blocked, and asks what to do next. A person sees the same boards in a board UI that renders inside MCP Apps hosts.

It runs on your own machine: one SQLite file, no account, no cloud service.

Install

Run it with uv (Python 3.13 or later):

uvx todosforagents

That serves MCP over stdio. To add it to Claude Code:

claude mcp add todosforagents -- uvx todosforagents

For Claude Desktop, the MCP bundle @nimblebraininc/todosforagents is available from mpak. It runs the same package and asks where to keep the database.

Any other MCP client that starts a stdio server can run uvx todosforagents the same way. To serve HTTP on 127.0.0.1 instead, run uvx todosforagents --http; HTTP requires a bearer token, which uvx todosforagents --print-token prints. See docs/local.md.

Where your data lives

Everything is in one SQLite file, todos.db, in your user data directory:

OSDefault location
macOS~/Library/Application Support/todosforagents/todos.db
Linux$XDG_DATA_HOME/todosforagents/todos.db (~/.local/share/... when unset)
Windows%LOCALAPPDATA%\todosforagents\todos.db

Set TODOS_LOCAL_DB to use another file. Keep it on a local disk, not a network share. Several clients may use the same file at once. Upgrades, backups and the HTTP token are covered in docs/local.md.

Tools

ToolWhat it does
create_todoAdd one to-do (to the default board unless one is named)
plan_todosAdd several to-dos in one call, optionally as the steps of a goal
update_todoChange a to-do's title, details, priority, labels, assignee, due date or goal
start_todoMark a to-do in progress
complete_todoMark a to-do done
block_todoMark a to-do blocked, with the reason
reopen_todoPut a to-do back to open
cancel_todoMark a to-do as won't do
reorder_todosSet the order of one status lane on a board
archive_todoHide a to-do from default views, status unchanged
list_todosList or search to-dos, with filters and cursor paging
get_todoRead one to-do whole, with its steps and recent activity
get_next_todoThe highest-priority open to-do: what to work on next
get_board_summaryA board's lane counts and what needs attention
list_boardsList the boards
create_boardCreate a board
update_boardChange a board's name, description or lanes

A to-do's status (open, in_progress, blocked, done, cancelled) changes only through the five status verbs. Every result carries a next_step telling the agent what to do with it, and the server also serves a skill (skill://todos/SKILL.md) with the rules for choosing a tool.

Keys

Every board has a short key, and every to-do a key made of its board's key and its number on that board: MAG-3 is the third to-do on board MAG. The default board's key is TODO. Any argument that takes a to-do id takes its key, and any argument that takes a board id takes the board's key, so an agent can pass on "MAG-3" exactly as a person said it.

The board UI

get_board_summary and get_todo are bound to the board UI (ui://todos/main). A host that supports MCP Apps shows the board, or the to-do, when the agent calls them. The board reads and changes data only through the same tools.

More

Licence

MIT. See LICENSE.