todos.md1
Install locally
Use Bun to install @hasna/todos. Local task state stays on the machine unless you explicitly export or send it.
Headless tasks for agents.
Tasks and plans agents can run from the terminal. Start locally with the public @hasna/todos CLI. When a team needs shared hosted state, give Codex, Claude Code, or Takumi scoped CLI, API, or MCP access.
Install
bun install -g @hasna/todosCodexClaude CodeTakumiOpenCodeAntigravityMCP hosts
Agent run
one project flow
Create a project
$ todos projects create website-launch
project website-launch ready
Add todos
$ todos add "Rewrite install docs" --project website-launch
task created with priority, owner, and history
Attach a plan
$ todos plans create website-launch --from PLAN.md
plan ready for task grouping
Agent runs the work
$ /goal execute website-launch
agent claims tasks, comments progress, and verifies completion
Done
projects, tasks, plans, and run logs stay queryable by CLI, API, or MCP
How it works
Three steps. One agent-readable source of truth.
2
Create work
Bootstrap the repo, add tasks, and attach a plan with priorities, owners, comments, and status.
3
Add hosted access
For shared workspaces, use platform-todos auth login, billing status, API keys, and MCP discovery.
Run a /goal against a real plan.
todos.md keeps the working trail in task state: create a project, add tasks, attach a plan, then let an agent claim and verify work through CLI or MCP.
Tasks
Small units of work with owner, status, priority, dependencies, comments, and verification evidence.
Projects
A local workspace boundary that keeps related tasks, plans, runs, and agent context together.
Plans
Ordered intent: acceptance criteria, dependencies, checkpoints, and the work an agent should execute.
Runs
Execution records for agent work, including logs, artifacts, status, receipts, and final proof.
1
Create the local workspace
Bootstrap the current repo so people and agents read the same local task state.
todos projects create launch
2
Add tasks and a plan
Create a task, group it under a plan, and keep the context in the CLI trail.
todos add "Ship install page" --project launch && todos plans create launch --from PLAN.md
3
Review the run trail
Agents should claim work, comment progress, record verification, and finish only after review.
/goal execute launch --source todos
You stay in control.
Local OSS stays local. Hosted features start only after explicit auth, API, MCP, import, or billing commands.
Local boundary
@hasna/todos works locally without default cloud calls.
Agent access
Agents use CLI locally; hosted work uses platform-todos, API keys, or MCP.
Audit
Task comments, status changes, and runs are logged for review.
Limits
Free is free forever up to 1,000 tasks and 10 projects. Pro unlocks unlimited tasks, unlimited projects, and hosted runs.
Everything the app can do.
todos.md is headless and agent-native: the landing page explains the product, while CLI, API, and MCP surfaces manage the actual work without a web app sign-in flow.
Tasks
- Create, list, show, start, block, fail, and complete work.
- Track priority, owner, status, due dates, tags, and verification notes.
Projects
- Group tasks by project without moving work out of the repo.
- Focus agents on the active project before they claim shared work.
Plans
- Turn a plan into ordered work for an agent to execute.
- Let Codex or Claude Code use /goal against a plan.
Agent Workflows
- Let agents read context, claim one task, update status, and post verification.
- Keep plan execution, handoffs, and acceptance checks in the same task trail.
Agent Runs
- Track agent runs, logs, artifacts, status, and receipts.
- Resume longer work by run id through API or MCP.
Dependencies and Blockers
- Model work that must happen before another task can start.
- Mark blockers clearly so agents do not claim impossible work.
Comments and Activity
- Record decisions, handoffs, verification, and status changes.
- Keep an audit history for every important task movement.
Evidence and Artifacts
- Attach run output, receipts, logs, and generated files to context.
- Keep proof of completion next to the work agents completed.
Search and Views
- Filter by project, status, owner, priority, tag, and query.
- Give agents focused views instead of a noisy global backlog.
Quotas and Billing
- Free is free forever up to 1,000 tasks and 10 projects.
- Pro unlocks unlimited tasks, unlimited projects, and hosted runs.
Usage Metering
- Report task, project, plan, run, storage, API, and worker usage.
- Reconcile hosted usage with billing and audit evidence.
API Keys and Service Accounts
- Issue scoped credentials for agents and automation.
- Separate human sessions from machine access in hosted workspaces.
Team Access
- Invite members, assign roles, and protect organization-scoped work.
- Keep evidence, runs, billing, and API keys under tenant boundaries.
Webhooks and Notifications
- Send agent-native events when tasks, runs, imports, or billing states change.
- Feed GitHub CI, support, and automation inboxes without browser actions.
CLI and MCP
- Use command and tool surfaces instead of browser workflows.
- Register agents, claim tasks, send heartbeats, and report progress.
Imports and Exports
- Import existing local todos and migrate shared project state.
- Export task data, run evidence, and audit-friendly records.
Local OSS Boundary
- Keep the public @hasna/todos package local-first by default.
- Make hosted cloud operations explicit through API, MCP, or billing commands.
Agent surfaces
The browser explains the product. Actual work happens through command and tool surfaces that agents can call directly.
CLI
Install @hasna/todos with Bun and run tasks from the terminal.
MCP
Expose structured tools for agents that should not scrape text.
API
Build integrations that need authenticated shared state and tenant boundaries.
Comments
Record decisions, blockers, and verification evidence.
Activity
Review task history, run status, and recent project movement.
Templates
Create repeatable task shapes for bugs, launches, and audits.
Simple pricing.
Free forever up to 1,000 tasks and 10 projects. Pro is $10/mo for unlimited tasks, unlimited projects, and hosted automation.
Free
$0
Free forever
- Local CLI
- 1,000 hosted tasks
- 10 hosted projects
Pro
$10/mo
For teams
- Unlimited hosted tasks
- Unlimited hosted projects
- API keys and billing portal
Enterprise
Custom
For companies
- SSO and compliance
- Custom rates
- Dedicated support
Plan access
Free covers 1,000 hosted tasks and 10 hosted projects. Pro removes those hosted quota limits.
Hosted surfaces
Hosted tasks, plans, run controls, audit exports, storage, and billing are explicit CLI, API, or MCP operations.
Compare plans
| Free | Pro | Enterprise | |
|---|---|---|---|
| Pricing | |||
| Monthly | Free forever | 10 USD | Custom |
| Hosted tasks | 1,000 | Unlimited | Custom |
| Hosted projects | 10 | Unlimited | Custom |
| Features | |||
| Local CLI | Included | Included | Included |
| API keys | - | ✓ | ✓ |
| Billing portal | - | ✓ | ✓ |
| Web app actions | - | - | - |
| All agent platforms | ✓ | ✓ | ✓ |
| Hosted runs | Launch-gated | Paid surface | Custom |
| Security | |||
| Access control | Basic | Team | Enterprise |
| SSO (SAML / OIDC) | - | - | ✓ |
| Self-hosted | - | - | ✓ |
FAQ
Is the Free plan really free?
Yes. Free is free forever up to 1,000 tasks and 10 projects.
What costs extra?
Pro unlocks unlimited hosted task and project quotas, API keys, team administration, and billing portal access. Local open source todos stay local.
Which agents are supported?
Codex, Claude Code, Takumi, OpenCode, Antigravity, and any MCP-compatible host.