# Todo Agent
A natural language interface for [todo.sh](https://github.com/todotxt/todo.txt-cli) task management powered by LLM function calling.
## What it does
Transform natural language into todo.sh commands with intelligent task management:
```bash
# Use interactively
todo-agent
# Instead of: todo.sh add "Buy groceries +shopping"
todo-agent "add buy groceries to shopping list"
# Instead of: todo.sh list +work
todo-agent "show my work tasks"
```
## Why Todo Agent?
**Speak naturally** instead of memorizing commands. Todo Agent understands "add dentist appointment next Monday" and automatically sets the right date, project, and context.
**Get intelligent insights** beyond basic task lists. It organizes tasks strategically, suggests priorities, and recommends optimal timing based on your patterns.
**Work smarter** with automatic duplicate detection, recurring task handling, and calendar-aware scheduling.
**Choose your privacy** - use cloud AI (OpenRouter) or run locally (Ollama).
## Quick Start
### 1. Install
#### Install todo.sh (required)
**macOS:** `brew install todo-txt`
**Linux:** `sudo apt-get install todo-txt-cli` (Ubuntu/Debian) or `sudo pacman -S todo-txt-cli` (Arch)
**Windows:** `choco install todo-txt-cli` (Chocolatey) or `scoop install todo-txt-cli` (Scoop)
#### Set up todo.sh
```bash
# Create and initialize your todo directory
mkdir ~/todo && cd ~/todo
todo.sh init
# Add to your shell profile (.bashrc, .zshrc, etc.)
export TODO_DIR="$HOME/todo"
```
#### Install todo-agent
```bash
git clone https://github.com/codeprimate/todo-agent.git
cd todo_agent
make install
```
### 2. Set up your LLM provider
**Option A: OpenRouter (recommended)**
```bash
export OPENROUTER_API_KEY="your-api-key-here"
```
**Option B: Ollama (local)**
```bash
# Install and start Ollama
ollama pull mistral-small3.1
# Configure environment
export LLM_PROVIDER=ollama
export OLLAMA_MODEL=mistral-small3.1
```
### 3. Use it
```bash
# Interactive mode
todo-agent
# Single command
todo-agent "add urgent meeting with team +work @office"
```
## Examples
### Task Management
```bash
todo-agent "add buy groceries to shopping list"
todo-agent "list my work tasks"
todo-agent "complete the shopping task"
todo-agent "delete task 5"
```
### Task Modification
```bash
todo-agent "change task 2 to buy organic milk"
todo-agent "add urgent to task 1"
todo-agent "set task 3 as high priority"
```
### Discovery
```bash
todo-agent "what projects do I have?"
todo-agent "show completed tasks"
todo-agent "list my contexts"
```
### Strategic Planning
```bash
todo-agent "what should I do next?"
todo-agent "organize my tasks by priority"
todo-agent "show me everything due this week"
todo-agent "what tasks are blocking other work?"
```
### Natural Language Intelligence
```bash
todo-agent "add dentist appointment next Monday"
todo-agent "set up recurring daily vitamin reminder"
todo-agent "move all completed tasks to archive"
todo-agent "show me tasks I can do from home"
```
## Configuration
### Configuration Variables
| Variable | Description | Default | Required |
|-----------------------|-------------------------------------------|------------------------|-------------------------------|
| `LLM_PROVIDER` | LLM provider: `openrouter` or `ollama` | `openrouter` | No (defaults to `openrouter`) |
| `TODO_DIR` | Path to your todo.txt repository | — | **Yes** |
| `OPENROUTER_API_KEY` | Your OpenRouter API key | — | Yes (if using OpenRouter) |
| `OLLAMA_MODEL` | Model name for Ollama | `mistral-small3.1` | No |
| `LOG_LEVEL` | Logging verbosity (`INFO`, `DEBUG`, etc.) | `INFO` | No |
**Note:**
- `TODO_DIR` is required for all configurations.
- `OPENROUTER_API_KEY` is only required if you use the OpenRouter provider.
- The `TODO_FILE`, `DONE_FILE`, and `REPORT_FILE` are automatically inferred from `TODO_DIR`.
The `TODO_FILE`, `DONE_FILE`, and `REPORT_FILE` are automatically inferred from `TODO_DIR`.
## Development
```bash
# Clone and install
git clone https://github.com/codeprimate/todo-agent.git
cd todo_agent
# Install options:
# - Built package (like production install)
make install
# - Development mode with dev dependencies (recommended for development)
make install-dev
# - Basic development mode
pip install -e .
# Available Makefile tasks:
make test # Run tests with coverage
make format # Format and lint code
make lint # Run linting only
make build # Build package distribution
make clean # Clean build artifacts
make install # Build and install package locally
make install-dev # Install in development mode with dev dependencies
```
## Code Quality and Linting
This project uses comprehensive linting to maintain code quality:
### Linting Tools
- **Ruff**: Fast Python linter and formatter (replaces Black, isort, and Flake8)
- **MyPy**: Static type checking
- **Bandit**: Security vulnerability scanning
**Note**: Ruff is configured to be compatible with Black's formatting style and provides 10-100x faster performance than traditional tools.
### Pre-commit Hooks
Install pre-commit hooks for automatic linting on commits:
```bash
pre-commit install
```
### Linting in Test Suite
Linting checks are integrated into the test suite via `tests/test_linting.py`. The `make test` command runs all tests including linting checks. You can also run linting tests separately:
```bash
# Run linting tests only
pytest -m lint
```
### Configuration Files
- `pyproject.toml`: Ruff, MyPy, and pytest configuration
- `.pre-commit-config.yaml`: Pre-commit hooks configuration
```
## Architecture
The todo-agent follows a clean, layered architecture with clear separation of concerns:
### **Interface Layer** (`todo_agent/interface/`)
- **CLI**: User interaction, input/output handling, and application loop
- **Tools**: Function schemas and execution logic for LLM function calling
- **Formatters**: Output formatting and presentation
### **Core Layer** (`todo_agent/core/`)
- **TodoManager**: Business logic orchestrator that translates high-level operations into todo.sh commands
- **ConversationManager**: Manages conversation state, memory, and context for multi-turn interactions
- **TaskParser**: Parses and validates task-related operations
- **Exceptions**: Custom exception classes for error handling
### **Infrastructure Layer** (`todo_agent/infrastructure/`)
- **Inference Engine**: Orchestrates LLM interactions, tool calling, and conversation flow
- **LLM Clients**: Provider-specific implementations (OpenRouter, Ollama) with factory pattern
- **TodoShell**: Subprocess wrapper for executing todo.sh commands
- **Configuration**: Environment and settings management
- **Logging**: Structured logging throughout the application
- **Token Counter**: Manages conversation token limits and costs
### **How It Works**
1. **User Input** → Natural language request (e.g., "add buy groceries to shopping list")
2. **CLI** → Captures input and passes to inference engine
3. **Inference Engine** → Sends request to LLM with available tools
4. **LLM** → Analyzes request and decides which tools to call
5. **Tool Execution** → TodoManager → TodoShell → todo.sh
6. **Response** → Results returned through conversation manager to user
### **Key Features**
- **Function Calling**: LLM intelligently selects and executes appropriate tools
- **Conversation Memory**: Maintains context across interactions
- **Multi-Provider Support**: Works with cloud (OpenRouter) and local (Ollama) LLMs
- **Error Handling**: Robust error management with detailed logging
- **Performance Monitoring**: Tracks thinking time and conversation metrics
## License
GNU General Public License v3.0
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "todo-agent",
"maintainer": "codeprimate",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "todo, task-management, llm, natural-language, cli",
"author": "codeprimate",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f4/83/17c96c5ed3e1420035bafcc64f6021c011baf6c77990bd66918d56b54031/todo_agent-0.2.9.tar.gz",
"platform": null,
"description": "# Todo Agent\n\nA natural language interface for [todo.sh](https://github.com/todotxt/todo.txt-cli) task management powered by LLM function calling.\n\n## What it does\n\nTransform natural language into todo.sh commands with intelligent task management:\n\n```bash\n# Use interactively\ntodo-agent\n# Instead of: todo.sh add \"Buy groceries +shopping\"\ntodo-agent \"add buy groceries to shopping list\"\n# Instead of: todo.sh list +work\ntodo-agent \"show my work tasks\"\n```\n\n## Why Todo Agent?\n\n**Speak naturally** instead of memorizing commands. Todo Agent understands \"add dentist appointment next Monday\" and automatically sets the right date, project, and context.\n\n**Get intelligent insights** beyond basic task lists. It organizes tasks strategically, suggests priorities, and recommends optimal timing based on your patterns.\n\n**Work smarter** with automatic duplicate detection, recurring task handling, and calendar-aware scheduling.\n\n**Choose your privacy** - use cloud AI (OpenRouter) or run locally (Ollama).\n\n## Quick Start\n\n### 1. Install\n\n#### Install todo.sh (required)\n\n**macOS:** `brew install todo-txt` \n**Linux:** `sudo apt-get install todo-txt-cli` (Ubuntu/Debian) or `sudo pacman -S todo-txt-cli` (Arch) \n**Windows:** `choco install todo-txt-cli` (Chocolatey) or `scoop install todo-txt-cli` (Scoop)\n\n#### Set up todo.sh\n\n```bash\n# Create and initialize your todo directory\nmkdir ~/todo && cd ~/todo\ntodo.sh init\n\n# Add to your shell profile (.bashrc, .zshrc, etc.)\nexport TODO_DIR=\"$HOME/todo\"\n```\n\n#### Install todo-agent\n\n```bash\ngit clone https://github.com/codeprimate/todo-agent.git\ncd todo_agent\nmake install\n```\n\n### 2. Set up your LLM provider\n\n**Option A: OpenRouter (recommended)**\n```bash\nexport OPENROUTER_API_KEY=\"your-api-key-here\"\n```\n\n**Option B: Ollama (local)**\n```bash\n# Install and start Ollama\nollama pull mistral-small3.1\n\n# Configure environment\nexport LLM_PROVIDER=ollama\nexport OLLAMA_MODEL=mistral-small3.1\n```\n\n### 3. Use it\n\n```bash\n# Interactive mode\ntodo-agent\n\n# Single command\ntodo-agent \"add urgent meeting with team +work @office\"\n```\n\n## Examples\n\n### Task Management\n```bash\ntodo-agent \"add buy groceries to shopping list\"\ntodo-agent \"list my work tasks\"\ntodo-agent \"complete the shopping task\"\ntodo-agent \"delete task 5\"\n```\n\n### Task Modification\n```bash\ntodo-agent \"change task 2 to buy organic milk\"\ntodo-agent \"add urgent to task 1\"\ntodo-agent \"set task 3 as high priority\"\n```\n\n### Discovery\n```bash\ntodo-agent \"what projects do I have?\"\ntodo-agent \"show completed tasks\"\ntodo-agent \"list my contexts\"\n```\n\n### Strategic Planning\n```bash\ntodo-agent \"what should I do next?\"\ntodo-agent \"organize my tasks by priority\"\ntodo-agent \"show me everything due this week\"\ntodo-agent \"what tasks are blocking other work?\"\n```\n\n### Natural Language Intelligence\n```bash\ntodo-agent \"add dentist appointment next Monday\"\ntodo-agent \"set up recurring daily vitamin reminder\"\ntodo-agent \"move all completed tasks to archive\"\ntodo-agent \"show me tasks I can do from home\"\n```\n\n## Configuration\n\n\n### Configuration Variables\n\n| Variable | Description | Default | Required |\n|-----------------------|-------------------------------------------|------------------------|-------------------------------|\n| `LLM_PROVIDER` | LLM provider: `openrouter` or `ollama` | `openrouter` | No (defaults to `openrouter`) |\n| `TODO_DIR` | Path to your todo.txt repository | \u2014 | **Yes** |\n| `OPENROUTER_API_KEY` | Your OpenRouter API key | \u2014 | Yes (if using OpenRouter) |\n| `OLLAMA_MODEL` | Model name for Ollama | `mistral-small3.1` | No |\n| `LOG_LEVEL` | Logging verbosity (`INFO`, `DEBUG`, etc.) | `INFO` | No |\n\n**Note:** \n- `TODO_DIR` is required for all configurations. \n- `OPENROUTER_API_KEY` is only required if you use the OpenRouter provider. \n- The `TODO_FILE`, `DONE_FILE`, and `REPORT_FILE` are automatically inferred from `TODO_DIR`.\n\nThe `TODO_FILE`, `DONE_FILE`, and `REPORT_FILE` are automatically inferred from `TODO_DIR`.\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/codeprimate/todo-agent.git\ncd todo_agent\n\n# Install options:\n# - Built package (like production install)\nmake install\n# - Development mode with dev dependencies (recommended for development)\nmake install-dev\n# - Basic development mode\npip install -e .\n\n# Available Makefile tasks:\nmake test # Run tests with coverage\nmake format # Format and lint code\nmake lint # Run linting only\nmake build # Build package distribution\nmake clean # Clean build artifacts\nmake install # Build and install package locally\nmake install-dev # Install in development mode with dev dependencies\n```\n\n## Code Quality and Linting\n\nThis project uses comprehensive linting to maintain code quality:\n\n### Linting Tools\n- **Ruff**: Fast Python linter and formatter (replaces Black, isort, and Flake8)\n- **MyPy**: Static type checking\n- **Bandit**: Security vulnerability scanning\n\n**Note**: Ruff is configured to be compatible with Black's formatting style and provides 10-100x faster performance than traditional tools.\n\n### Pre-commit Hooks\nInstall pre-commit hooks for automatic linting on commits:\n```bash\npre-commit install\n```\n\n### Linting in Test Suite\nLinting checks are integrated into the test suite via `tests/test_linting.py`. The `make test` command runs all tests including linting checks. You can also run linting tests separately:\n```bash\n# Run linting tests only\npytest -m lint\n```\n\n### Configuration Files\n- `pyproject.toml`: Ruff, MyPy, and pytest configuration\n- `.pre-commit-config.yaml`: Pre-commit hooks configuration\n```\n\n## Architecture\n\nThe todo-agent follows a clean, layered architecture with clear separation of concerns:\n\n### **Interface Layer** (`todo_agent/interface/`)\n- **CLI**: User interaction, input/output handling, and application loop\n- **Tools**: Function schemas and execution logic for LLM function calling\n- **Formatters**: Output formatting and presentation\n\n### **Core Layer** (`todo_agent/core/`)\n- **TodoManager**: Business logic orchestrator that translates high-level operations into todo.sh commands\n- **ConversationManager**: Manages conversation state, memory, and context for multi-turn interactions\n- **TaskParser**: Parses and validates task-related operations\n- **Exceptions**: Custom exception classes for error handling\n\n### **Infrastructure Layer** (`todo_agent/infrastructure/`)\n- **Inference Engine**: Orchestrates LLM interactions, tool calling, and conversation flow\n- **LLM Clients**: Provider-specific implementations (OpenRouter, Ollama) with factory pattern\n- **TodoShell**: Subprocess wrapper for executing todo.sh commands\n- **Configuration**: Environment and settings management\n- **Logging**: Structured logging throughout the application\n- **Token Counter**: Manages conversation token limits and costs\n\n### **How It Works**\n\n1. **User Input** \u2192 Natural language request (e.g., \"add buy groceries to shopping list\")\n2. **CLI** \u2192 Captures input and passes to inference engine\n3. **Inference Engine** \u2192 Sends request to LLM with available tools\n4. **LLM** \u2192 Analyzes request and decides which tools to call\n5. **Tool Execution** \u2192 TodoManager \u2192 TodoShell \u2192 todo.sh\n6. **Response** \u2192 Results returned through conversation manager to user\n\n### **Key Features**\n- **Function Calling**: LLM intelligently selects and executes appropriate tools\n- **Conversation Memory**: Maintains context across interactions\n- **Multi-Provider Support**: Works with cloud (OpenRouter) and local (Ollama) LLMs\n- **Error Handling**: Robust error management with detailed logging\n- **Performance Monitoring**: Tracks thinking time and conversation metrics\n\n## License\n\nGNU General Public License v3.0\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A natural language interface for todo.sh task management",
"version": "0.2.9",
"project_urls": {
"Bug Tracker": "https://github.com/codeprimate/todo-agent/issues",
"Documentation": "https://github.com/codeprimate/todo-agent#readme",
"Homepage": "https://github.com/codeprimate/todo-agent",
"Repository": "https://github.com/codeprimate/todo-agent"
},
"split_keywords": [
"todo",
" task-management",
" llm",
" natural-language",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a159f94b51f11fb059f237dafd2c572e3eac7df93c517d5e078a45a525c030b0",
"md5": "1864b693ab75b4f3334dc671410ec3dc",
"sha256": "6eca20287356bcfab184690a10c6a351b342ffbd4e70e25b66c862e8d6442d81"
},
"downloads": -1,
"filename": "todo_agent-0.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1864b693ab75b4f3334dc671410ec3dc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 67088,
"upload_time": "2025-08-31T18:24:13",
"upload_time_iso_8601": "2025-08-31T18:24:13.676365Z",
"url": "https://files.pythonhosted.org/packages/a1/59/f94b51f11fb059f237dafd2c572e3eac7df93c517d5e078a45a525c030b0/todo_agent-0.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f48317c96c5ed3e1420035bafcc64f6021c011baf6c77990bd66918d56b54031",
"md5": "3a21f005dbb7f0d335e14fca1835c97b",
"sha256": "9816dcd8869c884c98b6eef81aa0874147cd82a7c9bba6668f4dfeaf43524b49"
},
"downloads": -1,
"filename": "todo_agent-0.2.9.tar.gz",
"has_sig": false,
"md5_digest": "3a21f005dbb7f0d335e14fca1835c97b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 94833,
"upload_time": "2025-08-31T18:24:15",
"upload_time_iso_8601": "2025-08-31T18:24:15.198774Z",
"url": "https://files.pythonhosted.org/packages/f4/83/17c96c5ed3e1420035bafcc64f6021c011baf6c77990bd66918d56b54031/todo_agent-0.2.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 18:24:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "codeprimate",
"github_project": "todo-agent",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.32.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.15.0"
]
]
},
{
"name": "types-requests",
"specs": [
[
">=",
"2.32.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"14.0.0"
]
]
},
{
"name": "tiktoken",
"specs": [
[
">=",
"0.11.0"
]
]
}
],
"lcname": "todo-agent"
}
JSON
