Troubleshooting

Start with explain — it prints the raw stdin payload, every parsed value, the API and cache state, and your effective configuration. Most problems are visible in that output.

Nothing renders at all

  • Confirm the statusLine key exists in ~/.claude/settings.json and points at a file that exists.
  • Restart Claude Code. Status line configuration is read at startup.
  • Run the script by hand: echo '{}' | bash ~/.claude/statusline-command.sh. If bash reports a syntax error, the copy is truncated — reinstall.
  • Check that jq is on the PATH that Claude Code sees, which is not always your interactive shell’s PATH.

The rate-limit dashboard is missing

The 5-hour and 7-day bars come from the stdin payload, which requires Claude Code 2.1.140 or newer. Upgrade Claude Code, then run explain and look at the raw JSON: if there is no rate-limit data in the payload, the version is the cause.

Also confirm CESL_SHOW_RATE_BLOCK is not set to 0.

There is no 5-hour row

On a verified Ultra account (formerly Max 20x), Anthropic removed the 5-hour limit on 2026-10-30, so there is no 5-hour window to draw. The 7-day row and the per-model rows still render. explain prints a line when the payload has a 7-day window but no 5-hour one.

The per-model and extra-usage rows never appear

Those two rows are API enrichment and need an OAuth token. explain reports whether one was resolved. The lookup order is:

  1. CLAUDE_CODE_OAUTH_TOKEN
  2. ~/.claude/.credentials.json
  3. secret-tool (Linux keyring)
  4. macOS Keychain

If none resolves, the rows are skipped deliberately — this is not an error state, and the rest of the line is unaffected.

Extra-usage credits only render when extra usage is actually enabled on your account.

Also check CESL_SHOW_SCOPED and CESL_SHOW_EXTRA. With both set to 0 the API is never called at all, and explain says so on its needed: line.

The request runs in the background, so the rows are missing on the very first render and appear on the next one. explain reports the state of the digest and of the last fetch on its digest: and fetch: lines.

The pace projection never appears

⇢ NN% is deliberately quiet. It is suppressed in the first tenth of a window, when the projected figure lands below CESL_WARN, and when it barely differs from the current one — in other words, whenever your pace is fine. explain prints the computed value on its projection: line, so you can see what it decided and why nothing rendered.

It also needs a resets_at stamp in the stdin payload. Older Claude Code versions do not send one.

Values look stale

Check the version first: ~/.claude/statusline-command.sh version. Before v2.3.0, a render started more than a hundred processes. On Windows (Git Bash) that took several seconds, and Claude Code cancels a render that is still running when the next update arrives, so the line could lag far behind the session. Upgrade.

The usage API response is cached for CESL_CACHE_TTL seconds (60 by default), and it is refreshed in the background, so the per-model and extra-usage rows can be one refresh behind. Lower the TTL, or delete the cache directory reported by explain, to force a refresh.

Cost, duration, context and lines-changed come from the stdin payload and are never cached.

Claude Code re-runs the status line on events (a new message, a mode change). An idle session keeps the last render. Set refreshInterval in the statusLine block of ~/.claude/settings.json if you want time-based parts, such as a cold prompt cache, to update while idle.

Boxes, question marks or mangled characters

Your terminal or font cannot render the default glyph set. Switch:

CESL_GLYPHS=ascii

Use nerd only if you actually have a Nerd Font installed — it draws a branch glyph from the private-use range that other fonts render as a box.

The line is cut off on the right

Claude Code truncates rather than wraps. Turn off segments you do not need or shrink the bars — see Keep the line short on narrow terminals.

Colours look wrong or absent

If colour is missing entirely, check NO_COLOR and TERM first — both are honoured, and explain reports what it resolved on its colour: line. Force it back on with CESL_COLOR=1.

The palette uses truecolor escape sequences. In a terminal limited to 256 colours the output degrades, sometimes badly. Confirm your terminal advertises truecolor (echo $COLORTERM should print truecolor or 24bit), and remember that multiplexers like tmux need explicit truecolor passthrough configured.

A config change has no effect

Environment variables win over the config file. If CESL_* is exported in your shell profile, it overrides whatever you edit in config.sh. explain shows the merged result, which settles this quickly.

Also check CESL_CONFIG — if it is set, the script reads that path instead of the default one.

The status line feels slow

A render is around 65 ms on Linux and under a second on Windows (Git Bash), where starting a process is expensive. The usage API is never on the render path. If it feels slower:

  • Check the version with ~/.claude/statusline-command.sh version. Versions before 2.3.0 were much slower, mostly on Windows.
  • Git operations in a very large repository can dominate. Git and keychain lookups are bounded to roughly 2 seconds so they can never freeze the line, but you can remove the cost entirely with CESL_SHOW_GIT=0.

Something else

Open an issue on GitHub, including the explain output with any token redacted.