claude-code-statusline

A real-time statusline for Claude Code that tracks context usage, costs, and optionally logs sessions to Obsidian.

Features

• Context rot tracking — visual progress bar + health warnings at 70% and 85%
• Real-time cost — per-1k-token rate and session total
• API spend — per-key month-to-date cost tracked locally from Claude Code sessions
• GitHub identity — shows your @username from gh CLI
• Obsidian logging — auto-generates daily session tables (optional)

Quick Install

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

The installer will:

1. Copy statusline.sh to ~/.claude/statusline.sh
2. Add the statusLine config to ~/.claude/settings.json (preserves existing settings)
3. Optionally prompt for environment variables

Manual Setup

1. Copy the script

cp statusline.sh ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

2. Add to settings

Add this to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "bash ~/.claude/statusline.sh"
  }
}

3. Restart Claude Code

The statusline appears at the bottom of your terminal.

Configuration

All configuration is via environment variables. Add these to your .zshrc / .bashrc:

Example .zshrc

# Claude Code Statusline
export OBSIDIAN_VAULT="$HOME/Documents/MyVault"
export ANTHROPIC_ADMIN_API_KEY="sk-ant-admin01-..."

Dependencies

Context Rot Thresholds

The statusline warns you as context fills up:

Obsidian Integration

When OBSIDIAN_VAULT is set, the statusline creates daily notes at:

{OBSIDIAN_VAULT}/Claude Sessions/Claude Sessions — 2025-03-15.md

Each note contains a live-updating table:

Plus a footer with month-to-date API spend.

See examples/obsidian-sample.md for a full example.

API Spend Tracking

To track your total Anthropic API spend:

1. Go to console.anthropic.com/settings/admin-keys
2. Create an Admin API key
3. Set ANTHROPIC_ADMIN_API_KEY in your shell profile

The API cost is cached for 5 minutes to avoid excessive requests. Without this key, the statusline tracks session costs locally.

Note: The Admin API returns costs in cents. The script divides by 100 to display dollars correctly.

How It Works

Claude Code pipes a JSON blob to the statusline command on each update. The script:

1. Parses the JSON with jq for model, tokens, cost, and context window data
2. Calculates real-time cost-per-1k-tokens
3. Fetches your GitHub username (cached 60 min)
4. Optionally queries the Anthropic Admin API for month-to-date spend (cached 5 min)
5. Builds a visual progress bar and context health warning
6. Outputs the formatted statusline
7. Optionally appends a row to the Obsidian daily note

Troubleshooting

Statusline not showing?

• Make sure ~/.claude/settings.json has the statusLine config
• Restart Claude Code after making changes

jq: command not found

• Install jq: brew install jq (macOS) or apt install jq (Linux)

CC cost shows $0.00?

• Costs are tracked locally from Claude Code sessions — they accumulate as you use Claude Code
• The counter resets each billing cycle (controlled by ANTHROPIC_BILLING_START_DAY)
• To see the running total: jq '[.[]] | add // 0' ~/.claude/.cc_sessions.json
• To reset manually: echo '{}' > ~/.claude/.cc_sessions.json

GitHub username not showing?

• Make sure you're logged in: gh auth status
• Cache refreshes every 60 minutes (check ~/.claude/.gh_user_cache)

Obsidian notes not appearing?

• Verify OBSIDIAN_VAULT points to a valid directory: ls $OBSIDIAN_VAULT
• Notes are created in $OBSIDIAN_VAULT/Claude Sessions/

License

MIT — see LICENSE