ai-todo 3.0.0b17

AI-Agent First TODO List Tracker with MCP and CLI interfaces

todo.ai

Simple, zero-interaction TODO management for AI agents

AI Agent Installation: Copy-paste this to your agent:

Adopt todo.ai for task tracking. Install using:
curl -fsSL https://raw.githubusercontent.com/fxstein/todo.ai/main/install.sh | sh

Then create a task "Implement user authentication" with subtasks:
- Design database schema
- Create API endpoints
- Add frontend components
- Write tests

---

Why todo.ai?

AI agents often track tasks internally, but this creates a closed system that gets lost after time or restarts. todo.ai provides a permanent, version-controlled record that lives in your Git repository.

Key benefits:

• Permanent record: Tasks persist across sessions, restarts, and time
• Version controlled: Tracked in Git alongside your code changes
• Interactive: Add and insert new tasks even while an agent works on a long task list
• Simple: Plain Markdown format that's human-readable and editable
• Standard compliant: Works naturally with the GitHub TODO.md standard

Your task list becomes part of your project history, visible in pull requests, and never gets lost.

---

For AI Agents

Run ./todo.ai --help to see all available commands and usage examples. Everything you need to know is there.

---

For Humans

With todo.ai, you simply tell your AI agent what you want in plain English. Your agent handles all the technical details automatically.

Examples of what you can ask your agent:

Create a task for implementing user authentication

Break down the authentication feature into subtasks

Mark task 1 as complete

Show me all incomplete tasks tagged with #bug

Create a task to convince the coffee machine to understand sarcasm

Your agent understands natural language requests and translates them to the appropriate todo.ai commands. All tasks are tracked in TODO.md in your repository.

---

See It In Action

This repository uses todo.ai for its own development! Check out TODO.md to see:

• Real examples of how tasks are structured with subtasks and tags
• Current development status of the tool itself
• Live demonstration of the task management workflow

The TODO.md file showcases features like:

