RazTodo

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

rt --help
rt add --help

📖 See the Usage Guide for full command documentation.

Configuration

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