| name | todo |
| description | TODO CLI — portable terminal-based task manager for project TODO.md files. Manage tasks, actors, comments, tags, priorities, due dates. Single Rust binary, zero dependencies, Markdown storage.
|
todo — TODO CLI Agent Skill
Links
Install
Windows (MSI)
curl -LO https://github.com/RayanBO/todo/releases/latest/download/todo-x64.msi
todo-x64.msi
Windows (exe)
curl -LO https://github.com/RayanBO/todo/releases/latest/download/todo-x64.exe
macOS (ARM64)
curl -LO https://github.com/RayanBO/todo/releases/latest/download/todo-macos-arm64
chmod +x todo-macos-arm64
sudo mv todo-macos-arm64 /usr/local/bin/todo
Linux (x64)
curl -LO https://github.com/RayanBO/todo/releases/latest/download/todo-linux-x64
chmod +x todo-linux-x64
sudo mv todo-linux-x64 /usr/local/bin/todo
Cargo
cargo install todo-cli
Quick Start
todo init
todo init --md
todo add --task "My task" --actors u0v1 --priority high
todo list
todo dashboard
Config
A .todo/config file stores the current working format. Created automatically when you switch formats or init with a specific format. Content is md or yaml.
CLI Commands
todo init
Create a new TODO file. Supports interactive prompts and explicit flags.
todo init [--force] [--yaml] [--md] [--both]
- No flags and no file exists → interactive prompt: "Initialize TODO.md? (Y/n)" or "Initialize TODO.yaml? (Y/n)"
- No flags but one format exists → "Checking..." → "Initialize TODO.yaml? (Y/n)"
- No flags but both exist → error with
--force suggestion
--yaml — create TODO.yaml--md — create TODO.md--both — create both TODO.md and TODO.yaml--force — overwrite existing file(s)
todo add --task
Create a task.
todo add --task <description> [--actors <ids>] [--tags <labels>] [--priority <level>] [--due <date>] [--position <url>]
--task — description (required)--actors — comma-separated actor IDs--tags — comma-separated labels--priority — low|medium|high--due — YYYY-MM-DD HH:MM--position — code position URL (e.g. file:///path/to/file#L42:10)
todo add --actor
Create an actor.
todo add --actor <pseudo> [--pic <url>]
todo add --comment
Add a comment to a task.
todo add --comment <text> --task-id <id>
todo list
List items. Shows tasks with status, priority, actors, tags. Supports filtering.
todo list [--tasks] [--actors] [--comments] [--status <status>] [--search <query>] [--tag <labels>] [--priority <level>] [--overdue]
todo update
Update any item by ID.
todo update <id> [--description <text>] [--due <date>] [--priority <level>] [--actors <ids>] [--tags <labels>] [--name <pseudo>] [--pic <url>] [--text <text>] [--position <url>]
--position — change the code position URL
todo status
Change task status.
todo status <id> --set <status> [--reason <text>]
--set — todo|en-cours|done|bloqued--reason — required when setting to bloqued
todo cwi
Switch current working file format between Markdown and YAML.
todo cwi [md|yaml]
- With no argument — shows current format (reads
.todo/config)
- With format — switches to that format (target file must exist)
- Stores preference in
.todo/config
todo scan
Recursively scan source files for TODO: comments and add them as tasks with code positions.
todo scan
Skips .todo/, .git/, node_modules/, target/, .opencode/, .agents/, binary/media files, and existing TODO files. Each found comment becomes a new task with position set to the exact file location. Already tracked tasks (by position) are skipped.
todo tags
List all tags with task counts.
todo tags
todo search
Search tasks by query text.
todo search <query>
todo upgrade
Check for updates on GitHub and upgrade the binary.
todo upgrade [--yes]
- Fetches the latest release tag from GitHub API
- Compares with current version
- Downloads and replaces the binary (Windows only)
--yes — skip confirmation prompt
todo completion
Generate shell completion scripts.
todo completion bash|zsh|powershell|fish|elvish
todo install
Copy binary to PATH (Windows).
todo install
todo delete
Delete an item by ID. Cascades to all references.
todo delete <id>
todo dashboard
Start the web dashboard server on port 8383.
todo dashboard
Project State
A project lives in a single file — either TODO.md (Markdown) or TODO.yaml (YAML). Switch between formats with todo cwi. The file has three sections:
# Tasks — array of task objects# Actors — array of actor objects# Comments — array of comment objects
Task fields
| Field | Type | Description |
|---|---|---|---|---|
| id | string | 4-char alphanumeric (auto-generated) |
| description | string | Task description |
| status | "todo"|"en-cours"|"done"|"bloqued" | Current status |
| priority | "low"|"medium"|"high"|null | Priority level |
| tags | string[] | Labels |
| actors | string[] | Actor IDs assigned |
| created | datetime|null | Creation timestamp |
| due | datetime|null | Due date |
| blocked_reason | string|null | Reason if blocked |
| comments | string[] | Comment IDs |
| position | string|null | Code position URL (e.g. file:///path/to/file#L42:10) |
Actor fields
| Field | Type |
|---|
id | 4-char alphanumeric |
pseudo | string |
pic | string|null |
actor_type | "Human"|"AgentIa"|null |
Comment fields
| Field | Type |
|---|
id | 4-char alphanumeric |
text | string |
task | string (parent task ID) |
actors | string[] |
HTTP API
The dashboard server exposes a JSON API at /api on http://localhost:<port> (default 8383):
| Method | Route | Purpose |
|---|
| GET | /api/todo | Full project data |
| GET | /api/formats | List available formats + current |
| POST | /api/cwi | Switch active format |
| POST | /api/add-task | Create task |
| POST | /api/add-actor | Create actor |
| POST | /api/add-comment | Create comment |
| POST | /api/update | Update any item |
| POST | /api/delete | Delete any item |
| POST | /api/status | Change task status |
Dashboard UI
- List view — tasks grouped by status with detail panel and full CRUD, displays Position column with copy button
- Kanban view — 4 columns (Todo, En cours, Done, Bloqued) with drag & drop, shows position with copy button
- Format switcher — toggle between TODO.md and TODO.yaml from the header
- Position field — displayed as text with a
copy button; clicking copies the full file URL to clipboard (no editor links)
- Modals — add/edit tasks, actors, and comments inline, including the Position field
- Search & filter — filter by actor, tag, priority, and status
- Theme — dark/light mode with system preference detection
Agent Install
For AI coding agents (opencode, Cline, etc.), install this skill with one command:
npx skills add rayanbo/todo/skills
Or copy skills/SKILL.md to your agent's skills folder (e.g. .opencode/skills/todo/SKILL.md).
