todos.md
Are you an agent?

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.

Agent Integrations

todos.md gives agents a task API they can trust. Agents should read the backlog, claim work, update status, and report what changed.

Supported hosts

AgentExpected setup
CodexCLI, MCP, and API key access to the hosted workspace.
Claude CodeMCP and API key access with task and run tools.
TakumiCLI, MCP, and API key access for hosted plan execution.
OpenCodeMCP registration through the host config.
AntigravityMCP and API key access through the agy host.
MCP hostsAny host that can call the todos MCP gateway.

Adapter contracts

The first-class hosted adapters are Codex, Claude Code, and Takumi. Each adapter uses the same project, todos, plan, and run contract so a plan can move between hosts without changing task state.

AdapterSurfacesGoal command
CodexCLI, MCP, API/goal execute <plan-id> with todos.md
Claude CodeMCP, API/goal execute <plan-id> through todos MCP
TakumiCLI, MCP, API/goal execute <plan-id> with takumi

Hosted setup

  1. Install the public local package with Bun.
  2. Register the todos MCP server for the host agent.
  3. Create a scoped hosted API key for tasks, plans, runs, and storage.
  4. Store the key in the agent environment as PLATFORM_TODOS_API_KEY.
Install
bun install -g @hasna/todos
Codex MCP
todos mcp --register codex
Claude MCP
todos mcp --register claude
All local MCP hosts
todos mcp --register all

Check available surfaces

Hosted catalog
platform-todos docs catalog --surface mcp

Agent flow

  1. Read the current task list.
  2. Claim one task.
  3. Work in the repo.
  4. Add comments when state changes.
  5. Mark the task done only after verification.

Plan execution contract

Every hosted adapter follows the same steps:

  1. Resolve the active project.
  2. Read the plan and ordered task graph.
  3. List tasks and skip blocked dependencies.
  4. Claim exactly one task.
  5. Add progress comments during execution.
  6. Run the agent against the requested plan step.
  7. Upload verification evidence, logs, receipts, or artifacts.
  8. Comment with the verification commands and evidence references.
  9. Complete the task only after evidence exists.
  10. Report safe failure details if execution cannot finish.

Verification evidence upload uses /api/v1/runs/{runId}/artifacts/upload-url and must include run id, content type, byte size, file name, and checksum.

Clear failure messages

FailureAgent behavior
Missing authCreate a scoped API key before claiming work.
MCP unavailableRe-register the host MCP server and retry without changing task state.
Plan blockedAdd a blocker comment and stop downstream execution.
Evidence missingUpload logs or command output before completion.
Unknown failurePreserve safe run logs and report the last non-secret error.

MCP tools

The MCP gateway should expose tasks, projects, runs, feedback, docs, and organization context from the same API as the CLI.

bun install -g @hasna/todos