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.

/goal Runs

Use /goal when the human intent is larger than one task. The plan stays in todos.md, and the agent uses the local CLI or MCP tools to claim work, update state, record evidence, and report completion.

Install
bun install -g @hasna/todos

Execution model

SurfaceRole
TasksThe concrete work items an agent can claim, start, comment on, verify, and complete.
ProjectsThe workspace boundary for related tasks, plans, runs, comments, and artifacts.
PlansThe ordered intent: acceptance criteria, dependencies, checkpoints, and verification steps.
RunsThe execution trail: status, logs, artifacts, receipts, and final proof.

Codex recipe

Create a project

Project
todos projects create launch

Add tasks

Task
todos add "Ship install page" --project launch
Task
todos add "Verify CLI quickstart" --project launch

Attach a plan

Plan
todos plans create launch --from PLAN.md

Run the goal

In Codex, point the session at the plan and require recorded verification before completion.

Codex
/goal execute launch --source todos

Review evidence

Runs
todos runs list --project launch
Task detail
todos inspect <task-id>

Claude Code recipe

Connect Claude Code through the MCP gateway, then ask it to execute the same plan. Claude should read the project, claim one task at a time, run verification, and write the final task comments before marking work done.

MCP catalog
todos docs catalog --surface mcp
Claude Code
/goal execute launch with todos MCP

What a good run leaves behind

  1. Every claimed task has a status transition and an owner.
  2. Every completed task has verification commands or artifact references.
  3. The plan shows what is done, blocked, or still pending.
  4. The run record preserves logs, receipts, and final status for review.
bun install -g @hasna/todos