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:
| OS | Default 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
| Tool | What it does |
|---|---|
create_todo |
Add one to-do (to the default board unless one is named) |
plan_todos |
Add several to-dos in one call, optionally as the steps of a goal |
update_todo |
Change a to-do's title, details, priority, labels, assignee, due date or goal |
start_todo |
Mark a to-do in progress |
complete_todo |
Mark a to-do done |
block_todo |
Mark a to-do blocked, with the reason |
reopen_todo |
Put a to-do back to open |
cancel_todo |
Mark a to-do as won't do |
reorder_todos |
Set the order of one status lane on a board |
archive_todo |
Hide a to-do from default views, status unchanged |
list_todos |
List or search to-dos, with filters and cursor paging |
get_todo |
Read one to-do whole, with its steps and recent activity |
get_next_todo |
The highest-priority open to-do: what to work on next |
get_board_summary |
A board's lane counts and what needs attention |
list_boards |
List the boards |
create_board |
Create a board |
update_board |
Change 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. A to-do that names no board goes on
the workspace's default board: the first board created, or one made with the key TODO if
there is none. 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
docs/architecture.md: the core, runtimes, data model, the UI binding, errors and annotations.docs/local.md: the database file, several processes, the HTTP token, upgrades and backups.CONTRIBUTING.md: building and testing.
Licence
MIT. See LICENSE.
Metadata
Release files for todosforagents 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| todosforagents-0.4.0.tar.gz | 244.7 kB | With provenance | Details for todosforagents-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| todosforagents-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for todosforagents-0.4.0-py3-none-any.whl |
Total release size: 498.8 kB
Release files / todosforagents-0.4.0.tar.gz
| Download URL | todosforagents-0.4.0.tar.gz |
|---|---|
| Size | 244.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9e313ae7df19d153a076a1ac80d3c1288fa544d6e83b75adafb844b39482af81
|
|
BLAKE2b-256 checksum How to use checksums |
36fe83a3f40354c3528c977e9c5ad8e8741537752b9aeec90e4e23512ca35340
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / todosforagents-0.4.0-py3-none-any.whl
| Download URL | todosforagents-0.4.0-py3-none-any.whl |
|---|---|
| Size | 254.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
20031d9ed539c015556865a41d8b0a53648dd64b2abdb9ea46da9a1fb49614b8
|
|
BLAKE2b-256 checksum How to use checksums |
cd6a39bd47fbdc6702b2aeed605bc855981c63532d877de20077318bf32f2d44
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for todosforagents 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for todosforagents-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.