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.3.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.3.0
File Size Uploaded Provenance Actions
todosforagents-0.3.0.tar.gz 242.7 kB With provenance Details for todosforagents-0.3.0.tar.gz

Built distribution (wheel)

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

Total release size: 494.8 kB

Release files / todosforagents-0.3.0.tar.gz

Download URL todosforagents-0.3.0.tar.gz
Size 242.7 kB
Tags Source
SHA-256 checksum
How to use checksums
2e17f1a13df0ec4c488d077f307a0ec6f27facdb475e2a2309a1c10ff2825bb8
BLAKE2b-256 checksum
How to use checksums
ea93ecbbaa5a4cc44fa0ff09aeff73ee1fdbc172c1091d4ab264b9161a1bc5db
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.3.0-py3-none-any.whl

Download URL todosforagents-0.3.0-py3-none-any.whl
Size 252.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
41a45cb3a03991bfbf2a5d846eb643701442cdce012818e4d9b7fc93cfec6706
BLAKE2b-256 checksum
How to use checksums
0a39b4dd4cb15ce7aec91f6b35879f8d94692511fa2f2d53ba4a5dc716b6575d
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.3.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.3.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