todo

Todo TUI

A terminal-based todo list manager with animations, themes, and notifications.

Features

• 10 color themes (Catppuccin, Nord, Gruvbox, Dracula, and more)
• 30 unique completion animations
• Timer notifications with desktop alerts
• Inline editing for quick task management
• Sorting modes to organize tasks
• Automatic save functionality

Quick Start

Download Pre-built Binary (Recommended)

1. Go to Releases
2. Download the binary for your system.
3. Extract the folder and run:
   • Windows: Double-click todo.exe or run .\todo.exe in terminal
   • macOS/Linux: Run ./todo-app-name in terminal (you may need to chmod +x todo-app-name first)

Install with Go

If you have Go installed:

go install github.com/nirabyte/todo@latest

Then run:

todo

If Go’s bin directory isn’t in your PATH, add it by running:

export PATH=$PATH:$HOME/go/bin

Then reload your shell:

source ~/.bashrc   # or ~/.zshrc if you use Zsh

Build from Source

1. Clone the repository:

   git clone https://github.com/nirabyte/todo.git
   cd todo
   

2. Build for your platform:

   # Using Make (if available)
   make build
   
   # Or manually
   go build -o build/todo ./cmd/todo
   

3. Run it:

   # Windows
   .\build\todo.exe
   
   # macOS/Linux
   ./build/todo
   

Requirements

• A terminal that supports colors (most modern terminals work)
• A Nerd Font installed (for icons and symbols to display correctly)
  • Download from nerdfonts.com
  • Popular choices: FiraCode, JetBrains Mono, Hack, Meslo
• Desktop notifications enabled (optional, for timer alerts)
• Go 1.25.5 or later (only if building from source)

Usage

Starting the App

Run:

todo

On first launch, you'll see helpful hints to get started.

Navigation

Key	Action
↑ or k	Move up
↓ or j	Move down
q or Ctrl+C	Quit

Managing Tasks

Key	Action
n	New task
e	Edit selected task
d	Delete selected task
Space	Toggle complete/uncomplete
Enter	Confirm (when editing)
Esc	Cancel (when editing)

Setting Timers

Press @ on any task to set a reminder timer.

Examples:

• 10m = 10 minutes
• 1h30m = 1 hour 30 minutes
• 45s = 45 seconds
• 2h15m30s = 2 hours 15 minutes 30 seconds

When the timer expires, you'll get a desktop notification. The countdown displays next to the task.

Customization

Key	Action
t	Cycle through themes
s	Cycle through sorting modes

Themes

Choose from 10 color themes:

1. Catppuccin - Soothing pastel colors
2. Nord - Cool arctic blues
3. Gruvbox - Retro warm tones
4. Dracula - Dark purple theme
5. Tokyo Night - Clean dark theme
6. Rose Pine - Natural earthy colors
7. Everforest - Comfortable green tones
8. One Dark - Popular dark theme
9. Solarized - Easy on the eyes
10. Kanagawa - Inspired by Japanese art

Press t to cycle through themes. Your choice is saved automatically.

Sorting Modes

Organize your tasks with three sorting options:

• Off - Keep tasks in the order you created them
• Todo First - Incomplete tasks at the top
• Done First - Completed tasks at the top

Press s to cycle through modes. Your preference is saved.

Completion Animations

When you complete a task, one of 30 unique animations plays. These include:

• Sparkle effects
• Rainbow transitions
• Typewriter effects
• Matrix-style animations
• And 26 more unique effects

Each animation is randomly selected for a fresh experience.

Data Storage

Your tasks are saved automatically in a file called todos.json in the same directory where you run the app.

What's saved:

• All your tasks (title, completion status, due dates)
• Your selected theme
• Your sorting preference

You can backup this file, edit it manually, or move it to another computer.

Development

Project Structure

todo/
├── assets/          # Images/icons
├── cmd/todo/
│   └── main.go      # Entry point
├── internal/
│   ├── app/         # App setup
│   ├── config/      # Config handling
│   ├── models/      # Data & logic
│   └── ui/          # UI code
├── go.mod           # Go module dependencies
├── go.sum           # Dependency checksums
└── README.md

Building for All Platforms

# Build all platforms (requires Make)
make build-all

# Or prepare release binaries with simple names
make release

This creates binaries for:

• Windows (amd64, 386, arm64)
• macOS (amd64, arm64)
• Linux (amd64, 386, arm64, arm)

Roadmap

• Core app functionality: tasks, themes, animations, timers, inline edit, sorting
• JSON-based persistence (todos.json) with automatic save
• 10 color themes (Catppuccin, Nord, Gruvbox, Tokyo Night, etc.)
• 30 unique completion animations
• Timer reminders with desktop notifications
• Inline task editing
• Sorting modes: Off / Todo First / Done First
• Tasks with description, status indicator, and active filename in header
• Support for subtasks / nested tasks
• Search/filter tasks
• Markdown support for task descriptions
• Extend timers to days/weeks/months
• Add absolute due dates with visual indicators
• JSON/Markdown import/export feature
• Add CLI arguments for dates/days, todolist, file selection, import/export commands
• Syncing across devices (cloud)
• Emacs Org mode integration
• Performance improvements (faster load, reduced memory usage)
• More UI/UX refinements: animations, interactions, layout, accessibility

Built With

• Go
• Bubble Tea - TUI framework
• Lip Gloss - Styling library
• Beeep - Desktop notifications

Contributing

Please see the full contribution guidelines in CONTRIBUTING.md.

CONTRIBUTING.md

License

This project is licensed under the MIT License — see the LICENSE file for details.

LICENSE

Contact

If you have questions, suggestions, or just want to chat, feel free to reach out to me on Discord:

Message me on Discord