T_{_(UI)}ODO - A Modern Terminal Task Manager

TUIODO is a feature-rich, terminal-based task management application built with Go. It provides an intuitive, keyboard-driven interface with mouse support, making it easy to manage your tasks directly from the terminal.

A beautiful, lightning-fast terminal task manager with extensive customization.

Features

New UI Improvements

Dynamic Category Colors - Customize colors for each task category
Priority Visibility - Priority indicators automatically hidden for completed tasks
Intelligent Sorting - Completed tasks always appear at the bottom regardless of sort order
Visual Consistency - Categories for completed tasks appear with dimmed colors

Core Features

Gorgeous Modern UI with clean typography and visual hierarchy
Brilliant Colors with monochrome mode support (--no-color)
Mouse Support with hover effects and click interactions (where supported)
Keyboard-Driven workflow with intuitive, vim-inspired shortcuts
Instant Performance with optimized rendering and caching
Comprehensive CLI with extensive configuration options

Task Management

Priority Levels (Critical/High/Medium/Low) with color coding
Dynamic Category Organization with configurable colors
Smart Filtering by status, category, and priority
Task Expansion to view full details of any task
Circular Navigation with wrap-around cursor movement
Delete Confirmation with undo capability
Rich Metadata Support using @tag notation
Markdown Storage in simple, human-readable format (~/TODO.md by default)
Automatic Backups with configurable options

Metadata Tags Support

TUIODO supports several metadata tags for enhanced task tracking:

@priority - Set task importance (critical/high/medium/low)
@created - Automatically tracked creation timestamp
@due - Set deadlines with YYYY-MM-DD format
@tag - Add custom tags to group related tasks
@status - Track custom status values

Content & Storage

Automatic Backups with configurable options
Git Repository Detection - Automatically uses TODO.md at git repository root when available
Multi-device Sync via configurable storage paths (share tasks via Dropbox, etc.)
Import/Export to standard formats (coming soon)

Advanced Capabilities

Extensive Configuration via YAML configuration files
Theme Support with pre-built and custom themes
Custom Keybindings to match your workflow
Command Palette for quick access to all features (coming soon)
Plugin System for extending functionality (coming soon)

Screenshots

Main Task View	Task Editing
Help Screen	Category Filtering

Installation

Prerequisites

Go 1.24+ (or use the pre-built binaries)
A terminal with true color support recommended (iTerm2, Alacritty, Kitty, etc.)

Via Homebrew (macOS)

# Install from the official tap
brew tap spmfte/tuiodo
brew install tuiodo

Via AUR (Arch Linux)

NOTE: Work in progress.

# Using yay
yay -S tuiodo

# Using paru
paru -S tuiodo

# Manual installation from AUR
git clone https://aur.archlinux.org/tuiodo.git
cd tuiodo
makepkg -si

Via Go Install

go install github.com/spmfte/tuiodo@latest

From Source

# Clone the repository
git clone https://github.com/spmfte/tuiodo.git
cd tuiodo

# Build the project
go build

# Run it
./tuiodo

Quick Start

Basic Usage

Just run tuiodo to start the application. Use the keyboard shortcuts to navigate and manage your tasks. It is recommended to use the following alias:

echo "alias todo='tuiodo'" >> "$HOME/.$(which "$SHELL" | awk -F'/' '{print $NF}')rc"

What this command does:

which "$SHELL" retrieves the full path of the current shell (e.g., /bin/zsh or /bin/bash).
awk -F'/' '{print $NF}' extracts only the last part of the path, which is the shell name (e.g., zsh or bash).
"$HOME/.$(which "$SHELL" | awk -F'/' '{print $NF}')rc" constructs the appropriate shell configuration file path (~/.zshrc, ~/.bashrc, etc.).
echo "alias todo='tuiodo'" >> "$HOME/.$(which "$SHELL" | awk -F'/' '{print $NF}')rc" appends the alias to the correct shell config file.
After running this command, reload your shell configuration with source ~/.zshrc (or source ~/.bashrc) to apply the alias.
You can now run todo instead of tuiodo to start the application.

