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.

Overview

todos.md is local-first task management for agents with an optional hosted control plane. People write plans and review the trail. Agents use the local CLI by default, and use the hosted CLI, API, or MCP only when a team explicitly signs in.

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.

UseRun /goal plans

Give Codex or Claude Code a project plan and review the task, run, and evidence trail.

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. Bootstrap the repo and add todos locally.
  3. Attach a plan with priorities and context.
  4. Give Codex or Claude Code a goal that points at the local plan.
  5. Use platform-todos only when you want hosted auth, API keys, billing, imports, or MCP access.
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 local MCP or the hosted onboarding path.

bun install -g @hasna/todos