todo

Todo TUI

A terminal user interface (TUI) todo list manager with animations, themes, and comprehensive features.

Table of Contents

• Features
• Quick Start
  • Installation
  • Requirements
  • Data Storage
  • Data Format
  • Logging
• Usage
  • Basic Controls
  • Themes & Customization
• Development
  • Testing
  • Building
  • Technologies
• Roadmap
  • Completed
  • Future Plans
• Contributing
• License
• Contact

Features

• Task Management - Add, edit, and complete tasks with rich descriptions
• Recycle Bin - Safe deletion with undo functionality
• Multiple Views - Tasks, recycle bin, tutorial, and help system
• User Interface - 30+ animations, 10 color themes, expandable task details
• Cross-platform - Works on Windows, macOS, and Linux
• Data Storage - Markdown files with automatic persistence
• Logging - Automatic rotation and compression

Quick Start

Installation

Option 1: Go Install

go install github.com/nirabyte/todo@latest

Then run:

todo

[!TIP] On first launch, the application will show helpful hints to get you started.

Option 2: Pre-built Binaries

• Visit Releases
• Download the appropriate binary for your platform
• Extract and run

Option 3: Build from Source

1. Clone the repository:

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

2. Run it:

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

On Linux/macOS: chmod +x the binary if needed

Requirements

• Go 1.25.5+ (for building)
• Terminal with ANSI color support
• Nerd Font for icons

Data Storage

Todos are stored as Markdown files:

• Windows: %LOCALAPPDATA%\todo\todos.md
• macOS: ~/Library/Application Support/todo/todos.md
• Linux: ~/.local/share/todo/todos.md

Data Format

Tasks are stored in Markdown format:

# TODO List

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

- [ ] Buy groceries
  Need milk, bread, and eggs

- [x] Finish project report
  Complete the quarterly summary

- [ ] Call dentist

Format Details:

• [ ] - Incomplete tasks
• [x] - Completed tasks
• Indented text - Task descriptions
• HTML comments store theme/sort preferences

Logging

Comprehensive logging with automatic rotation:

• Location:
  • Windows: %APPDATA%\todo\logs\todo.log
  • macOS: ~/Library/Logs/todo/todo.log
  • Linux: ~/.local/share/todo/logs/todo.log
• Rotation: 10MB size limit, keeps 5 files
• Compression: Automatic gzip compression of old logs

Usage

Basic Controls

Task Management

• Create Tasks: Press n to add new tasks with optional detailed descriptions
• Edit Tasks: Press e to modify existing tasks inline, including adding descriptions to tasks that don't have them
• Complete Tasks: Press Space to toggle task completion
• Delete Tasks: Press d to move tasks to recycle bin
• Undo Actions: Press u to restore recently deleted tasks

Views & Navigation

• Main View: Default task list with completion status
• Recycle Bin: Press Shift+B to view and restore deleted tasks
• Tutorial: Press Shift+T for interactive guided tour
• Help: Press Shift+? for comprehensive key bindings

Themes & Customization

Color Themes

• 10 Color Themes: Catppuccin, Nord, Gruvbox, Dracula, Tokyo Night, Rose Pine, Everforest, One Dark, Solarized, Kanagawa

Sorting Options

• Sort Modes: Creation order, Todo first, Done first

Animations

• 30+ Completion Effects: Unique animations for task completion

Data Storage

Todos are saved as readable Markdown files with your theme and sorting preferences.

Development

Testing

go test ./...                    # Run all tests
go test -v ./...                 # Run tests with verbose output
go test -cover ./...             # Run tests with coverage
go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out -o coverage.html  # Generate coverage report

Building

# Using Make
make build         # Build for current platform
make build-all     # Cross-platform build
make release       # Prepare release binaries

# Using build scripts
./build.sh         # Comprehensive bash script with testing, formatting, and cross-platform builds
./build.ps1        # PowerShell build script (Windows)

Technologies

Built with Go, Bubble Tea, and Lip Gloss.

Roadmap

Completed

• Core task management with inline editing
• Markdown persistence with automatic saving
• 10 color themes and 30 completion animations
• Sorting modes and task descriptions
• Recycle bin with undo functionality
• Multiple views and cross-platform support
• Advanced logging and comprehensive testing
• Build system with cross-platform tools

Future Plans

• Kanban board view (columns: Todo, In Progress, Done)
• Priority levels (High/Medium/Low) with visual indicators
• Tags/categories for task organization
• Due dates with calendar integration
• Advanced search and filtering
• Bulk operations (select multiple tasks)
• Time tracking for tasks
• Import/export (JSON, CSV, Markdown)
• Performance optimizations

Contributing

See CONTRIBUTING.md for development guidelines.

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