A local-first task manager for developers with a native CLI, optional Web UI, and local AI assistance powered by Ollama.

---

Preview

CLI

Local AI assistance powered by Ollama

Web UI

CLI + optional Web UI powered by FastAPI

---

Why RazTodo

Most task managers are either web-first, cloud-dependent, or tied to a single interface. RazTodo keeps everything local while letting you manage the same tasks from a native CLI or an optional Web UI.

Highlights

• 💻 Native CLI built for daily terminal workflows
• 🌐 Optional Web UI backed by the same local database
• 🤖 Local AI assistance powered by Ollama
• 🗄️ Single SQLite database shared across all interfaces
• 🔒 No cloud services, accounts, or telemetry
• ⚡ Fast startup with zero background services

Architecture

CLI ─┐
     ├── Core Engine ─── SQLite
Web ─┘

Both the CLI and Web UI use the same core engine and SQLite database, so every interface stays synchronized automatically.

The architecture follows three design principles:

• Separation of concerns core logic is independent of the user interface.
• Local-first storage all data stays on your machine.
• Composable interfaces use only the interfaces you need.

---

Quick Start

CLI

# Add a task
rt add "Prepare weekly groceries" --priority H --due 2026-12-31

# List all tasks
rt list

# Mark as done
rt done 1

# Search
rt search "groceries"

# Update
rt update 1 --title "Weekly groceries: milk, vegetables, essentials"

# Delete
rt remove 1

Web UI

Start the server:

rt-web

Then open http://127.0.0.1:8000.

Note

Runs locally only (not exposed to the internet) Single-user design with no authentication layer CLI and Web UI share one SQLite database (real-time sync) Local-first architecture optimized for personal use Built with FastAPI + lightweight static frontend AI-powered task explanations (Summary / Deep Analysis / Action Plan) via Ollama

Shell Completion

# Requires raztodo[completion]
eval "$(rt completion bash)"

Supports bash, zsh, and fish. For permanent setup see the Completion Guide.

---

LLM Integration

RazTodo integrates with Ollama to provide optional local AI assistance for your tasks. Every explanation runs locally using your own LLM, keeping your data private.

Available explanation modes:

• --short — concise summary of the task
• --plan — actionable step-by-step plan
• --deep — detailed analysis and recommendations

Example:

rt explain 1 --short
rt explain 1 --plan
rt explain 1 --deep

Note

Requires Ollama with a compatible local model. All AI processing is performed locally.

📖 See the Explain Guide for installation, configuration, supported models, and usage examples.

---

Installation

# Recommended (pipx)
pipx install raztodo

# No-install (uv)
uvx --from raztodo rt

# Standard install
pip install raztodo

# Web UI (optional)
pip install "raztodo[web]"

# Shell completion (optional)
pip install "raztodo[completion]"

# Everything (web + completion)
pip install "raztodo[all]"

For virtual environment and source installation, see the Installation Guide.

---

Commands

Command	Description	Example
add	Create a new task	rt add "Task" --priority H
list	List tasks with filters	rt list --pending --priority H
update	Update a task	rt update 1 --title "New title"
done	Toggle task done/undone	rt done 1
remove	Delete a task	rt remove 1
search	Search tasks by keyword	rt search "keyword"
export	Export tasks to JSON	rt export backup.json
import	Import tasks from JSON	rt import backup.json
migrate	Run database migrations	rt migrate
clear	Delete all tasks	rt clear --confirm
completion	Output shell completion script	rt completion bash
explain	Get an AI explanation of a task	rt explain 1 --plan

rt --help
rt add --help

📖 See the Usage Guide for full command documentation.

---

Configuration

Variable	Description	Default
RAZTODO_DB	Database filename or path	tasks.db
LOG_LEVEL	Logging level	ERROR

export RAZTODO_DB="/path/to/custom.db"
export LOG_LEVEL="DEBUG"

Tip

📖 See the Configuration Guide

---

Docker

docker build -t raztodo:local .
docker run --rm -it -v "$HOME/raztodo-data:/data" raztodo:local add "My first task"

Note

kept CLI-only to minimize image size and dependencies

Tip

📖 See the Docker Guide

---

Documentation

Core:

• 📦 Installation Guide
• 📖 Usage Guide
• ⚙️ Configuration Guide
• 🤖 Explain Guide

Advanced:

• ⌨️ Completion Guide
• 🐳 Docker Guide
• 🏗️ Architecture
• 🧪 Testing
• 📝 Changelog

---

Ecosystem

RazTodo is part of the RazBuild ecosystem of open-source developer tools.

• RazTint Zero-dependency ANSI colors, icons, and terminal formatting utilities powering RazTodo's CLI output.

---

Contributing

We welcome bug reports, feature requests, and pull requests.

git clone https://github.com/razbuild/raztodo
cd raztodo
uv sync

Quality checks

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

Workflow

1. Create feature branch
2. Implement changes
3. Ensure tests pass
4. Submit PR

See the CONTRIBUTING guide for details.

---

License