task-list

Category: Task Management

Usage

task-list [--dir <directory>] [--status <status>] [--format <format>]

Arguments

• --dir : Optional - Specific directory (focus, active, paused, completed, all). Default: all

• --status : Optional - Filter by status (pending, in_progress, completed, blocked)

• --format : Optional - Output format (table, list, json). Default: table

Execution Instructions for Claude Code

When this command is run, Claude Code should:

• Scan specified directories for task files (*.md)

• Parse each task file header to extract:

• Task ID and title

• Status and priority

• Progress percentage

• Estimated/actual hours

• Blocked status

• Dependencies

• Apply any filters (status, etc.)

• Calculate aggregate statistics

• Display in requested format

Directory Scanning Order

• focus/ - Show first (current work)

• active/ - Ready tasks

• paused/ - Context switched

• completed/ - Recently done

• archive/ - If requested

Output Formats

Table Format (default)

📋 Task List Overview

FOCUS (1 task)

ACTIVE (3 tasks)

PAUSED (1 task)

Summary: 5 tasks | 2 in progress | 1 blocked | Total: 40h estimated, 9h actual

List Format

📋 Task List

🎯 FOCUS └── TASK-001: User Authentication Progress: 50% | 8h estimated, 4h actual | High priority Status: In Progress | Next: 2.3 Implement JWT tokens

📂 ACTIVE (3) ├── TASK-002: API Documentation │ Progress: 0% | 4h estimated | Medium priority │ Status: Pending | Dependencies: TASK-001 │ ├── TASK-003: Search Implementation │ Progress: 20% | 12h estimated, 2h actual | High priority │ Status: In Progress │ └── TASK-004: Performance Optimization Progress: 0% | 6h estimated | Low priority Status: Blocked ⚠️ | Reason: Waiting for profiling tools

JSON Format

{ "summary": { "total_tasks": 5, "in_progress": 2, "blocked": 1, "total_estimated_hours": 40, "total_actual_hours": 9 }, "tasks": { "focus": [...], "active": [...], "paused": [...], "completed": [...] } }

Progress Indicators

• ████████░░

• Visual progress bar

• Percentage with color coding:

• 0-25%: 🔴 Red

• 26-75%: 🟡 Yellow

• 76-100%: 🟢 Green

Error Handling

• If no tasks found: Show helpful message about creating tasks

• If task file corrupted: Mark with ❌ and continue

• If no task directories: Suggest running task-system-init

Example

List all tasks

task-list

Show only focused task

task-list --dir focus

Show all in-progress tasks

task-list --status in_progress

Get JSON for automation

task-list --format json > tasks.json

Show only active directory in list format

task-list --dir active --format list

Implementation Tips for Claude Code

• Efficient Parsing: Cache parsed headers for performance

• Smart Sorting: Focus first, then by priority and progress

• Dependency Tracking: Show dependency chains if relevant

• Time Calculations: Sum estimates and actuals by directory

• Visual Appeal: Use Unicode characters for better formatting