Creating Tasks

Press a to add a new task. You can organize tasks by category using the format:

"Category: Task description"

For example:

"Work: Finish quarterly report"
"Personal: Call mom about birthday plans"
"Health: Schedule dentist appointment"

Adding Priorities

Use the p key to cycle through priority levels for the selected task:

None → Low → Medium → High → Critical → None

Adding Metadata

Add metadata to tasks using @ notation:

@due:2023-12-31 - Sets a due date
@tag:important - Adds a custom tag
@status:in-progress - Sets a custom status

Command-line Options

# Basic usage
tuiodo

# Use a specific config file
tuiodo --config ~/.config/tuiodo/my-config.yaml

# Use a different storage file
tuiodo --storage ~/projects/work-tasks.md

# Start with specific view and sorting
tuiodo --view pending --sort priority

# Terminal-friendly mode
tuiodo --no-mouse --no-color

# Configure backup behavior
tuiodo --backup-dir ~/backups --max-backups 10

# Start with specific category and view
tuiodo --category Work --view pending

⌨️ Keyboard Controls

Action	Keys
Navigation
Move cursor down	`j` `↓`
Move cursor up	`k` `↑`
Next page	`n` `→` `l`
Previous page	`b` `←` `h`
Switch tabs	`tab` `t`
Task Management
Add task	`a`
Edit task	`e`
Delete task	`d` (press twice to confirm)
Undo delete	`u`
Toggle completion	`space` `enter`
Expand task details	`x`
Cycle priority	`p`
Filtering
Cycle categories	`c`
Sort by priority	`s`
Sort by date	`S`
Sort by category	`C`
Other
Show/hide help	`?` `F1`
Quit	`q` `Ctrl+c`

Configuration

TUIODO supports extensive configuration through a YAML file located at ~/.config/tuiodo/tuiodo.yaml.

Configuration Locations

Configuration files are automatically loaded from the following locations (in order):

Custom path specified with --config /path/to/config.yaml
~/.config/tuiodo/tuiodo.yaml (primary location)
User config directory as reported by OS
Current directory ./tuiodo.yaml

Creating a Default Config File

To generate a default configuration file:

tuiodo --create-default-config

Configuration Sections

The configuration file is divided into these main sections:

1. General Settings

general:
  default_category: "Uncategorized" # Default category for new tasks
  show_status_bar: true # Show status bar at bottom
  tasks_per_page: 10 # Number of tasks to show per page
  clear_status_after_seconds: 3 # Time before status messages disappear

2. UI Settings

ui:
  show_header: true # Show app header
  header_format: "TUIODO" # Header text
  show_categories: true # Show category labels
  show_priorities: true # Show priority indicators
  task_separator: "─" # Character used to separate tasks
  enable_tabs: true # Show tab bar
  enable_borders: true # Show container borders
  border_style: "rounded" # Border style (rounded, normal, double, thick, none)
  date_format: "2006-01-02" # Go date format for creation dates

3. Colors Settings

colors:
  theme: "default"
  primary: "#7C3AED"
  secondary: "#2563EB"
  tertiary: "#10B981"
  # ... other base colors ...
  
  # Custom category colors
  category_colors:
    ui: "#8B5CF6"          # Purple for UI tasks
    add-task: "#EC4899"    # Pink for add-task
    bug: "#EF4444"         # Red for bugs
    function: "#10B981"    # Green for function
    fix: "#F59E0B"         # Amber for fixes
    functionality: "#3B82F6" # Blue for functionality
    layout: "#6366F1"      # Indigo for layout
    docs: "#2563EB"        # Blue for docs
    storage: "#14B8A6"     # Teal for storage
    # You can add your own categories:
    my-category: "#9333EA" # Custom color for your category