• Task hierarchies with subtasks
• Tag-based organization (#security, #feature, #bug)
• Task relationships and dependencies
• Completion tracking and archiving
• Development roadmap and priorities

This is the same file structure and workflow you'll use in your own projects with todo.ai.

---

Why not GitHub Issues?

Agents need a fast, local, Markdown-native way to manage tasks. GitHub Issues adds too much complexity and overhead—API calls, authentication, rate limits, and network latency slow down task management.

Key differences:

• Speed: todo.ai is instant and local—no API calls or network delays
• Simplicity: Plain Markdown that agents can parse and modify directly
• Zero overhead: No authentication, rate limits, or API complexity
• Native workflow: Works seamlessly with your Git workflow

But you can still reference GitHub Issues and PRs:

GitHub issue and PR numbers can be tagged onto tasks and subtasks for reference. For example:

• "Create a task for fixing #123"
• "Add subtask 1.1: Address PR #456 feedback"

This keeps todo.ai fast and simple while still maintaining links to your GitHub workflow.

---

Zero Interaction Design

• ✅ No prompts or confirmations
• ✅ No configuration required
• ✅ Instant operations
• ✅ Git-friendly (TODO.md tracked in repo)
• ✅ Works automatically without user input

Perfect for AI agents - just works.

---

Limitations

---

Installation

Stable Release (Recommended)

Requires Python 3.10+

Install via uv (recommended) or pipx for standard CLI and MCP Server support:

# Using uv (recommended - faster, more reliable)
uv tool install ai-todo

# Alternative: pipx
pipx install ai-todo

This installs one unified command: todo-ai.

• CLI Usage: todo-ai [command] (e.g., todo-ai add "Task")
• MCP Server: todo-ai serve (used by Cursor/Claude)

Task Management

• Start: todo-ai start <task_id> marks a task as in-progress.
• Stop: todo-ai stop <task_id> pauses work on a task (optional - complete handles this automatically).
• Complete: todo-ai complete <task_id> marks a task as done.

TODO.md Formatting Standards

todo.ai enforces strict formatting standards (v3.0+) for consistency and parseability:

Visual Structure:

• Managed file with warning header
• Three sections: Tasks, Archived Tasks, Deleted Tasks
• Section separators and consistent spacing
• Footer with tool variant and timestamp

Formatting Rules:

• 2-space indentation per nesting level
• One blank line between root tasks
• No blank lines between subtasks
• Tags wrapped in backticks (`#tag`)
• Notes use blockquote format with proper indentation

Commands (Python CLI v3.0+):

• Lint: todo-ai lint checks formatting violations
• Reformat: todo-ai reformat automatically fixes violations (preserves all data)
• Reorder: todo-ai reorder sorts tasks (newest on top)
• Resolve Conflicts: todo-ai resolve-conflicts fixes duplicate task IDs

Legacy Shell Script (v2.x): Use ./todo.ai prefix instead of todo-ai.

Important: TODO.md is a managed file. Always use todo-ai commands instead of manual edits to maintain formatting integrity.

Quality Gates

todo.ai enforces quality through automated checks:

• Pre-commit: todo-ai lint runs automatically on commit to block invalid TODO.md files.
• CI/CD: GitHub Actions workflow verifies TODO.md integrity and runs regression tests.

Documentation:

• Python Migration Guide - How to upgrade from v2.x (Shell).
• MCP Setup Guide - How to set up Cursor AI integration.

Beta Testing (Help Us Test)

Want to try upcoming features before they're released? Install the latest beta:

# Using uv (recommended)
uv tool install --prerelease=allow ai-todo

# Alternative: pipx
pipx install --pre ai-todo

Beta releases let you test new features and provide feedback before stable release. See Release Channels below for more information.

Alternative Installation Methods

Using pip:

pip install ai-todo              # Stable
pip install --pre ai-todo        # Beta

Recommendation: Use uv tool or pipx for isolated installations that won't conflict with other Python packages.

Development Version

Install from Git to get the latest unreleased code:

# Using uv (recommended)
uv tool install git+https://github.com/fxstein/todo.ai.git@main

# Alternative: pipx
pipx install git+https://github.com/fxstein/todo.ai.git@main

Release Channels

• Stable: Fully tested, production-ready releases (recommended)
• Beta: Feature-complete pre-releases for testing (7+ days before stable for major releases)
• Development: Latest code from main branch (may have bugs)

See CHANGELOG.md for version history and release notes.

Legacy Shell Script (v2.x)

If you cannot use Python, the legacy shell script is still available:

Smart Installer:

curl -fsSL https://raw.githubusercontent.com/fxstein/todo.ai/main/install.sh | sh

Manual Installation: Zsh version (recommended for macOS):

curl -o todo.ai https://raw.githubusercontent.com/fxstein/todo.ai/main/todo.ai && chmod +x todo.ai

Bash version (recommended for Linux, requires bash 4+):

curl -o todo.ai https://raw.githubusercontent.com/fxstein/todo.ai/main/todo.bash && chmod +x todo.ai

Note: The bash version requires bash 4.0+ for associative arrays. macOS ships with bash 3.2, so use the zsh version on macOS or upgrade bash via homebrew.

Update

Python (v3.0+):

# Using uv (recommended)
uv tool upgrade ai-todo

# Alternative: pipx
pipx upgrade ai-todo

Legacy Shell:

./todo.ai update

Uninstall

Python (v3.0+):

# Using uv (recommended)
uv tool uninstall ai-todo

# Alternative: pipx
pipx uninstall ai-todo

Legacy Shell:

./todo.ai uninstall              # Remove script only
./todo.ai uninstall --all        # Remove script, data, and rules

---

Documentation

Getting Started: GETTING_STARTED.md - Quick start guide with setup instructions

Additional Guides:

• Numbering Modes - Complete guide to all numbering modes
• Usage Patterns - Real-world usage scenarios
• Coordination Setup - Setup guides for coordination services

Full Documentation Index: docs/README.md - Complete documentation navigation

---

License

Apache License 2.0 - See LICENSE file