ohmyzsh/plugins/taskman/README.md

Taskman v2.0 - Oh My Zsh Plugin

A modern, feature-rich terminal task manager plugin for Oh My Zsh. Taskman provides an intuitive sidebar-style interface for managing your tasks with advanced features like priority-based coloring, humanized timers, and even a fun running cat animation!

✨ Features

Core Functionality

• Sidebar Interface: Clean, terminal-based UI that doesn't interfere with your workflow
• Persistent Storage: Tasks are automatically saved to JSON format
• Priority System: Three priority levels (high, normal, low) with visual indicators
• Task Operations: Add, complete, delete, and navigate tasks with keyboard shortcuts

Advanced Features

• Smart Sorting: Multiple sort modes (creation order, priority, alphabetical) with completed tasks always at bottom
• Priority-Based Colors: Task text colored by priority (red=high, yellow=normal, cyan=low)
• Humanized Timers: Shows task age in human-readable format ([5m], [2h], [3d]) using local timezone
• Visual Separation: Horizontal line separates active and completed tasks
• Configurable Storage: Set custom task file location via TASKMAN_DATA_FILE environment variable
• Completed Task Dimming: Completed tasks retain priority colors but are visually dimmed
• Fun Animation: Optional Chrome dino-style mini-game for entertainment (toggle with 'x')

Display Format

Taskman v2.0                                    [Sort: default]
Pending: 3, Completed: 1                Press 'h' for help, 'q' to quit

[  5m] ○ [!] Fix critical bug in authentication system
[ 2h] ○ [-] Review pull request #123
[now] ○ [·] Update documentation

─────────────────────────────────────────────────────────────────

[ 1d] ✓ [!] Complete project setup

        ◆
. . . ● . . . | . . . ▌ . . . █ . . . ┃ . . . ▐ . . .

n: New | Space: Toggle | d: Delete | s: Sort | ↑↓: Navigate | h: Help | q: Quit

🚀 Installation

Manual Installation

# Clone or copy the plugin to your Oh My Zsh plugins directory
cp -r taskman ~/.oh-my-zsh/plugins/

# Add to your .zshrc plugins list
plugins=(... taskman)

# Reload your shell
source ~/.zshrc

Using Oh My Zsh Plugin Manager

If you're using a plugin manager like oh-my-zsh-plugins:

# Add to your plugin list
plugins=(... taskman)

🎮 Usage

Interactive UI

Launch the interactive task manager:

taskman
# or use aliases
tasks
tm
todo

Keyboard Shortcuts

Navigation

• ↑/k - Move selection up
• ↓/j - Move selection down

Task Operations

• n - Create new task
• Space - Toggle task completion
• d - Delete selected task

Sorting

• s - Cycle through sort modes (default → priority → alphabetical)
• p - Sort by priority (high → normal → low)
• a - Sort alphabetically

Other

• h - Toggle help panel
• x - Toggle animation on/off
• q - Quit application

Command Line Interface

# Add a new task
tasks add "Complete project documentation"
tasks add "Fix bug in login system" high

# List tasks
tasks list
tasks list pending
tasks list completed

# Mark task as completed
tasks done 1

# Delete a task
tasks delete 2

# Sort tasks
tasks sort priority
tasks sort alphabetical
tasks sort default

# Show help
tasks help

⚙️ Configuration

Custom Storage Location

Set a custom location for your task file:

export TASKMAN_DATA_FILE="$HOME/my-tasks.json"

Priority Levels

• High Priority (!): Red text - urgent tasks
• Normal Priority (-): Yellow text - regular tasks
• Low Priority (·): Cyan text - nice-to-have tasks

🎨 Visual Features

Color System

• Active Tasks: Text colored by priority (red/yellow/cyan)
• Completed Tasks: Same priority colors but dimmed for subtle indication
• Status Bullets: Green checkmarks for completed, colored circles for active
• Selection: Reverse highlighting for currently selected task

Timer Display

• Shows how long ago each task was created
• Updates in real-time for active tasks
• Uses local timezone for accurate time calculation
• Formats: [now], [5m], [2h], [3d]

Mini-Game Animation

• Chrome dino-style side-scrolling game with jumping player and obstacles
• Press 'x' to toggle animation on/off
• Automatic jumping and varied obstacles for entertainment
• Runs alongside task management without interference

📁 File Structure

~/.taskman/
└── tasks.json          # Task storage (default location)

Task Data Format

{
  "tasks": [
    {
      "id": 1,
      "text": "Complete project setup",
      "completed": true,
      "priority": "high",
      "created_at": "2024-01-15T10:30:00"
    }
  ],
  "next_id": 2,
  "sort_mode": "default"
}

🔧 Technical Details

• Language: Python 3.6+
• Dependencies: Built-in libraries only (curses, json, datetime)
• Storage: JSON format for human-readable task data
• Cross-platform: Works on macOS, Linux, and other Unix-like systems
• Performance: Efficient curses-based rendering with 100ms refresh rate

🎯 Tips & Tricks

1. Quick Task Entry: Use Tab in input mode to cycle through priority levels
2. Efficient Navigation: Use k/j (vim-style) or arrow keys for navigation
3. Sort Persistence: Your preferred sort mode is remembered between sessions
4. Bulk Operations: Use CLI commands for scripting and automation
5. Custom Storage: Set TASKMAN_DATA_FILE to sync tasks across different setups
6. Visual Cues: Completed tasks are automatically moved to bottom with visual separator
7. Time Awareness: Timer shows local time, perfect for tracking task age across time zones

🐛 Troubleshooting

Common Issues

• Unicode Display: Ensure your terminal supports Unicode for proper emoji display
• Color Issues: Some terminals may not support all color combinations
• Permission Errors: Check write permissions for the task storage directory

Debug Mode

# Run with Python directly for debugging
python3 ~/.oh-my-zsh/plugins/taskman/task_manager.py

🤝 Contributing

This is an Oh My Zsh version of the Taskman plugin. For contributions and bug reports, please refer to the original osh framework repository.

📄 License

Part of the Oh My Zsh ecosystem. See individual license files for details.

---

Enjoy managing your tasks with style! 🐱✨