A statusline in one jq call
- Objective
- How claude-code-statusline turns Claude Code's JSON into a Powerlevel10k-style prompt, why it forks jq exactly once, and how a pure-bash wizard does live previews with arrow keys.
- Date
- · 4 min read
- Apparatus
- claude-codebashtoolsshipped
- Experiment
- EXP-006 · claude-code-statusline
- Observer
- RC · Berlin
This is the story behind claude-code-statusline, one of the experiments that made it to the top of the column.
I spend most of my day inside Claude Code, and I kept asking myself the same things. Which model is this session on? How full is the context window? How much has this conversation cost so far? How close am I to the rate limit? The answers exist, but I didn’t want to go looking for them. I wanted them sitting at the bottom of the screen, looking as good as my shell prompt.
So I built a statusline. The interesting parts turned out to be the small ones.
The contract is tiny
Claude Code lets you register a command as your statusline. Each time it redraws, it runs that command and pipes a blob of JSON into stdin: the model’s display name, the working directory, the vim mode, context-window token counts and the percentage used, cache reads and writes, the session’s total cost in dollars, and the five-hour and seven-day rate-limit percentages. Whatever the command prints becomes the status line.
That’s the whole interface. JSON comes in and one line of text goes out. Everything else is craft.
CCS_INPUT="$(cat)" # read the whole payload once
# ... parse, build segments ...
printf "%b" "$CCS_OUTPUT" # one line, with ANSI escapes interpreted
Why one jq call matters
The obvious way to read 13 fields from JSON in bash is 13 calls:
model=$(echo "$json" | jq -r .model.display_name)
cwd=$(echo "$json" | jq -r .cwd)
# ...eleven more
Each of those lines forks a subshell and starts a new jq process. That’s invisible when you run it once. A statusline runs constantly, and fourteen-plus forks every redraw is the kind of cost you feel as lag without being able to name it.
The trick is to let jq write shell code for you:
eval "$(printf '%s' "$CCS_INPUT" | jq -r '
"CCS_J_MODEL=" + (.model.display_name // "Claude" | @sh),
"CCS_J_CWD=" + (.cwd // .workspace.current_dir // "" | @sh),
"CCS_J_COST=" + (.cost.total_cost_usd // 0 | tostring | @sh),
"CCS_J_FIVE_H=" + (.rate_limits.five_hour.used_percentage // "" | tostring | @sh)
')"
One jq process emits a list of NAME=value lines. Each value goes through jq’s @sh filter, which quotes it safely for the shell. Then eval turns the whole batch into variables at once. That’s thirteen variables for a single fork. The // "Claude" and // 0 parts are jq’s “or else” defaults, so a missing field quietly becomes a sane value instead of a crash.
It’s an idea I keep reusing: when a hot path shells out, count the forks.
Eight segments, mostly honest pass-through
Each segment is a small function that turns one or two of those variables into a colored block:
- dir shortens the path:
$HOMEbecomes~, and middle folders collapse to…past a depth of four. - git prefers the worktree branch Claude Code already reports. Otherwise it asks
gitdirectly and marks the tree dirty withgit diff --quiet. - model and vim_mode just mirror what Claude Code says.
- tokens draws a little context bar. The color moves toward red at 35%, 60% and 85% full.
- cache, cost and rate_limits show Claude Code’s own numbers.
That last point is worth being honest about. The statusline does no accounting of its own. Cost, cache hits and rate limits all come from Claude Code. If a field is missing, the segment simply hides itself. I think that’s the right call: two sources of truth for money is one too many.
Making it look like Powerlevel10k
The powerline look comes from a handful of Nerd Font glyphs: rounded caps (), sharp arrows () and slants (). One detail makes it look right. The composer draws a hard separator only when two neighboring segments have different background colors. Segments that share a background, like tokens and cache, get a thin divider instead. That’s why it reads as groups rather than a row of stickers.
Colors are 256-color ANSI escapes (\033[38;5;51m). If you don’t have a Nerd Font, there are Unicode (⎇ ⚡ Σ) and plain ASCII icon sets. There are 21 themes in the repo today. The README still says four, a reminder that docs go stale the moment you get excited.
A wizard in pure bash
I didn’t want people editing config files, so I copied the best part of Powerlevel10k: a wizard that shows you each option as you choose it.
No ncurses, no dialog, just read:
read -r -s -n1 key # one raw keystroke, no echo
if [[ $key == $'\033' ]]; then # ESC: an arrow key is a 3-byte sequence
read -r -s -n2 -t 0.1 seq # grab the "[A" / "[B" that follows
fi
Each keypress clears the screen and redraws. The live preview runs each theme in its own bash -c subshell with errors suppressed, so a broken theme can’t take the wizard down with it.
When it’s done, the wizard can register itself in Claude Code’s settings. It does that carefully: it checks that jq exists, backs up your settings file with a timestamp, and writes the new version to a temp file before an atomic mv. Editing someone’s settings in place is how you lose them.
What I’d do differently
- There are no tests. For something this small it felt fine. Then I found the README and the code disagreeing about the name of the settings key, which is exactly what a ten-line test would have caught.
- The git segment still forks. The one-jq-call trick doesn’t cover
git diff. Caching the git state for a second or two would be the next win. - 256 colors only. Truecolor terminals could look better.
The lesson
The best tools I use feel instant and look like someone cared. Both of those came down to paying attention to tiny things: a fork count, a separator rule, a backup before a write. If that made you curious, the source is small enough to read in one sitting: github.com/chandrasekar-r/claude-code-statusline.