todo

Todo TUI

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

[!WARNING] This project is in active development and may contain bugs!

This application is not yet stable enough to be used as your primary todo list manager. It may lose data, crash unexpectedly, or have incomplete features. Please:

• Don't use this for critical tasks or important data
• Report any bugs you find via GitHub Issues
• Help improve the project by contributing code or reporting issues
• Backup your data regularly if you choose to use it

Your feedback and contributions are greatly appreciated as we work to make this a reliable tool!

Table of Contents

• Features
• Quick Start
  • Installation
  • Requirements
  • Data Storage
  • Data Format
  • Data Migration
  • Logging
• Usage
  • Basic Controls
  • Task Management
  • Views & Navigation
• Themes & Customization
  • Color Themes
  • Sorting Options
  • Animations
  • Data Storage
• Development
  • 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, and help system
• User Interface - Multiple animations, various 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

[!CAUTION] Remember: This is a development version with potential bugs. Test thoroughly and backup your data before using for important tasks.

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

Data Migration

For users upgrading from older versions:

1. Automatic Migration: The app automatically detects and loads existing data from the standard locations
2. Backwards Compatibility: All previous data formats are supported
3. Missing Data: If no data file is found, the app starts with helpful introductory tasks

Previous data locations that are still supported:

• Any existing todos.md file in the current data directory
• Data is preserved through updates - no manual migration needed

If you have data in a custom location:

• Copy your todos.md file to the appropriate data directory for your platform
• The app will automatically detect and load it on next startup

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
  • u / Shift+U: Restore selected/all tasks from recycle bin
  • d / Shift+D: Permanently delete selected/all tasks from recycle bin
• Help: Press Shift+? for comprehensive key bindings

Themes & Customization

Color Themes

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

• Multiple Completion Effects: Unique animations for task completion

Data Storage

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

Development

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 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
• Multiple color themes and completion animations
• Sorting modes and task descriptions
• Recycle bin with undo functionality
• Multiple views and cross-platform support
• Advanced logging
• 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

We welcome contributions from everyone! Since this project is still in development, your help is crucial to make it better.

Bug Reports & Feature Requests

Please report bugs and request features! This helps us identify and fix issues quickly.

• Use GitHub Issues: Create detailed bug reports with steps to reproduce
• Include your environment: OS, terminal, Go version
• Attach logs if available: Located in the data directory
• Describe expected vs actual behavior

Code Contributions

See CONTRIBUTING.md for detailed development guidelines.

Areas that need help:

• Testing on different platforms (Windows, macOS, Linux)
• Bug fixes and stability improvements
• UI/UX improvements
• Performance optimizations
• Documentation improvements
• Feature implementations from the roadmap

Getting Started

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes and test thoroughly
4. Submit a pull request with a clear description

Thank you for helping make Todo TUI better!

License

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

LICENSE

Contact

• Bug Reports & Issues: GitHub Issues
• Discussions: GitHub Discussions
• Questions & Chat: Discord