Hourglass

A context progress bar for Claude Code that displays your remaining context window as a colored status line.

Features

• Shows remaining context percentage as a visual progress bar
• Green when context is healthy (>= 15% remaining)
• Red when context is critical (< 15% remaining)
• Lightweight and fast (bash-based)

Quick Start

Clone the repository and run the installation script:

git clone https://github.com/yourusername/hourglass.git
cd hourglass
./install.sh

The installer will:

• Check and install jq if needed (supports Homebrew, apt, yum, dnf, pacman, apk)
• Copy the statusline script to ~/.claude/hourglass/
• Configure Claude Code's settings.json with the statusLine setting
• Clean up any old plugin-style installation

After installation, restart Claude Code to activate the status line.

Manual Installation

If you prefer manual installation:

Requirements

• Claude Code CLI
• jq for JSON parsing (brew install jq on macOS)

Steps

1. Copy the script to your Claude directory:

mkdir -p ~/.claude/hourglass
cp scripts/statusline.sh ~/.claude/hourglass/
chmod +x ~/.claude/hourglass/statusline.sh

2. Add the statusLine configuration to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "/Users/YOUR_USERNAME/.claude/hourglass/statusline.sh"
  }
}

Replace YOUR_USERNAME with your actual username, or use the full path from echo $HOME.

3. Restart Claude Code.

How It Works

Hourglass uses Claude Code's built-in statusLine feature, which allows you to run a custom command that outputs text to display in the status bar.

The script:

1. Receives JSON data from Claude Code via stdin containing context window information
2. Calculates remaining context percentage from input tokens, cache creation, and cache read tokens
3. Renders a 20-character progress bar with appropriate coloring

Example Output

When context is healthy:

⏳ [████████████████░░░░] 80%

When context is critical:

⏳ [██░░░░░░░░░░░░░░░░░░] 10%

Configuration

The script uses these thresholds:

Remaining	Color	Status
>= 15%	Green	Healthy
< 15%	Red	Critical

Uninstall

To remove Hourglass:

1. Remove the statusLine configuration from ~/.claude/settings.json:

# Using jq to remove the statusLine key
jq 'del(.statusLine)' ~/.claude/settings.json > /tmp/settings.json && mv /tmp/settings.json ~/.claude/settings.json

2. Remove the script directory:

rm -rf ~/.claude/hourglass

3. Restart Claude Code.

Credits

Inspired by cc-statusline.

License

MIT