Claude Code Status Line: the 7 gotchas that make yours lie to you (payload reference, copy-paste snippets, and a one-line install)

A developer detailed the seven pitfalls that cause Claude Code status lines to display incorrect information, based on their experience building and refining one. The post includes the full JSON structure passed to the status line command, code snippets for debugging, and a one-line installable version. The developer emphasized that these bugs are undocumented and were present in their own shipped status line for weeks.

Everything I learned writing and rewriting a Claude Code status line: the full shape of the JSON you get on stdin, the seven bugs that quietly make a status line wrong, and a finished one you can install in a single line. The bugs are the interesting part. Every one of these was in my own status line, shipped, for weeks. None of them are in the docs. How it looks schematically: ✻ O5 H ┃ 📁 my-repo 🌿 main ●3 ↑1 ┃ 💰 $0.42 · 4m +1.2k/-340 ┃ 🧠 36% 357k/1.0M ⏱5h 63% ↻1h07m ┃ ☕ 52m break session place change budget rest Contents How a status line works https://gist.github.com/starred.atom how-a-status-line-works The JSON you actually get https://gist.github.com/starred.atom the-json-you-actually-get The 7 gotchas https://gist.github.com/starred.atom the-7-gotchas Snippets worth stealing https://gist.github.com/starred.atom snippets-worth-stealing Or just install mine https://gist.github.com/starred.atom or-just-install-mine Claude Code runs one command of your choosing on every render and pipes it a JSON blob describing the session. Whatever the command prints on stdout becomes the bar at the bottom of your window. That is the entire contract. { "statusLine": { "type": "command", "command": "python3 \"/Users/you/.claude/glint.py\"" } } It runs locally, on your machine, with no API calls, so it costs nothing and counts against no quota. It also runs constantly , which is the source of gotcha 4. Two ways to get one: - Type /statusline show model, git branch and context percentage and Claude writes the script for you. Good starting point, zero trust required. - Install a finished one. Mine is one line https://gist.github.com/starred.atom or-just-install-mine . Fields I have actually consumed in a working status line, so this is what I can vouch for rather than a copy of a schema. There are more session id , output style , version , and the set drifts, which is why the dump script below matters. Anything can be absent, and the ones marked sometimes are absent most of the time, which is exactly how a status line ends up printing None . { "model": { "display name": "Claude Opus 4.6", "id": "claude-opus-4-6" }, "workspace": { "current dir": "/Users/you/code/repo", "git worktree": "wt-refactor" }, "cwd": "/Users/you/code/repo", "transcript path": "/Users/you/.claude/projects/<slug /<uuid .jsonl", "context window": { "total input tokens": 357000, // input side of the last turn "context window size": 1000000, // authoritative: 200000 or 1000000 "used percentage": 36, // null until the first assistant turn "remaining percentage": 64 }, "cost": { "total cost usd": 0.42, "total duration ms": 244000, "total lines added": 1247, "total lines removed": 340 }, // sometimes: paid plans that report quota "rate limits": { "five hour": { "used percentage": 63, "resets at": "2026-08-05T23:00:00Z" }, "seven day": { "used percentage": 10, "resets at": "2026-08-08T00:00:00Z" } }, // sometimes "effort": { "level": "high" }, // low | medium | high | xhigh | max "fast mode": true, "worktree": { "name": "wt-refactor" }, "exceeds 200k tokens": true } Print the whole thing once and read it yourself, because this list will drift: python cat ~/.claude/dump.py <<'PY' import json, sys json.dump json.load sys.stdin , open "/tmp/statusline.json", "w" , indent=2 print "✻ dumped" PY point statusLine.command at it, render once, then: cat /tmp/statusline.json Emoji occupy two terminal cells, ANSI colour codes occupy zero, and OSC 8 hyperlinks hide an entire URL in zero cells. Measure len line and a "fits in 120 columns" line clips mid-number at 100. python import re, unicodedata ANSI = re.compile r"\033\ 0-9; m" OSC8 = re.compile r"\033\ 8;; ^\033\a ?:\033\\|\a " def vis width s : text = OSC8.sub "", ANSI.sub "", s w = 0 for i, ch in enumerate text : if ord ch == 0xFE0F or unicodedata.combining ch : continue selectors and marks are free wide = text i+1:i+2 == "\ufe0f" or 0x1F000 <= ord ch <= 0x1FAFF w += 2 if wide else 1 return w The obvious fix is "treat U+2600 to U+27BF as wide". That range is full of emoji, but it also holds ✻ U+273B , ⚠ U+26A0 , ✓ , ✗ , which render one cell wide unless followed by a U+FE0F presentation selector. Overcounting is not safe either: my line measured 3 cells too wide and dropped a segment on terminals with room to spare. The rule that works: wide if the codepoint is emoji-by-default Emoji Presentation=Yes , or if the next character is U+FE0F. ♻️ is two cells. ♻ is one. Deriving the limit yourself with something like tokens 200000 ? 1M : 200k is wrong on turn one: tokens is 0 or tiny, so a 1M session gets drawn against 200k and shows 75% when you are at 15%. context window size is authoritative and already accounts for a 1M window. Trust it whenever it is present, and derive the percentage from the token count while used percentage is still null. cw = data.get "context window" or {} limit = cw.get "context window size" if not isinstance limit, int, float or limit <= 0: only guess if truly absent limit = 1 000 000 if data.get "exceeds 200k tokens" else 200 000 pct = cw "used percentage" / 100 if isinstance cw.get "used percentage" , int, float \ else min cw.get "total input tokens" or 0 / limit, 1.0 The command runs on every render. A gh pr list call is 300 to 900 ms of network, and your bar now lags behind your typing. Pattern that works: read a cache file, show whatever is in it immediately, and spawn a detached refresh when it is stale. Never block a render on the network. subprocess.Popen sys.executable, file , "--refresh", cache, cwd, branch , stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start new session=True The flip side: because renders track activity, the gap between two renders is idle time . That is a free signal. I use it to notice you have been working for 90 minutes without a break. Be careful what you write during a render, though: if reading a value also stamps "last seen", then a status command that reports the value corrupts the thing it reports. Reads must be read-only. If you fall back to parsing transcript path needed on older versions that have no context window , the naive "last assistant turn" is often a sub-agent's turn. Sub-agents have their own windows, so your gauge starts reporting a delegate's usage, which is usually far smaller, and you get told you have plenty of room right before auto-compact fires. Skip any line with isSidechain: true , take the last main-thread assistant turn, and sum the input side: usage "input tokens" + usage "cache creation input tokens" + usage "cache read input tokens" The standard one-liner is curl -fsSL .../install.sh | bash , which means the script's own stdin is the script. read -r answer gets script bytes, not a keypress. So you read /dev/tty instead. Then the second trap: -r /dev/tty returns true in containers and CI where opening it still fails, so you print a question nobody can answer and follow it with an error. Test by opening it: if { exec 3</dev/tty; } 2 /dev/null; then group redirect applies before the failing one printf 'Enable gauges? y/N ' read -r reply <&3 || reply="" exec 3<&- fi If you cache to /tmp/mytool-<something-guessable .json , another local user can create that file first and choose what your status line renders. That matters more than it sounds, because a status line is a great place to hide a lie: an OSC 8 hyperlink shows friendly text while pointing anywhere, and nobody inspects their own prompt. Cheap fixes, all of them worth it: write with O EXCL and mode 0600 , read back only if you own it and it is a regular file O NOFOLLOW , and refuse to linkify a URL that is not https:// . fd = os.open path, os.O RDONLY | getattr os, "O NOFOLLOW", 0 st = os.fstat fd if not stat.S ISREG st.st mode or hasattr os, "getuid" and st.st uid = os.getuid : raise PermissionError path hasattr os, "getuid" is not paranoia, it is gotcha 7b: os.getuid does not exist on Windows. Mine raised there, the catch-all swallowed it, and Windows users saw a bare badge and nothing else for weeks. Truecolor and 256-colour text python def c text, color, bold=False : xterm-256, widely supported return f"\033 {'1;' if bold else ''}38;5;{color}m{text}\033 0m" A clickable link OSC 8 . Terminals without support just show the text. python def link text, url : return f"\033 8;;{url}\033\\{text}\033 8;;\033\\" Terminal width, when stdout is a pipe. os.get terminal size on stdout fails here, so ask stderr, then the tty, then COLUMNS . python def term width default=120 : for fd in 2, 1 : stderr first: stdout is a pipe here try: return os.get terminal size fd .columns except Exception: pass try: with open "/dev/tty" as t: return os.get terminal size t.fileno .columns except Exception: pass try: return int os.environ "COLUMNS" except Exception: return default Drop segments by priority until the line fits , instead of clipping. Give each segment a number, drop the highest until it fits, then put back anything that still has room. Keep the model badge unconditional so a narrow window loses detail, not identity. Time until a quota reset , accepting both epoch seconds and ISO 8601, because resets at has appeared as each: python import datetime as dt def seconds until v : try: t = dt.datetime.fromtimestamp float v , dt.timezone.utc if isinstance v, int, float else dt.datetime.fromisoformat str v .replace "Z", "+00:00" left = t - dt.datetime.now dt.timezone.utc .total seconds return left if left 0 else None except Exception: return None Never crash the bar. Wrap everything and fall back to a bare badge. An exception here means an empty status line, and an empty status line looks like Claude Code is broken. if name == " main ": try: main except Exception: sys.stdout.write "\033 38;5;209m✻ Claude\033 0m" glint https://github.com/oleg-koval/glint : one Python file, zero dependencies, every gotcha above already handled. curl -fsSL https://raw.githubusercontent.com/oleg-koval/glint/main/install.sh | bash ✻ O5 H ┃ 📁 my-repo 🌿 main ●3 ↑1 ┃ 💰 $0.42 · 4m +1.2k/-340 ┃ 🧠 36% 357k/1.0M ⏱5h 63% ↻1h07m ┃ ☕ 52m break | Group | Shows | |---|---| | session | model, reasoning effort, fast mode | | place | directory, git branch with dirty count and ahead/behind, worktree, open PR with CI state as a clickable link | | change | session cost and duration, lines added and removed | | budget | live context percentage with a runway countdown, prompt-cache hit ratio, 5h and 7d quota with reset ETAs, a pace marker when you are burning quota faster than the window elapses | | rest | how long you have worked without a break | The last group is the one nobody else has. It stays invisible until you have worked 30 unbroken minutes, then: | At | Shows | |---|---| | 30 min | dim 🪑 34m , just a clock | | 50 min | ☕ 52m break | | 90 min | bold red 🛑 1h35m stand up | Thresholds are where three lines of evidence roughly agree: sedentary research finds the harm is in uninterrupted sitting and interrupts it every 20 to 30 minutes, DeskTime's data put the most productive rhythm near 52 minutes on and 17 off, and attention runs on roughly 90-minute ultradian cycles. Walking away for ten minutes resets the clock by itself; a shorter break you report with glint.py --rested . Move the whole ladder with GLINT REST NUDGE=40 , or switch it off with GLINT REST=0 . There is also an optional companion Stop hook, glint alert.py , that notifies you at 75% and 90% context so you compact deliberately instead of being surprised by auto-compact. Everything is a toggle: GLINT BARS=1 adds block gauges next to the percentages, and GLINT COST , GLINT LINES , GLINT CACHE , GLINT RATELIMITS , GLINT WORKTREE , GLINT PR , GLINT REST each turn a segment off. Works on macOS, Linux and Windows. MIT. Corrections and additions welcome in the comments. If you found an eighth way for a status line to lie, I want to know about it.