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.

Headless Onboarding

Use this path when a team wants hosted todos.md without browser task management. People keep the plan in the repo. Agents use the local OSS CLI, hosted CLI, API, or MCP.

Install the local OSS CLI

Install the package agents use inside the repo.

Install
bun install -g @hasna/todos

Authenticate the hosted CLI

The hosted CLI requests an email code, verifies it, and stores an API key in the selected profile.

Request code
platform-todos auth login --email [email protected]
Verify profile
platform-todos --json auth status
Verify identity
platform-todos --json auth whoami

CI and agent runners can inject an existing key without writing a profile.

Environment key
PLATFORM_TODOS_API_KEY=ak_example_redacted platform-todos --json auth whoami

Check MCP discovery

Ask the hosted service for the MCP catalog before connecting an agent. The catalog should include get_docs_catalog, list_tasks, create_task, and list_runs.

MCP catalog
platform-todos docs catalog --surface mcp --json

Create the local project workflow

Create one project, add todos, attach the plan, and hand execution to an agent with /goal.

Create project
todos projects create website-launch
Add todo
todos add "Draft launch notes" --project website-launch
Add QA todo
todos add "Run production smoke test" --project website-launch
Attach plan
todos plans create website-launch --from PLAN.md
Run agent
/goal execute website-launch

Mirror remote work when needed

Hosted tasks and run controls stay explicit. Use idempotency keys for mutations so retries are safe.

Create hosted task
platform-todos tasks add "Review launch" --idempotency-key launch-1
List hosted tasks
platform-todos tasks list --status pending
Set run controls
platform-todos runs controls --budget-cents 5000 --max-run-cost-cents 500
Check capabilities
platform-todos api get /api/v1/capabilities --json

What success looks like

platform-todos --json auth status returns a JSON object with signedIn, apiUrl, source, and the active profile.

platform-todos docs catalog --surface mcp --json returns schemaVersion, a list of MCP operations, and schemas agents can read before calling tools.

todos list shows the local project todos, while hosted commands show only the remote tasks you explicitly created or imported.

Agent handoff

After onboarding, give Codex, Claude Code, Takumi, or another MCP-capable agent the project slug and the plan. The agent should read the backlog, claim one task, run the work, add comments or evidence, and only mark tasks done after verification.

bun install -g @hasna/todos