todos.md1
Install
Use Bun to install @hasna/todos, the public local package agents can run from the terminal.
Headless tasks for agents.
Install the public local package, create projects and todos, attach plans, and let Codex, Claude Code, or Takumi run the work through /goal.
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 linked to the project backlog
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
Add work
Create a project, add todos, and attach a plan with priorities, owners, comments, and status.
3
Run the plan
Ask Codex, Claude Code, or Takumi to use /goal, then let the agent claim tasks and report verification.
Run a /goal against a real plan.
todos.md turns a goal into a local execution loop: create the project, add tasks, attach the plan, then let an agent claim and verify the 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 backlog
Start with one local project, a small task list, and a plan the agent can inspect.
todos projects create launch && todos add "Ship install page" --project launch
2
Give the agent a goal
Codex or Claude Code can point /goal at the project plan instead of a browser workflow.
/goal execute launch --source todos
3
Review the run trail
The result is tasks, comments, verification commands, artifacts, and completion status.
todos runs list --project launch && todos inspect <task-id>
You stay in control.
Local OSS stays local. Hosted features stay explicit. Full audit trail.
Local boundary
@hasna/todos works locally without default cloud calls.
Agent access
CLI, API, and MCP are the working surfaces.
Audit
Task comments, status changes, and runs are logged for review.
Limits
Free is 1,000 tasks and 10 projects. Pro is unlimited.
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
- 1,000 tasks
- 10 projects
- CLI and MCP
Pro
$10/mo
For teams
- Unlimited tasks
- Unlimited projects
- Hosted runs
Enterprise
Custom
For companies
- SSO and compliance
- Custom rates
- Dedicated support
Plan access
Free covers 1,000 tasks and 10 projects. Pro removes task and project limits.
Hosted runs
Agents can queue work and return logs, artifacts, and status through CLI, API, or MCP.
Compare plans
| Free | Pro | Enterprise | |
|---|---|---|---|
| Pricing | |||
| Monthly | Free forever | 10 USD | Custom |
| API calls | Included | Unlimited | Custom |
| Hosted runs | Limited | Included | Custom |
| Features | |||
| Tasks | 1,000 | Unlimited | Custom |
| Projects | 10 | Unlimited | Custom |
| Web app actions | - | - | - |
| All agent platforms | ✓ | ✓ | ✓ |
| Remote runs | Limited | ✓ | ✓ |
| 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 tasks and projects plus hosted automation. Local open source todos stay local.
Which agents are supported?
Codex, Claude Code, Takumi, OpenCode, Antigravity, and any MCP-compatible host.