ohmyzsh/plugins/taskman/README.md

taskman

A powerful terminal task manager plugin for Oh-My-Zsh. Manage your daily tasks without leaving the command line!

Features

• 📝 Dual Interface: Both interactive TUI and CLI operations
• ⌨️ Vim-like Keybindings: Navigate with j/k, Space to toggle
• 🎯 Priority System: High, normal, and low priority with color coding
• 💾 Persistent Storage: Tasks saved in ~/.taskman/tasks.json
• 🎨 Rich Colors: Visual indicators for task status and priority
• ⚡ Zero Config: Works immediately after installation
• 🔧 Shell Integration: Aliases, completion, and sidebar workflow

Installation

1. Add taskman to your plugins list in ~/.zshrc:

   plugins=(git taskman)
   

2. Reload your shell:

   source ~/.zshrc
   

3. Start using!

   tasks add "My first task"
   

Requirements

• Python 3.6+ (for interactive UI and CLI operations)
• Terminal with color support (most modern terminals)

Usage

Interactive UI

Launch the full-screen task manager:

tasks           # Launch interactive UI
tasks ui        # Same as above
task-sidebar    # Launch with sidebar usage tips

Keyboard Shortcuts

Key	Action
↑/k	Move up
↓/j	Move down
n	Create new task
Space	Toggle task completion
d	Delete selected task
Tab	Cycle priority when creating tasks
h	Toggle help panel
q	Quit

Command Line Interface

Adding Tasks

tasks add "Fix login bug"                    # Normal priority
tasks add "Deploy to production" high        # High priority
tasks add "Update documentation" low         # Low priority

Listing Tasks

tasks list           # All tasks
tasks list pending   # Only pending tasks
tasks list completed # Only completed tasks
tasks ls            # Short alias

Managing Tasks

tasks done 3         # Mark task ID 3 as completed
tasks delete 5       # Delete task ID 5
tasks help          # Show help

Aliases

The plugin provides convenient aliases:

tm add "Buy groceries"    # Same as 'tasks add'
task list               # Same as 'tasks list'
todo done 1             # Same as 'tasks done 1'

Priority Levels

Tasks support three priority levels with color coding:

• High Priority (!) - 🔴 Red, for urgent tasks
• Normal Priority (-) - 🟡 Yellow, default priority
• Low Priority (·) - 🔵 Cyan, for less urgent tasks

Task Display

Tasks are displayed with visual indicators:

 ✓ [!] Completed high priority task     (green)
 ○ [-] Pending normal priority task     (yellow)
 ○ [·] Pending low priority task        (cyan)

Sidebar Workflow

Perfect for split-terminal development workflow:

1. Split your terminal horizontally or vertically
2. Run tasks ui in one pane for persistent task view
3. Work in the other pane while keeping tasks visible
4. Quick updates with keyboard shortcuts

Auto-completion

The plugin provides intelligent tab completion:

tasks <TAB>              # Shows: add, list, done, delete, etc.
tasks add "task" <TAB>   # Shows: high, normal, low
tasks done <TAB>        # Shows available task IDs

Configuration

Optional Startup Summary

To show task summary when opening terminal, uncomment this line in the plugin:

# In ~/.oh-my-zsh/plugins/taskman/taskman.plugin.zsh
_taskman_startup_summary  # Uncomment this line

This shows:

📋 Task Summary: 3 pending, 2 completed
   Type 'tasks' to manage your tasks

Data Storage

Tasks are stored in ~/.taskman/tasks.json:

{
  "tasks": [
    {
      "id": 1,
      "text": "Fix login bug",
      "completed": false,
      "priority": "high",
      "created_at": "2024-01-15T10:30:00"
    }
  ],
  "next_id": 2
}

Examples

Daily Developer Workflow

# Morning planning
tasks add "Review PR #123" high
tasks add "Fix login bug" high  
tasks add "Update docs" low

# Check current tasks
tasks list pending

# Work in interactive mode (split terminal)
tasks ui

# Quick CLI updates
tm done 1
tm add "Deploy hotfix" high

# End of day review
tasks list completed

Project Management

# Sprint planning
tasks add "Implement user auth" high
tasks add "Add unit tests" normal
tasks add "Update README" low

# Track progress
tasks list

# Mark completed
tasks done 1
tasks done 2

# Cleanup
tasks delete 3  # Remove completed/outdated tasks

Comparison with Alternatives

Feature	taskman	taskwarrior	todo.txt	Todoist
Interactive TUI	✅	❌	❌	❌
CLI Interface	✅	✅	✅	✅
Zero Setup	✅	❌	✅	❌
No External Deps	✅	❌	✅	❌
Rich Visual UI	✅	❌	❌	❌
Vim Keybindings	✅	❌	❌	❌
Local Data	✅	✅	✅	❌

Troubleshooting

Python Not Found

# Install Python 3 (macOS)
brew install python3

# Install Python 3 (Ubuntu/Debian)
sudo apt-get install python3

# Verify installation
python3 --version

Plugin Not Loading

1. Check that taskman is in your plugins list:

   echo $plugins
   

2. Reload your shell:

   source ~/.zshrc
   

3. Test plugin function:

   tasks help
   

File Permissions

# Make Python files executable
chmod +x ~/.oh-my-zsh/plugins/taskman/bin/*.py

Contributing

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

License

MIT License - see the Oh-My-Zsh license for details.

Author

Created by @oiahoon

---

Happy task managing! 🚀