claude-code-statusline

README

Claude Code Statusline

A fast, lightweight statusline for Claude Code showing git info, API usage, costs, and more.

Features

• Git status: branch, modified/staged/untracked indicators, ahead/behind
• Model: current Claude model in use
• Context window: visual usage bar with color-coded thresholds
• Subscription: plan type and rate limit tier
• Costs: daily/weekly/monthly token costs from your usage logs
• API usage: current utilization % and time until reset
• Tool activity: running tools with spinner, completed tool counts
• Agent tracking: subagent status with description and elapsed time
• Todo progress: current task and completion count
• Session duration: time since session started

Installation

Claude Code Plugin (Recommended)

In any Claude Code session:

/plugin marketplace add erwint/claude-code-statusline
/plugin install cc-statusline@cc-statusline

Restart Claude Code. The binary downloads automatically and the statusline appears.

If the statusline doesn't appear, run /cc-statusline:setup to manually install.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/erwint/claude-code-statusline/main/install.sh | bash

Or clone and install manually:

git clone https://github.com/erwint/claude-code-statusline.git
cd claude-code-statusline
./install.sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/erwint/claude-code-statusline/main/install.ps1 | iex

Or download and run manually:

Invoke-WebRequest -Uri https://raw.githubusercontent.com/erwint/claude-code-statusline/main/install.ps1 -OutFile install.ps1
.\install.ps1

Build from source

Requires Go 1.21+:

go build -ldflags="-s -w" -o claude-code-statusline .

Force source build with the install script:

BUILD_FROM_SOURCE=1 ./install.sh

Configuration

The install script automatically configures Claude Code by adding to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/bin/claude-code-statusline"
  }
}

Environment Variables

Variable	Default	Description
CLAUDE_STATUS_CACHE_TTL	300	Cache TTL in seconds for API usage
CLAUDE_STATUS_DISPLAY_MODE	colors	colors, minimal, or background
CLAUDE_STATUS_INFO_MODE	none	none, emoji, or text
CLAUDE_STATUS_AGGREGATION	fixed	Cost aggregation: fixed or sliding
CLAUDE_STATUS_AUTO_UPDATE	true	Enable automatic daily update checks
CLAUDE_STATUS_DEBUG	false	Enable debug logging to /tmp/claude-statusline.log
CLAUDE_STATUS_CONTEXT	true	Show context window usage bar
CLAUDE_STATUS_TOOLS	true	Show tool activity
CLAUDE_STATUS_AGENTS	true	Show agent activity
CLAUDE_STATUS_TODOS	true	Show todo progress
CLAUDE_STATUS_DURATION	true	Show session duration

Aggregation modes:

• fixed: Calendar periods - today, this week (Mon-Sun), this month (1st onwards)
• sliding: Rolling windows - last 24h, last 7 days, last 30 days

Command Line Flags

--cache-ttl <seconds>   Cache TTL for API usage (default: 300)
--no-color              Disable ANSI colors
--display-mode <mode>   colors|minimal|background
--info-mode <mode>      none|emoji|text
--aggregation <mode>    fixed|sliding (default: fixed)
--auto-update           Enable automatic daily updates (default: true)
--debug                 Enable debug logging to /tmp/claude-statusline.log
--show-context          Show context window usage (default: true)
--show-tools            Show tool activity (default: true)
--show-agents           Show agent activity (default: true)
--show-todos            Show todo progress (default: true)
--show-duration         Show session duration (default: true)
--version               Show version info
--update                Download and install the latest version

Auto-updates: By default, the statusline checks for updates once per day (with ±2 hour jitter to avoid server load). If a new version is available, it automatically downloads and installs it in the background. You can disable this with --auto-update=false or CLAUDE_STATUS_AUTO_UPDATE=false.

How It Works

1. Git info: Runs git commands to get branch and status
2. Model & context: Receives current model and context window via stdin JSON from Claude Code
3. Credentials: Reads from ~/.claude/credentials.json, falls back to system keychain
4. API usage: Fetches from Anthropic's OAuth API (cached)
5. Costs: Parses ~/.claude/projects/*/*.jsonl logs (incremental, cached)
6. Activity: Parses transcript JSONL for tools, agents, todos, and session start

Supported Platforms

Pre-built binaries are available for:

• macOS (Intel and Apple Silicon)
• Linux (x64 and ARM64)
• Windows (x64 and ARM64)

Acknowledgments

Inspired by gabriel-dehan/claude_monitor_statusline and jarrodwatts/claude-hud.

License

MIT