todos.md

todos.md documentation

Run shared task work with agents.

Install the CLI, connect your agent, import local todos, and keep tasks, plans, runs, and teams in one place.

Overview

todos.md is headless task management for agents. People write plans and review the trail. Agents use the CLI, API, or MCP to claim and finish work from the same source of truth.

What you can do

StartQuickstart

Install the public package and create your first local task.

UseWork with tasks

List tasks, add work, start it, finish it, and inspect state.

OperateUnderstand pricing

See the free 1,000 task / 10 project limits and what Pro unlocks.

OperateOperate hosted runs

Track async work, logs, artifacts, and receipts.

Mental model

  1. Install @hasna/todos once with Bun.
  2. Create a project and add todos locally.
  3. Attach a plan with priorities and context.
  4. Give Codex or Claude Code a /goal that points at the plan.
  5. Let agents update tasks through CLI, API, or MCP.
First install
bun install -g @hasna/todos

Local folder contract

The local package keeps task data in the workspace. Hosted integrations should only receive data you explicitly send through authenticated API or MCP operations.

FolderPurpose
.todos/Local task data, agent metadata, and safe config.
.todos/runs/Local run metadata when downloaded or replayed.
.todos/exports/Files exported by explicit commands.

Next step

Follow the quickstart, then connect your agent through MCP.

bun install -g @hasna/todos