todo

Todo TUI

A Terminal UI (TUI) based todo list manager with animations and themes.

Features

• 10 color themes (Catppuccin, Nord, Gruvbox, Dracula, and more)
• 30 unique completion animations
• Inline editing for quick task management
• Task descriptions with expandable details
• Sorting modes to organize tasks
• Automatic save functionality
• Local file storage with Markdown persistence

Quick Start

Install with Go

If you have Go installed:

go install github.com/nirabyte/todo@latest

Then run:

todo

To launch the TUI.

[!TIP] On first launch, you'll see helpful hints to get started.

If Go's bin directory isn't in your PATH:

Add this to your shell configuration file (~/.bashrc, ~/.zshrc, etc.):

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

Or run this command to add it automatically:

echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc  # or ~/.zshrc

Then reload your shell configuration:

source ~/.bashrc

Download Pre-built Binary

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

Build from Source

1. Clone the repository:

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

2. Build for your platform:

   go build -o build/todo .
   
   # Build all platforms (requires Make)
   make build-all
   
   # Or prepare release binaries with simple names
   make release
   

3. Run it:

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

Requirements

• A terminal that supports ANSI color codes (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
• Go 1.25.5 or later

[!WARNING]

• No Pasting Support: Do not paste text into the application - it causes glitches and unpredictable behavior
• Caps Lock Issue: If Caps Lock is enabled before running the app, typing may not work properly. Turn off Caps Lock before starting the application.

Storage

Your todos are stored locally in Markdown format in platform-specific user data directories:

• Windows: %LOCALAPPDATA%\todo\todos.md (or %APPDATA%\todo\todos.md)
• macOS: ~/Library/Application Support/todo/todos.md
• Linux: ~/.local/share/todo/todos.md (or $XDG_DATA_HOME/todo/todos.md)

You can override the default location by setting the DATA_PATH environment variable.

Logging

The application maintains detailed logs of all user actions and system events:

• Location: Platform-specific log directories
  • Windows: %LOCALAPPDATA%\todo\logs\todo.log
  • macOS: ~/Library/Logs/todo/todo.log
  • Linux: ~/.local/share/todo/logs/todo.log
• Content: Task creation, editing, deletion, theme changes, sorting, animations, and system events
• Format: Timestamped entries with file location information

Logs are automatically rotated and help with troubleshooting and understanding application behavior.

Navigation

Managing Tasks

Task Descriptions

When creating a new task with n, you'll be prompted to add an optional description after entering the title. Press Enter to skip the description.

When editing a task with e:

• Tasks without descriptions: Edit title only
• Tasks with descriptions: Edit title first, then description

Use v to expand/collapse task details to view descriptions.

Customization

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 todos are stored locally in Markdown format in platform-specific user data directories:

• Windows: %LOCALAPPDATA%\todo\todos.md (preferred) or %APPDATA%\todo\todos.md
• macOS: ~/Library/Application Support/todo/todos.md
• Linux: $XDG_DATA_HOME/todo/todos.md or ~/.local/share/todo/todos.md
• Format: Human-readable Markdown with checkboxes
• Override: Set DATA_PATH environment variable to use a custom location

Markdown Format Example

# TODO List

<!-- Theme: 0, Sort: 0 -->

- [ ] Buy groceries
      Milk, bread, eggs

- [x] Finish project report
      Due tomorrow

- [ ] Call dentist

• [ ] = Incomplete tasks
• [x] = Completed tasks
• Indented text = Task descriptions
• Comments store theme and sort settings

What's Saved

All data includes:

• All your tasks (title, completion status)
• Your selected theme
• Your sorting preference
• Application configuration

Roadmap

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

Built With

• Go
• Bubble Tea - TUI framework
• Lip Gloss - Styling library

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