Skip to main content

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

Metadata

Release files for todosforagents 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for todosforagents 0.2.0
File Size Uploaded Provenance Actions
todosforagents-0.2.0.tar.gz 241.7 kB With provenance Details for todosforagents-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for todosforagents 0.2.0
File Interpreter ABI Platform Actions
todosforagents-0.2.0-py3-none-any.whl Python 3 none any Details for todosforagents-0.2.0-py3-none-any.whl

Total release size: 492.8 kB

Release files / todosforagents-0.2.0.tar.gz

Download URL todosforagents-0.2.0.tar.gz
Size 241.7 kB
Tags Source
SHA-256 checksum
How to use checksums
cfbd26994c25e2bcbaa2f4cca95cac1c2af4ca6075a611279afbed441bf965ec
BLAKE2b-256 checksum
How to use checksums
90be2f7962525cb8fe1924714ab6390dbfc0ed4e7255cdd09e09d0301dbd046a
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 15, 2026.

Transparency log

Release files / todosforagents-0.2.0-py3-none-any.whl

Download URL todosforagents-0.2.0-py3-none-any.whl
Size 251.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
25f88313f305e7eb267d89406c10ac9dc6f762e4fb364eb44f541e381c9c529a
BLAKE2b-256 checksum
How to use checksums
fe3ab7eb20683ff598269291b52b96bb1a555a7ce30812c2d91e7ac4d7057942
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 15, 2026.

Transparency log

Security for todosforagents 0.2.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.

Select from 2 files

Attestation for todosforagents-0.2.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 15, 2026.

Transparency log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page