4. Key Bindings

keybindings:
  quit: ["q", "ctrl+c"]
  add_task: ["a"]
  edit_task: ["e"]
  delete_task: ["d"]
  toggle_task: ["enter", "space"]
  cycle_priority: ["p"]
  cycle_category: ["c"]
  cycle_tab: ["tab", "t"]
  next_page: ["right", "l", "n"]
  prev_page: ["left", "h", "b"]
  move_cursor_up: ["up", "k"]
  move_cursor_down: ["down", "j"]
  help: ["?", "F1"]

5. Storage Settings

storage:
  file_path: "TODO.md" # Path to task storage file
  backup_directory: "~/.config/tuiodo/backups" # Backup directory
  auto_save: true # Save automatically on changes
  backup_on_save: true # Create backups when saving
  max_backups: 5 # Maximum number of backups to keep

📝 Storage Format

Tasks are stored in a simple Markdown format that's human-readable and version-control friendly:

## Work

- [ ] Prepare presentation @priority:high @due:2023-06-15
- [x] Send weekly report @priority:medium

## Personal

- [ ] Buy groceries @priority:low
- [ ] Call mom @due:2023-05-10

Format Details

Categories: Denoted by ## Category Name
Tasks: Uses GitHub-style checkbox syntax
- - [ ] for pending tasks
- - [x] for completed tasks
Metadata:
- Priorities: @priority:high, @priority:medium, @priority:low
- Due dates: @due:YYYY-MM-DD

Advanced Usage

Custom Task Storage Location

You can store your tasks anywhere:

# Store in a Dropbox folder for sync between devices
tuiodo --storage ~/Dropbox/tasks.md

# Project-specific task list
tuiodo --storage ~/projects/awesome-project/TODO.md

Theme Customization

Create a custom theme by defining your own colors in the config:

colors:
  # Use a light theme
  theme: "custom"
  primary: "#8B5CF6" # Purple
  secondary: "#3B82F6" # Blue
  text: "#1F2937" # Dark gray
  background: "#F9FAFB" # Light gray
  # ... other color settings

Task Dependencies (Coming Soon)

Link tasks together with dependencies:

- [ ] Design project architecture @priority:high
- [ ] Implement database layer @depends:1
- [ ] Write unit tests @depends:2

Upgrading

To upgrade to the latest version:

go install github.com/spmfte/tuiodo@latest

Contributing

Contributions are very welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

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

Acknowledgements

Bubble Tea - The amazing TUI framework
Lip Gloss - Style definitions for terminal applications
Charm - For their suite of beautiful terminal tools

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
.github/workflows		.github/workflows
config		config
handlers		handlers
model		model
screenshots		screenshots
storage		storage
ui		ui
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
RELEASE.md		RELEASE.md
TODO.md		TODO.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go
release.sh		release.sh
tuiodo.demo.gif		tuiodo.demo.gif

License

spmfte/tuiodo

Folders and files

Latest commit

History

Repository files navigation

T(UI)ODO - A Modern Terminal Task Manager

Features

New UI Improvements

Core Features

Task Management

Metadata Tags Support

Content & Storage

Advanced Capabilities

Screenshots

Installation

Prerequisites

Via Homebrew (macOS)

Via AUR (Arch Linux)

Via Go Install

From Source

Quick Start

Basic Usage

What this command does:

Creating Tasks

Adding Priorities

Adding Metadata

Command-line Options

⌨️ Keyboard Controls

Configuration

Configuration Locations

Creating a Default Config File

Configuration Sections

1. General Settings

2. UI Settings

3. Colors Settings

4. Key Bindings

5. Storage Settings

📝 Storage Format

Format Details

Advanced Usage

Custom Task Storage Location

Theme Customization

Task Dependencies (Coming Soon)

Upgrading

Contributing

License

Acknowledgements

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Languages

T_{_(UI)}ODO - A Modern Terminal Task Manager

Packages