todo-cli-tool 0.3.0

A CLI tool for managing personal TODOs across life categories and project directories

todo-cli-tool

A fast, project-aware CLI for managing personal TODOs across your life.

Manage TODOs from the terminal with priorities, life categories, and automatic project detection. Cross-LLM integration via per-project .todos.md files and LLM config file pointers. Launch AI coding sessions directly from your TODO list.

Features

• Life Categories: Organize TODOs across Work, Family, Health, Hobbies, and custom categories.
• Priority System: Five priority levels (Critical to None) with color-coded Rich output.
• Project-Aware: Auto-detects your project from the working directory — no flags needed.
• Cross-LLM Integration: Auto-generates .todos.md and updates claude.local.md / AGENTS.local.md so your AI assistant (Claude, Codex, Gemini, OpenCode) always knows your TODOs.
• LLM Quick Start: Run todo start <id> to mark a TODO as in-progress and launch your preferred LLM with the TODO as the prompt.
• Beautiful Output: Rich-powered tables and detail panels with overdue highlighting.
• Self-Update: Check for new versions and upgrade in-place with todo update.
• Single YAML Store: All TODOs in one file (~/.todo/todos.yml) — easy to backup, sync, or inspect.

Demo

$ todo add "Implement auth middleware" -p 1 -c Work -dd 2026-04-01 -t backend,auth
Created TODO [a3f7b2]: Implement auth middleware

$ todo list
┏━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ ID       ┃ Pri        ┃ Title                      ┃ Category     ┃ Status       ┃ Due            ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ a3f7b2   │ Critical   │ Implement auth middleware   │ Work         │ todo         │ 2026-04-01     │
└──────────┴────────────┴────────────────────────────┴──────────────┴──────────────┴────────────────┘

$ todo done a3f7b2
Marked [a3f7b2] as done

$ todo start a3f7b2 claude
Started [a3f7b2]
# Launches: claude "Implement auth middleware" -n "todo:a3f7b2"

Tech Stack

• Python 3.11+ — Language
• Typer — CLI framework
• Rich — Terminal output
• Pydantic — Data validation
• PyYAML — Data storage
• uv — Package management
• pytest — Testing
• ruff — Linting & formatting
• mypy — Type checking

Getting Started

Prerequisites

• Python 3.11 or higher
• uv (recommended) or pip

Install from PyPI

pipx install todo-cli-tool

Or install from source

git clone https://github.com/lucasluize-tech/cli-todo.git
cd cli-tools
uv venv --python 3.13
source .venv/bin/activate
uv pip install -e .

Add todo to your PATH

Symlink the binary so it's available globally, without needing to activate the venv:

ln -sf "$(pwd)/.venv/bin/todo" ~/.local/bin/todo

Make sure ~/.local/bin is in your PATH. Then you can run todo from anywhere.

Verify the installation

todo --help

Usage

Managing TODOs

# Add a TODO with priority, category, due date, and tags
todo add "Buy groceries" -p 2 -c Family -dd 2026-04-15 -t errands

# List all TODOs
todo list -a

# List TODOs for the current project (auto-detected)
todo list

# Filter by category, priority, status, or tag
todo list -c Work -p 1
todo list --tag backend

# Show full details of a TODO
todo show a3f7b2

# Edit a TODO
todo edit a3f7b2 --title "New title" -p 3

# Mark as in-progress and launch an LLM session
todo start a3f7b2           # uses default LLM (claude)
todo start a3f7b2 codex     # override with specific LLM
todo done a3f7b2

# Archive completed TODOs
todo archive a3f7b2
todo archive --all-done

# Delete a TODO (with confirmation)
todo delete a3f7b2

# Check version
todo --version

# Check for updates and upgrade
todo update

# Force reinstall
todo update --force

Configuration

Project Roots (important!)

Project roots are parent directories that contain your projects. The tool uses these to auto-detect which project you're working in based on your current directory.

By default, ~/projects and ~/work are configured. If your projects live elsewhere, add your own roots:

# List configured project roots
todo config roots list

# Add a project root
todo config roots add ~/code
todo config roots add ~/personal

# Remove a project root
todo config roots remove ~/work

How it works: If ~/projects is a root and you run todo add from ~/projects/my-app, the tool detects my-app as the project. TODOs are tagged with this project and a .todos.md file is generated at ~/projects/my-app/.todos.md.

If your cwd is not inside any configured root, no project is detected and no .todos.md is generated.

Categories and Defaults

# List categories
todo config categories list

# Add/remove categories
todo config categories add "Pets"
todo config categories remove "Social"

# Set defaults
todo config defaults set priority 2
todo config defaults set category "Family"

LLM Integration

Configure which LLM to use and which config files to generate:

# Set default LLM for `todo start`
todo config defaults set llm claude       # claude, codex, gemini, opencode

# Choose which files to generate (comma-separated)
todo config defaults set llm_files claude,agents

# Use local files (default) or shared files
todo config defaults set llm_files_local true   # claude.local.md, AGENTS.local.md
todo config defaults set llm_files_local false  # CLAUDE.md, AGENTS.md

By default, todo writes to claude.local.md and AGENTS.local.md (local-first, not committed to git). Set llm_files_local to false if you want the shared variants.

Project Integration

# Regenerate .todos.md and CLAUDE.md for the current project
todo generate

# Regenerate for all projects
todo generate -a

When you run todo add or todo done from within a configured project root, the tool automatically:

1. Detects the project from your working directory
2. Regenerates .todos.md at the project root
3. Updates LLM config files (claude.local.md, AGENTS.local.md by default) with open TODO counts

Project Structure

cli-tools/
├── src/todo/
│   ├── cli.py          # Typer app, command definitions
│   ├── models.py       # Pydantic models (Todo, Config)
│   ├── store.py        # YAML read/write, file locking
│   ├── renderer.py     # Rich output formatting
│   ├── project.py      # Project detection, .todos.md generation
│   ├── config.py       # User config management
│   └── sync.py         # Cloud sync interface (stub)
├── tests/              # 109 tests, 84% coverage
├── .github/workflows/  # CI + Release pipelines
└── pyproject.toml

Contributing

This is an open-source project and contributions are welcome.

Fork the repository, make your changes, and open a pull request. Please ensure tests pass before submitting:

uv run pytest
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

License

MIT