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 or Claude Code run the work through /goal.
Install
bun install -g @hasna/todosCodexClaudeGeminiCursorOpenCodeMCP 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 or Claude Code to use /goal, then let the agent claim tasks and report verification.
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: tasks, projects, plans, runs, CLI, API, and MCP all describe the same work without a web app sign-in flow.
Tasks
- Create, list, show, start, block, fail, and complete work.
- Use priority, owner, status, dependencies, due dates, tags, and comments.
- Keep an audit history for every important task change.
Projects
- Group tasks by project without moving work out of the repo.
- Focus agents on the active project before they claim work.
- Track free limits at 1,000 tasks and 10 projects.
Plans
- Turn a plan into ordered work for an agent to execute.
- Let Codex or Claude Code use /goal against a plan.
- Preserve comments and verification notes as the plan changes.
Runs
- Track agent runs, logs, artifacts, status, and receipts.
- Resume longer work by run id through API or MCP.
- Keep run output attached to the project context.
Agent Access
- Use CLI, MCP, and API surfaces instead of browser workflows.
- Register agents, send heartbeats, claim tasks, and report progress.
- Support Codex, Claude Code, Gemini, Cursor, OpenCode, and MCP hosts.
Security
- Separate the local OSS package from hosted cloud operations.
- Use API keys, tenant isolation, and explicit access boundaries.
- Avoid putting production secrets into local task files.
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.
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, Gemini, Cursor, and any MCP-compatible host.