Zero-token progress bar for Claude Code that tracks actual task completion

████████╗ █████╗ ███████╗██╗ ██╗ ╚══██╔══╝██╔══██╗██╔════╝██║ ██╔╝ ██║ ███████║███████╗█████╔╝ ██║ ██╔══██║╚════██║██╔═██╗ ██║ ██║ ██║███████║██║ ██╗ ╚═╝ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ██████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███████╗███████╗███████╗ ██╔══██╗██╔══██╗██╔═══██╗██╔════╝ ██╔══██╗██╔════╝██╔════╝██╔════╝ ██████╔╝██████╔╝██║ ██║██║ ███╗██████╔╝█████╗ ███████╗███████╗ ██╔═══╝ ██╔══██╗██║ ██║██║ ██║██╔══██╗██╔══╝ ╚════██║╚════██║ ██║ ██║ ██║╚██████╔╝╚██████╔╝██║ ██║███████╗███████║███████║ ╚═╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝╚══════╝╚══════╝ ██████╗ █████╗ ██████╗ ██╔══██╗██╔══██╗██╔══██╗ ██████╔╝███████║██████╔╝ ██╔══██╗██╔══██║██╔══██╗ ██████╔╝██║ ██║██║ ██║ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ 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 | curl -fsSL https://raw.githubusercontent.com/PRAFULREDDYM/task-progress-bar/main/install.sh | bash Or clone and install locally: git clone https://github.com/PRAFULREDDYM/task-progress-bar.git cd task-progress-bar bash install.sh The installer checks for Python 3.8+, copies the plugin to ~/.claude/task-progress-bar.py , and patches ~/.claude/settings.json with the appropriate statusLine and PostToolUse hook entries. Windows users: Native PowerShell/CMD is not supported. Use WSL and run the install command from inside WSL. bash uninstall.sh Removes ~/.claude/task-progress-bar.py , the ~/.claude/task-progress-bar/ cache directory, and all hook entries from ~/.claude/settings.json . Other settings are not modified. 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 estimates use an Exponential Moving Average (EMA) over task completion intervals. No AI, no API calls — pure arithmetic. - Record — when a task moves to completed , the timestamp is logged to~/.claude/task-progress-bar/history.json - Compute — rolling average seconds-per-task using EMA (α = 0.3): EMA_new = α × latest_interval + (1 - α) × EMA_old - Estimate — remaining_time = EMA × tasks_remaining - Format — human-readable output: ~4m 12s left ,~1h 3m left , oralmost 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. 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 Run standalone for a full colored multi-line view: python3 task_progress_bar.py 📋 Task Progress ──────────────────────────────────────────── [████████████████░░░░] 8/10 (80%) ✓ Completed: 8 ⟳ In progress: 1 ○ Pending: 1 ⏱ ~3m 24s left (102s/task avg) | Completion | Color | Example | |---|---|---| | 0–33% | Red | [███░░░░░░░] | | 33–66% | Yellow | [██████░░░░] | | 66–99% | Green | [████████░░] | | 100% | Bold green | [██████████] ✅ All done! | | 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 task_progress_bar.py . Edit them directly (or in ~/.claude/task-progress-bar.py after install). | 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 1h gap) | EMA clamps interval at 1 hour to avoid skew | | Bulk-loaded tasks (same timestamp) | Displays calculating... until real intervals exist | | Requirement | Version | |---|---| | Claude Code | v2.1+ | | Python | 3.8+ | | Dependencies | None (stdlib only) | | OS | macOS, Linux, WSL | The hook fires on both legacy and current task tools: TodoWrite — legacy todo creationTodoRead — legacy todo readingTaskCreate — task creation (Claude Code v2.1+)TaskUpdate — task status updates task-progress-bar/ ├── task_progress_bar.py # Main plugin — single file, stdlib only ├── install.sh # One-command installer ├── uninstall.sh # Clean removal ├── 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 This project is intentionally minimal. The goal is a single Python file with zero external dependencies. - No pip dependencies — stdlib only ( json ,pathlib ,datetime ,os ,sys ,time ) - Single file — all logic stays in task_progress_bar.py - Zero tokens — the plugin must never trigger LLM calls - Custom progress bar characters ( ▓▒░ ,⣿⣀ , etc.) - Sound notification on completion - tmux status bar integration - Prometheus metrics export 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 python3 task_progress_bar.py # Run status line mode python3 task_progress_bar.py --status-line # Clean up rm ~/.claude/tasks/test.json MIT — see LICENSE.