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

An optional Docker image covers the CLI and the Web UI with persistent SQLite storage.

docker build -t raztodo:local .

CLI:

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

Web UI (via Compose):

docker compose up -d web
# open http://localhost:8000

[!NOTE] The image stores the database in /data; mount a host folder or use the Compose named volume to persist data. CLI and Web UI share the same database when they use the same /data volume.

[!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

Contributions are welcome! Whether it's bug reports, feature requests, documentation improvements, or code changes, check the contribution guide before getting started.

See the Contributing Guide for development setup, testing, coding standards, and pull request guidelines.

License