Metadata-Version: 2.4
Name: task-progress-bar-claude
Version: 0.1.0
Summary: Zero-token, zero-cost task progress bar for Claude Code.
Author: Praful Reddy
License: MIT
Project-URL: Homepage, https://github.com/PRAFULREDDYM/task-progress-bar
Project-URL: Bug Tracker, https://github.com/PRAFULREDDYM/task-progress-bar/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

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

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

[![License: MIT](https://img.shields.io/badge/License-MIT-a6e3a1.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-89b4fa.svg)](https://python.org)
[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-f9e2af.svg)](#)
[![Claude Code](https://img.shields.io/badge/Claude_Code-v2.1%2B-cba6f7.svg)](#compatibility)

</div>

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.

<div align="center">
<img src="screenshots/demo.svg" alt="task-progress-bar animated demo" width="600" />
</div>

```
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

```bash
pip install task-progress-bar-claude
```

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

```bash
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:

```bash
task-progress-bar --uninstall
```

Then you can uninstall the Python package:

```bash
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:

```bash
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

```bash
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](LICENSE).
