Claude Code Statusline

A minimal, practical status bar for Claude Code terminal sessions — showing the things that actually matter while you work: active model, git branch, context window usage, and rate limit countdowns.

Requires a paid Claude.ai plan (Pro or Max). Free accounts do not have access to Claude Code at all — it is a terminal tool that runs alongside your editor, not part of the web app.

What you're looking at

Sonnet 4.6 | no-git | ████████░░░░░░░░░░░░ 11.0% | 22k / 200k | 04:56 1% | Fri 57%

The bar and percentage share the same color zones:

These thresholds reflect two real constraints: research by AI educator Matt Pocock showing LLM quality drops past approximately 40% context fill, and Anthropic's own recommendation to run /compact manually at 60% while Claude still has full context to generate a good summary. Claude Code's auto-compact fires much later (75–95%), by which point quality has already suffered.

The rate limit segments only appear on Pro and Max plans. If you're on a Pro plan (like this setup), you see both. API key users see neither — you're billed per token with no rate windows.

Why terminal Claude Code?

The desktop and web apps are great for getting started. But the terminal version unlocks a different level:

• Hooks — run shell commands automatically before/after Claude responds, on tool calls, on session start
• MCP servers — connect Claude to your local tools, databases, and APIs
• The ! prefix — run any shell command inline without leaving the CC prompt; the output lands directly in the conversation
• This statusline — a fully programmable, persistent status bar driven by a shell script you write
• IDE integration — run CC in your VSCode or JetBrains terminal and get the best of both: Claude's context + your editor's file tree, search, and Git UI

The statusline alone is worth the switch: you always know your model, context state, and rate limit headroom without interrupting your flow.

Install (3 steps)

Step 1 — Copy the script

curl -o ~/.claude/statusline.sh https://raw.githubusercontent.com/bitcoin21ideas/claude-statusline/main/statusline.sh
chmod +x ~/.claude/statusline.sh

Or clone and copy manually:

git clone https://github.com/bitcoin21ideas/claude-statusline.git
cp claude-statusline/statusline.sh ~/.claude/statusline.sh

Step 2 — Point Claude Code at it

Add this to ~/.claude/settings.json (create it if it doesn't exist):

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

See settings-example.json in this repo for a complete example.

Step 3 — Restart Claude Code

Close and reopen your CC session. The statusline appears at the bottom of the terminal UI immediately.

How it works

After every response (and on events like /compact and permission changes), Claude Code:

1. Serializes the current session state into a JSON object
2. Pipes it to stdin of your configured command
3. Renders whatever your script prints to stdout as the status bar

Your script is just a process — any language works. This repo uses bash because it's universally available, fast to spawn, and has direct access to git, jq, and system tools with no dependencies.

Updates are debounced at ~300ms, so your script needs to be fast. The script here typically runs in under 50ms.

The one thing to know about tokens

The JSON payload includes both total_input_tokens and used_percentage. They are not the same thing and using the wrong one is the most common mistake.

• total_input_tokens — cumulative across the entire session. It can exceed your context window size as the conversation grows and gets compacted. Do not use this to calculate how full your context is.
• used_percentage — pre-calculated from your current context state. Use this. It reflects what's actually in the window right now.

The script in this repo derives the absolute token count from used_percentage × window_size so the bar, percentage, and token count are always consistent with each other.

Customize it

The script is readable bash — open ~/.claude/statusline.sh and edit freely. A few ideas:

Show the session cost (useful for API key users):

cost=$(echo "$input" | jq -r '.cost.total_cost_usd // empty')
[ -n "$cost" ] && printf " | \$%.4f" "$cost"

Show vim mode (if you use CC's vim keybindings):

vim_mode=$(echo "$input" | jq -r '.vim.mode // empty')
[ -n "$vim_mode" ] && printf " | %s" "$vim_mode"

Extract a Jira/Linear ticket number from your branch name:

ticket=$(echo "$branch" | grep -oE '[A-Z]+-[0-9]+' | head -1)
[ -n "$ticket" ] && printf " | %s" "$ticket"

Use a project-specific statusline by creating .claude/settings.json inside any repo with its own statusLine block — it overrides the global one for that project only.

The JSON payload

Everything available to your script:

{
  "cwd": "/current/dir",
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "version": "2.1.90",

  "model": {
    "id": "claude-sonnet-4-6",
    "display_name": "Sonnet"
  },

  "workspace": {
    "current_dir": "/project",
    "project_dir": "/original/project",
    "git_worktree": "feature-xyz"
  },

  "context_window": {
    "context_window_size": 200000,
    "used_percentage": 11.0,
    "remaining_percentage": 89.0,
    "total_input_tokens": 22000,
    "total_output_tokens": 4521,
    "current_usage": {
      "input_tokens": 8500,
      "output_tokens": 1200,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 2000
    }
  },

  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000,
    "total_lines_added": 156,
    "total_lines_removed": 23
  },

  "rate_limits": {
    "five_hour": {
      "used_percentage": 1.0,
      "resets_at": 1738425600
    },
    "seven_day": {
      "used_percentage": 57.0,
      "resets_at": 1738857600
    }
  },

  "vim": { "mode": "NORMAL" },
  "effort": { "level": "high" },
  "thinking": { "enabled": true },
  "agent": { "name": "my-agent" }
}

rate_limits only appears on Pro/Max plans. vim, effort, thinking, and agent only appear when those features are active.

Going further

This is a minimal, beginner-friendly setup. If you want more, check out ccstatusline that offers pre-built themes and more configuration options

Made by Tony • Feedback and PRs welcome