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.

Prompts

Prompt What it does
get_started Start your list, or pick it up. With focus (what you are working on), the agent proposes 3 to 5 to-dos for it; without, it checks your board first

Hosts that surface prompts, as slash commands for example, offer it as "Get started with your to-dos".

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

Licence

MIT. See LICENSE.

Metadata

Release files for todosforagents 0.6.1

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.6.1
File Size Uploaded Provenance Actions
todosforagents-0.6.1.tar.gz 246.6 kB With provenance Details for todosforagents-0.6.1.tar.gz

Built distribution (wheel)

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

Total release size: 503.0 kB

Release files / todosforagents-0.6.1.tar.gz

Download URL todosforagents-0.6.1.tar.gz
Size 246.6 kB
Tags Source
SHA-256 checksum
How to use checksums
6fb14bfbd124be9b650128b6615ba9145b89c7ab26d208c1f7e9becc9030c041
BLAKE2b-256 checksum
How to use checksums
d5eb3b20a77a37eff1b84fff907198d077b609780c1de9a235362d18bde9ed89
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 19, 2026.

Transparency log

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

Download URL todosforagents-0.6.1-py3-none-any.whl
Size 256.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
523c272e6efbe3975cce76221ca16539bd59186745deabf7979f2610f88ddae7
BLAKE2b-256 checksum
How to use checksums
5522ab7586870899e3ddaee38b2d3afbd0214ef116cf0a9c5c746512c66929ab
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 19, 2026.

Transparency log

Security for todosforagents 0.6.1

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.6.1.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 19, 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