task-progress-bar-claude 0.1.0

Zero-token, zero-cost task progress bar for Claude Code.

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

Zero-token, zero-cost progress bar for Claude Code

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.

	Token Cost	What It Shows
Typical extensions	💰 Tokens per query	API usage, cost, model info
task-progress-bar	🆓 Zero	Task completion, time remaining

---

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

Completion	Color	Example
0–33%	Red	[███░░░░░░░]
33–66%	Yellow	[██████░░░░]
66–99%	Green	[████████░░]
100%	Bold green	[██████████] ✅ All done!

---

Configuration

Option	Default	Description
--status-line	false	Output compact single-line for Claude Code statusLine
--update	false	Alias for --status-line, used by PostToolUse hook
--tasks-dir PATH	~/.claude/tasks/	Custom path to task JSON files
EMA_ALPHA	0.3	EMA smoothing factor (0.1 = smoother, 0.5 = more reactive)
MIN_SAMPLES	3	Minimum completions before showing time estimates
DONE_DISPLAY_SECS	30	Seconds to show "All done" before hiding
BAR_WIDTH	20	Character width of the progress bar

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

Scenario	Behavior
No tasks exist	Empty output — status line hidden
Task file missing or malformed	Silent fail — no output, no crash
All tasks complete	Displays ✅ All done! (N tasks) for 30s, then hides
Single task	Progress bar shown, no time estimate
Time estimate < 10s	Displays almost done
Session break (>1h gap)	EMA clamps interval at 1 hour to avoid skew
Bulk-loaded tasks (same timestamp)	Displays calculating... until real intervals exist

---

Compatibility

Requirement	Version
Claude Code	v2.1+
Python	3.8+
Dependencies	None (stdlib only)
OS	macOS, Linux, WSL

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.