todo

Todo TUI

A terminal-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

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:

# For the latest published version (may not work with current development)
go install github.com/nirabyte/todo@latest

# For development/testing, build from source:
git clone https://github.com/nirabyte/todo.git
cd todo
go build -o todo .

Then run:

./todo  # or just 'todo' if in PATH

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
• 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.

Important Warnings

• 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 a data directory in the current working directory.

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 a data directory:

• Default path: ./data/todos.md
• Format: Human-readable Markdown with checkboxes
• Location: Relative to where you run the application

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

Migration

The application now stores data in a local data directory by default. Existing users will have their data stored in ./data/todos.md relative to where the application is run.

Development

Project Structure

todo/
├── assets/          # Images/icons
├── cmd/todo/
│   └── main.go      # Main application entry point
├── internal/
│   ├── app/         # App setup
│   ├── config/      # Config handling
│   ├── models/      # Data models & business logic
│   │   ├── models.go    # Task data structures
│   │   ├── storage.go   # Data persistence (Markdown)
│   │   ├── update.go    # Input handling & state updates
│   │   ├── view.go      # UI rendering
│   │   └── sort.go      # Task sorting logic
│   └── styles/      # UI styling & themes
├── data/            # Application data directory (created at runtime)
├── go.mod           # Go module dependencies
├── go.sum           # Dependency checksums
├── Makefile         # Build automation
├── build.sh         # Build script
└── 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, 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
• Markdown support for task descriptions
• 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)
• 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

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