todo

README

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

Table of Contents

• Features
• Quick Start
  • Install with Go
  • Download Pre-built Binary
  • Build from Source
• Requirements
• Storage
  • Data Storage
  • Logging
• Usage
  • Navigation
  • Managing Tasks
  • Recycle Bin
  • Task Descriptions
  • Customization
• Themes
• Sorting Modes
• Completion Animations
• Animations
• What's Saved
• Roadmap
• Built With
• Contributing
• License
• Contact

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)

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.

Usage

Navigation

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

Managing Tasks

Key	Action
n	Create new task
e	Edit selected task (title or with description if it has one)
v	Expand/collapse task details and descriptions
d	Delete selected task (moves to recycle bin)
Space	Toggle task completion status
u	Undo last deletion
Enter	Confirm (when editing)
Esc	Cancel (when editing)

Recycle Bin

Deleted tasks are moved to a recycle bin for easy restoration:

Key	Action
Shift+B	Enter/exit recycle bin view
u	Restore selected task from bin
Shift+U	Restore all tasks from bin
d	Permanently delete selected task from bin
Shift+D	Permanently delete all tasks from bin
v	Expand/collapse description in bin

The recycle bin preserves task states (completed/incomplete) and shows animated feedback for restore/delete operations.

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

Key	Action
t	Cycle through color themes
s	Cycle through sorting modes
Shift+B	Access recycle bin

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.

Animations

The app features 30+ unique animated effects:

• Completion animations: Sparkle, Matrix, Rainbow, Wave, Binary, Dissolve, and more
• Deletion animations: Animated binary sequences when deleting tasks
• Restore animations: Smooth transitions when restoring from recycle bin
• Random selection: Each completion gets a different animation style
• Description support: Animations work on both titles and expanded descriptions

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

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