RazTodo

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

Preview

A command-line task manager powered by SQLite, with optional AI-assisted task explanations via Ollama.

Why RazTodo

Most task managers pull you into a browser tab or a cloud account just to jot down a to-do. RazTodo stays entirely in your terminal, backed by a single local SQLite database, with no accounts, no telemetry, and no background services.

Highlights

• 💻 Native CLI built for daily terminal workflows
• 🗄️ Single local SQLite database, your data never leaves your machine
• 🤖 Optional local AI task explanations powered by Ollama
• 🔒 No cloud services, accounts, or telemetry
• ⚡ Fast startup with zero background services
• ⌨️ Shell completion for bash, zsh, and fish
• 🌐 Optional Web UI via the companion raztodo-web package

Architecture

RazTodo follows a layered architecture, keeping the core task-management logic independent of any interface:

src/raztodo/
├── application/     # use cases / orchestration
├── domain/          # core task model and business rules
├── infrastructure/  # SQLite, settings, logging, LLM (Ollama) integration
└── presentation/
    └── cli/         # the `rt` command-line interface

• Separation of concerns: core logic is independent of the CLI.
• Local-first storage: all data stays on your machine in SQLite.

Quick Start

Installation

# Recommended (pipx)
pipx install raztodo

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

# Standard install
pip install raztodo

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

# Web UI (optional, separate package)
pip install raztodo-web

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

Basic Usage

# 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

Shell Completion

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

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

Commands

rt --help
rt add --help

📖 See the Usage Guide for full command documentation.

AI / Ollama Integration

RazTodo can optionally use Ollama to explain a task locally, no data leaves your machine.

rt explain 1 --short   # concise summary
rt explain 1 --plan    # actionable step-by-step plan
rt explain 1 --deep    # detailed analysis and recommendations

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

Configuration

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

📖 See the Configuration Guide.

Docker

An optional Docker image runs RazTodo's CLI (rt) directly as the container entrypoint.

docker build \
  --build-arg USER_UID=$(id -u) \
  --build-arg USER_GID=$(id -g) \
  -t raztodo:local .

docker run --rm raztodo:local --help

docker run --rm \
  -v raztodo-data:/data \
  raztodo:local add "Buy milk"

docker run --rm \
  -v raztodo-data:/data \
  raztodo:local list

📖 See the Docker Guide.

Documentation

Core:

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

Advanced:

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

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.
• raztodo-web: Optional Web UI, installs on top of raztodo (pip install raztodo-web).

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