task-progress-bar-claude 0.1.0

  ████████╗ █████╗ ███████╗██╗  ██╗
  ╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝
     ██║   ███████║███████╗█████╔╝
     ██║   ██╔══██║╚════██║██╔═██╗
     ██║   ██║  ██║███████║██║  ██╗
     ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
  ██████╗ ██████╗  ██████╗  ██████╗ ██████╗ ███████╗███████╗███████╗
  ██╔══██╗██╔══██╗██╔═══██╗██╔════╝ ██╔══██╗██╔════╝██╔════╝██╔════╝
  ██████╔╝██████╔╝██║   ██║██║  ███╗██████╔╝█████╗  ███████╗███████╗
  ██╔═══╝ ██╔══██╗██║   ██║██║   ██║██╔══██╗██╔══╝  ╚════██║╚════██║
  ██║     ██║  ██║╚██████╔╝╚██████╔╝██║  ██║███████╗███████║███████║
  ╚═╝     ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝╚══════╝
  ██████╗  █████╗ ██████╗
  ██╔══██╗██╔══██╗██╔══██╗
  ██████╔╝███████║██████╔╝
  ██╔══██╗██╔══██║██╔══██╗
  ██████╔╝██║  ██║██║  ██║
  ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝

A Claude Code hook that reads the native task list from disk and renders a live ASCII progress bar with time estimates. It uses Claude Code's PostToolUse hook system, which runs as a subprocess and consumes zero tokens.

Tasks [████████░░] 8/10 (~3m left) | ✓8 ⟳1 ○1

Existing Claude Code dashboards and extensions show token usage, API costs, and model stats. This shows work completion — how many tasks are done, how many remain, and when the current session is likely to finish.

Installation

pip install task-progress-bar-claude

After installation, inject the hooks into your Claude Code settings by running:

task-progress-bar --install

The installer verifies your ~/.claude/settings.json and patches it with the appropriate statusLine and PostToolUse hook entries.

Uninstall

To remove the hooks and cache from your system:

task-progress-bar --uninstall

Then you can uninstall the Python package:

pip uninstall task-progress-bar-claude

How it works

Architecture

Claude Code (runs tool)
    │
    ├── PostToolUse hook fires (zero tokens)
    │
    └── task_progress_bar.py (subprocess)
            │
            ├── Reads ~/.claude/tasks/*.json
            ├── Counts: completed / in_progress / pending
            ├── Updates EMA history → ~/.claude/task-progress-bar/history.json
            ├── Calculates time estimate
            └── Outputs status line → Claude Code statusLine renderer

The hook fires whenever Claude Code calls TodoWrite, TodoRead, TaskCreate, or TaskUpdate. It runs as a subprocess — Claude never sees its output, and no tokens are consumed.

Time estimation

Time estimates use an Exponential Moving Average (EMA) over task completion intervals. No AI, no API calls — pure arithmetic.

1. Record — when a task moves to completed, the timestamp is logged to ~/.claude/task-progress-bar/history.json
2. Compute — rolling average seconds-per-task using EMA (α = 0.3):

   EMA_new = α × latest_interval + (1 - α) × EMA_old
   

3. Estimate — remaining_time = EMA × tasks_remaining
4. Format — human-readable output: ~4m 12s left, ~1h 3m left, or almost done

The EMA weights recent completions heavily (α = 0.3) while smoothing out noise from variable task durations. Intervals longer than 1 hour are clamped to avoid skew from session breaks. The first 3 completions display "calculating..." until enough data exists for a meaningful estimate.

Usage

StatusLine mode

The default when running inside Claude Code. Outputs a compact ≤80-character single line for the status bar:

Tasks [████████░░] 8/10 (~3m left) | ✓8 ⟳1 ○1

Inline mode

Run standalone for a full colored multi-line view:

task-progress-bar

  📋 Task Progress
  ────────────────────────────────────────────

  [████████████████░░░░] 8/10 (80%)

    ✓ Completed:   8
    ⟳ In progress: 1
    ○ Pending:     1

  ⏱  ~3m 24s left  (102s/task avg)

Color coding

Configuration

EMA_ALPHA, MIN_SAMPLES, DONE_DISPLAY_SECS, and BAR_WIDTH are constants at the top of the plugin. Edit them directly if you run the script from source.

Edge cases

Compatibility

Supported tool names

The hook fires on both legacy and current task tools:

• TodoWrite — legacy todo creation
• TodoRead — legacy todo reading
• TaskCreate — task creation (Claude Code v2.1+)
• TaskUpdate — task status updates

Project structure

task-progress-bar/
├── task_progress_bar_claude/
│   ├── __init__.py            
│   └── task_progress_bar.py   # Main plugin — single file, stdlib only
├── pyproject.toml             # PyPI package metadata
├── README.md                  # Documentation
├── screenshots/
│   ├── demo.svg               # Animated SVG demo (CSS keyframes, no JS)
│   ├── screenshot_light.txt   # ASCII mockup — light terminals
│   └── screenshot_dark.txt    # ASCII mockup — dark terminals
└── LICENSE                    # MIT

Contributing

This project is intentionally minimal. The goal is a single Python file with zero external dependencies.

Guidelines

1. No pip dependencies — stdlib only (json, pathlib, datetime, os, sys, time)
2. Single file — all logic stays in task_progress_bar.py
3. Zero tokens — the plugin must never trigger LLM calls

Ideas

• Custom progress bar characters (▓▒░, ⣿⣀, etc.)
• Sound notification on completion
• tmux status bar integration
• Prometheus metrics export

Local testing

git clone https://github.com/PRAFULREDDYM/task-progress-bar.git
cd task-progress-bar

# Create mock tasks
mkdir -p ~/.claude/tasks
echo '[{"id":"1","status":"completed","title":"Test"},{"id":"2","status":"pending","title":"Test 2"}]' > ~/.claude/tasks/test.json

# Run inline mode
task-progress-bar

# Run status line mode
task-progress-bar --status-line

# Clean up
rm ~/.claude/tasks/test.json

License

MIT — see LICENSE.