Set up a Claude Code status line for model name, git branch, session cost, and context usage. settings.json config, JSON input, bash, Python, Node.js scripts.
Set up a custom Claude Code status line showing model name, git branch, cost, and context usage. Includes ready-to-copy scripts.
Your Claude Code terminal is missing useful information. The status line fixes that by putting model name, git branch, session cost, and context usage right at the bottom of the interface.
Think of it like PS1 for Claude Code. If you've ever customized a shell prompt with Oh-my-zsh or Starship, this is the same idea. One line of real-time info that keeps you oriented while you work.
The status line sits at the bottom of the Claude Code interface and updates every time the conversation changes. It can display anything your script outputs: the current model, which git branch you're on, how much you've spent this session, or how full your context window is.
Here's what a configured status line looks like in practice:
[Opus] my-project | main | $0.42 | Context: 37%
That single line tells you the model, the project folder, the git branch, the session cost so far, and the percentage of your context window used. All updated automatically.
The fastest path to a working status line is the built-in /statusline command. Type it directly into Claude Code and it generates a script for you.
/statusline
Claude Code will create a status line script that mirrors your terminal prompt by default. But you can also give it specific instructions:
/statusline show the model name in orange
/statusline display git branch and session cost
/statusline show context window percentage with color coding
That's it. Claude Code writes the script, configures the settings, and the status line appears. If you want more control, keep reading for manual setup.
Understanding the mechanics helps when debugging or building custom scripts:
Update trigger: The status line refreshes whenever conversation messages change
Throttle: Updates run at most every 300ms to avoid performance issues
Output handling: Only the first line of stdout from your script becomes the status line text
Colors: Full ANSI color code support for styling
Input: Claude Code pipes a JSON object with session data into your script via stdin
That last point is the key. Your script receives structured JSON containing the current model, workspace paths, session cost, context window stats, and more. Parse it, format it, print one line to stdout.
The context percentage turns green below 50%, yellow between 50-80%, and red above 80%. You can immediately see when it's time to manage your context window.
Watching your context window is one of the most practical uses for the status line. When context fills up, Claude Code compacts the conversation and you lose detail. Knowing where you stand helps you decide when to start fresh or compact strategically.
Simple approach using the pre-calculated percentage:
The manual approach lets you see raw token numbers alongside the percentage. Useful when you want to know exactly how many tokens you have left, especially when picking between different models with different context sizes.
If you're on a budget or tracking costs per feature, this is immediately useful. Pair it with model selection strategies to switch models when a task doesn't need the most expensive option.
The most common cause is a missing execute permission on the script file. Fix it with:
chmod +x ~/.claude/statusline.sh
Script runs but output is empty
Your script might be writing to stderr instead of stdout. The status line only reads the first line of stdout. Add a simple echo "test" to verify output, then build from there.
Testing your script manually
You can test without running Claude Code by piping mock JSON into your script:
Once you have the basics working, here are some ideas to make your status line more useful:
Lines changed tracker: Show +added/-removed to monitor session productivity
Session duration: Calculate elapsed time from total_duration_ms
Model ID display: Show the full model identifier when testing different model configurations
Project vs current directory: Show both when Claude Code navigates into subdirectories
Cost-per-minute: Divide total_cost_usd by total_duration_ms to see burn rate
Context window bar: Replace the percentage with a visual bar like [========--]
Conditional warnings: Flash a color when context exceeds 80% or cost passes a threshold
The status line runs a script you control. If you can write it in bash, Python, or Node.js, you can display it. If you'd rather skip the scripting, ClaudeFast's Code Kit ships with a pre-built statusline-monitor.mjs that displays context usage, API budget, and backup status out of the box.