Metadata-Version: 2.4
Name: ai-todo
Version: 4.0.0b3
Summary: AI-Agent First TODO List Tracker with MCP and CLI interfaces
Author-email: Oliver Ratzesberger <fxstein@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/fxstein/ai-todo
Project-URL: Documentation, https://github.com/fxstein/ai-todo/tree/main/docs
Project-URL: Repository, https://github.com/fxstein/ai-todo.git
Project-URL: Issues, https://github.com/fxstein/ai-todo/issues
Keywords: todo,ai,mcp,cli,productivity,agent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=0.1.0
Requires-Dist: click>=8.1.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: requests>=2.32.0
Requires-Dist: pygithub>=2.5.0
Requires-Dist: fastmcp<3.0.0,>=2.14.4
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: pre-commit>=3.7.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: ascii-guard>=1.5.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Requires-Dist: types-pyyaml>=6.0.12.12; extra == "dev"
Dynamic: license-file

# ai-todo

**AI-native task management for coding agents**

Simple, persistent, version-controlled TODO tracking that works naturally with AI agents like Cursor, Claude, and Copilot.

---

## Quick Start

Add this to your project's `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ai-todo": {
      "command": "uvx",
      "args": ["ai-todo", "serve", "--root", "${workspaceFolder}"]
    }
  }
}
```

Then enable the server in Cursor Settings → MCP Servers → toggle **ai-todo** on.

That's it! Your AI agent can now manage tasks directly. No installation required.

**Try it:** Ask your agent to *"create a task for implementing user authentication"*

---

## Why ai-todo?

AI agents track tasks internally, but this creates a closed system that gets lost after sessions end. ai-todo provides a **permanent, version-controlled record** in your Git repository.

- **Persistent** — Tasks survive across sessions, restarts, and time
- **Version Controlled** — Tracked in Git alongside your code
- **AI-Native** — MCP integration for direct agent interaction
- **Human Readable** — Plain Markdown in standard TODO.md format
- **Zero Config** — Works immediately, no setup required
- **Instant & Local** — No API calls, authentication, or rate limits

---

## Installation Options

### Option A: Zero-Install MCP (Recommended)

For AI agent integration via Cursor or similar IDEs. Uses `uvx` to run on-demand without permanent installation.

**Project-specific setup** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "ai-todo": {
      "command": "uvx",
      "args": ["ai-todo", "serve", "--root", "${workspaceFolder}"]
    }
  }
}
```

Requires [uv](https://docs.astral.sh/uv/) to be installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`).

### Option B: System Installation

For CLI usage or permanent MCP server setup. Requires Python 3.10+.

```bash
# Install globally (recommended)
uv tool install ai-todo

# Or with pipx
pipx install ai-todo
```

**CLI Usage:** `ai-todo [command]` (e.g., `ai-todo add "My task"`, `ai-todo list`)

**MCP Server:** `ai-todo serve` (for Cursor integration)

---

## For Humans

With ai-todo, you simply tell your AI agent what you want in plain English:

- *"Create a task for implementing user authentication"*
- *"Break down the auth feature into subtasks"*
- *"Mark task 1 as complete"*
- *"Show me all tasks tagged with #bug"*
- *"Archive completed tasks"*
- *"Prune archived tasks older than 30 days"* — Keep TODO.md clean
- *"Fix the issue from #123"* — Reference GitHub Issues in tasks

Your agent handles the technical details. All tasks are stored in `TODO.md` in your repository.

---

## See It In Action

This repository uses ai-todo for its own development! Check [`TODO.md`](./TODO.md) to see:

- Task hierarchies with subtasks
- Tag-based organization (`#feature`, `#bug`, `#documentation`)
- Completion tracking and archiving
- Real development workflow in action

---

## Documentation

- **[MCP Setup Guide](docs/user/MCP_SETUP.md)** — Detailed Cursor integration
- **[Migration Guide](docs/user/PYTHON_MIGRATION_GUIDE.md)** — Upgrading from v2.x shell script
- **[Getting Started](docs/guides/GETTING_STARTED.md)** — Complete setup walkthrough
- **[FAQ](docs/FAQ.md)** — Common questions answered
- **[Full Documentation](docs/README.md)** — All guides and references

---

## License

Apache License 2.0 — See [LICENSE](LICENSE)
