lazytodo

A fast, beautiful, vim-centric TUI for managing todo.txt files. Built with TypeScript, OpenTUI, and Bun.

Features

• Vim-style Keybindings - Navigate with j/k, g/G, and use : commands like :w, :q, :wq
• Full todo.txt Support - Compliant with the todo.txt format specification
• Multi-Panel Interface - Priority chart, projects, contexts, and command history panels
• 8 Built-in Themes - Catppuccin, Dracula, Nord, Gruvbox, Tokyo Night, Solarized, One Dark, Monokai
• Braille Bar Charts - High-resolution priority visualization with 20 levels of granularity
• Fast & Lightweight - Single binary with no runtime dependencies
• Undo Support - Revert changes with u
• Yank/Paste - Copy tasks with y, paste with p

Installation

From Source

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Clone and build
git clone <repository-url>
cd lazytodo
bun install
bun run build

# Move to PATH
sudo mv lazytodo /usr/local/bin/

Development

bun run dev        # Run without building
bun test           # Run tests

Usage

TUI Mode (Recommended)

lazytodo tui                    # Launch TUI with default ~/todo.txt
lazytodo -f todo.txt tui        # Use specific file

Keyboard Shortcuts

Navigation

Key	Action
j / ↓	Move down
k / ↑	Move up
g	Go to top
G	Go to bottom
TAB	Cycle panels (Tasks → Priorities → Projects → Contexts)
ESC	Return to tasks / Clear filter

Task Actions

Key	Action
Space	Toggle task completion
Enter / e / i	Edit task
n / a	Add new task
d	Add due date
x	Delete task
y	Yank (copy) task
p	Paste task
0-9	Set priority (number mode)
Shift+A-Z	Set priority (letter mode)

View

Key	Action
v	Toggle show completed tasks
/	Search tasks
s	Cycle sort mode
o	Toggle highlight overdue
u	Undo last action
?	Show help
,	Open settings

Vim Commands

Command	Action
:q / :quit	Quit
:w / :write	Save
:wq / :x	Save and quit
:help	Show help
:set	Open settings
:theme <name>	Switch theme
:sort <mode>	Change sort mode

CLI Mode

lazytodo list                    # List active tasks
lazytodo add "Call Mom +Family"  # Add task
lazytodo do 1                    # Complete task 1
lazytodo pri 1 A                 # Set priority A
lazytodo edit 1 "New text"       # Edit task
lazytodo delete 1                # Delete task

Filtering

lazytodo list -c phone           # Filter by @context
lazytodo list -p Work            # Filter by +project
lazytodo list --priority A       # Filter by priority
lazytodo list -s "search term"   # Search text
lazytodo list --all              # Include completed

Panels

Priority Chart

Visual bar chart showing task distribution by priority. Uses braille characters for high-resolution display with 20 levels of granularity.

Projects Panel

Lists all +project tags. Press Enter to filter tasks by project.

Contexts Panel

Lists all @context tags. Press Enter to filter tasks by context.

Command History

Read-only log of recent commands (not included in TAB navigation).

Stats (Header)

Shows DUE/OVERDUE count, DONE TODAY, and ACTIVE tasks.

Configuration

Config file: ~/.config/todo-tui/config.toml

# Priority mode: 'letter' (A-Z) or 'number' (0-9)
priorityMode = "number"

# Color theme
theme = "catppuccin"

Available Themes

• catppuccin (default)
• dracula
• nord
• gruvbox
• tokyonight
• solarized
• onedark
• monokai

Priority Format Detection

When opening a file, lazytodo detects the priority format used (letter A-Z or number 0-9). If it differs from your settings, you'll be prompted to:

1. Convert the file - Transform all priorities to match your settings
2. Switch settings - Adapt your settings to match the file format
3. Ignore - Keep both formats as-is

This ensures consistency and prevents confusion when working with files created with different priority modes.

Todo File Location

Priority order:

1. -f flag: lazytodo -f ~/my-todos.txt tui
2. TODO_FILE environment variable
3. ./todo.txt (current directory)
4. ~/todo.txt (home directory)

Todo.txt Format

(A) 2025-12-10 Call Mom +Family @phone due:2025-12-15
x 2025-12-11 (A) 2025-12-10 Completed task +Project @context

• (A) - Priority (A-Z or 0-9)
• 2025-12-10 - Creation date
• +Family - Project tag
• @phone - Context tag
• due:2025-12-15 - Due date metadata
• x - Completion marker
• Second date after x - Completion date

Tech Stack

• Runtime: Bun
• Language: TypeScript
• TUI Framework: @opentui/react
• State Management: Zustand
• CLI: Commander.js

License

MIT