todo

Portable CLI for project TODO.md files. Single binary, zero dependencies.

Quick Start • CLI • Dashboard • API • Build • Agent Skill • Site

---

Overview

todo manages tasks, actors, and comments directly in a plain-text TODO.md file — no database, no cloud, no lock-in. Everything stays version-control friendly and editable in any text editor.

When you need a visual interface, todo dashboard spawns an embedded web server with a full-featured dashboard.

AI Agent Skill

Install the todo skill into your AI coding agent (opencode, Cline, etc.) with one command:

npx skills add rayanbo/todo/skills

This teaches the agent all CLI commands, the data model, the HTTP API, and dashboard features. Also available as skills/SKILL.md.

---

Demo

Quick Start

# Initialize a new TODO file (supports Markdown and YAML)
todo init

# Add your first task
todo add --task "Set up CI pipeline" --actors u0v1

# Add an actor
todo add --actor "Alice" --pic https://example.com/alice.png

# Auto-detect TODOs in source code
todo scan

# Open the web dashboard
todo dashboard

Storage

All data lives in a single file — TODO.md (Markdown) or TODO.yaml (YAML) — at the project root. Switch between them with todo cwi.

# Tasks

- [ ] a1b2 **Set up CI pipeline**
    - **Actors**: u0v1
    - **Created**: 2026-07-07 12:00

# Actors

- u0v1 **Teddy**
    - **Pseudo**: Teddy-Dev
    - **Pic**: https://...
    - **Type**: Human

# Comments

- c1d2 **Comment**
    - **Text**: Let's use GitHub Actions
    - **Task**: a1b2

CLI Commands

| Command | Description | |---|---|---| | todo init [--force] [--yaml] [--both] | Create a new TODO file (md, yaml, or both) | | todo add --task <desc> [--actors ids] [--position url] | Create a task | | todo add --actor <pseudo> [--pic url] | Create an actor | | todo add --comment <text> --task-id <id> | Add a comment to a task | | todo list [--tasks] [--actors] [--comments] | List items in the terminal | | todo update <id> [--description] [--due] [--name] [--text] [--position] | Update any item | | todo delete <id> | Delete an item (cascades to references) | | todo status <id> --set <status> [--reason] | Change task status | | todo scan | Scan source files for TODO: comments and add as tasks | | todo cwi [md\|yaml] | Switch between Markdown and YAML format | | todo dashboard | Start the web dashboard |

Status tokens: [ ] todo · [~] in progress · [x] done · [B] blocked

Web Dashboard

Start it with todo dashboard, then open the provided URL in your browser.

• List view — tasks grouped by status with a detail panel, full CRUD, and clickable Position links
• Kanban view — 4 columns (Todo, In Progress, Done, Blocked) with drag & drop and position links
• Format switcher — toggle between TODO.md and TODO.yaml from the header when both exist
• 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

HTTP API

Route	Method	Purpose
/api/todo	GET	Fetch full project data (JSON)
/api/formats	GET	List available formats + active format
/api/cwi	POST	Switch active format
/api/add-task	POST	Create a task
/api/add-actor	POST	Create an actor
/api/add-comment	POST	Create a comment
/api/update	POST	Update any item
/api/delete	POST	Delete any item
/api/status	POST	Change task status

Build from Source

Requires Rust 1.75+.

cargo build --release
cargo test

The binary is placed at target/release/todo.exe.

---

Architecture

todo (Rust CLI)
  → .todo/config (format preference)
  → TODO.md / TODO.yaml (flat-file storage)
  → Rust HTTP server (TcpListener)
  → dashboard/index.html (static SPA)

• IDs are 4-character alphanumeric, auto-generated
• Deleting an actor or comment strips it from all tasks (cascading delete)
• Dashboard auto-finds a free port starting at 8383

---

Built by Rayan Rav · Forked from kanban · MIT License