Claude Code status line, and why it is blank or reads the wrong number

What the status line actually is

Anthropic describes it as a customizable bar at the bottom of Claude Code that runs any shell script you configure. The script receives JSON session data on stdin, and the bar displays whatever the script prints. That is the whole contract: one command in, one string out. Everything else on this page is detail about the two halves of it.

It draws in its own row above the footer badges rather than replacing them, and it does cost you something: with a custom status line configured, Claude Code stops showing most of the footer's keyboard hints, including esc to interrupt, the ? shortcuts hint and the voice dictation hint. If those hints are the reason you want a custom row, this is not the setting for the badges themselves.

It runs locally and does not consume API tokens, so a script that calls git or reads a file is free in the only currency that matters here. It hides temporarily during the help menu and permission prompts, which is normal and not a fault in your script.

How to set up a status line

The setting is one object. type is command, command is a script path or an inline shell command, and three optional fields adjust it: padding in characters, refreshInterval in seconds, and hideVimModeIndicator. It can live in your user settings at ~/.claude/settings.json or in a project's settings, and with nothing set there is no row at all.

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2,
    "refreshInterval": 10
  }
}

A sibling field, subagentStatusLine, rewrites the rows in the panel below the prompt that lists the subagents running in your session. It takes the same type and command and receives its own JSON, so it is a separate setting rather than a second line of this one.

Because command runs in a shell, you do not need a file at all. This one prints the model name and the context percentage using jq:

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

There is also a command that writes this for you. /statusline takes a description in plain language — “show model name and context percentage with a progress bar” — and generates a script in ~/.claude/, updating your settings to point at it. Approve the file edits it asks for, and the row appears.

The shortest script that works

Save this as ~/.claude/statusline.sh, make it executable, and point command at it. Each echo you add becomes another row.

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
echo "[$MODEL] ${DIR##*/} | ${PCT}% context"

Before you wire it in, run it by hand with mock input. A failure you find here is your script's, and a failure you find in Claude Code is usually the setting's, so the order saves you the guessing:

echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/you/project"},"context_window":{"used_percentage":25},"session_id":"test"}' | ~/.claude/statusline.sh

On Windows

Claude Code runs the command through Git Bash when Git Bash is installed, and through PowerShell when it is not. The trap is the path: Git Bash treats an unquoted backslash as an escape character, so a command written as C:\Users\you\statusline.mjs reaches the runner with its separators eaten and fails without a visible error. Write the path with forward slashes, or use ~. To run a PowerShell script, invoke powershell yourself, as powershell -NoProfile -File C:/Users/you/.claude/statusline.ps1.

The JSON your script receives

One object arrives on stdin, and it is large. The groups that matter most are the model, the workspace, the cost block, the context window, and the rate limits. Here is the shape, trimmed to what a status line usually shows:

{
  "model": { "id": "claude-opus-5-5", "display_name": "Opus" },
  "cwd": "/project",
  "workspace": {
    "current_dir": "/project",
    "project_dir": "/project",
    "added_dirs": []
  },
  "version": "2.1.310",
  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000,
    "total_lines_added": 156,
    "total_lines_removed": 23
  },
  "context_window": {
    "total_input_tokens": 15500,
    "total_output_tokens": 1200,
    "context_window_size": 200000,
    "used_percentage": 8,
    "remaining_percentage": 92,
    "current_usage": {
      "input_tokens": 8500,
      "output_tokens": 1200,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 2000
    }
  },
  "exceeds_200k_tokens": false,
  "rate_limits": {
    "five_hour": { "used_percentage": 23.5, "resets_at": 1738425600 },
    "seven_day": { "used_percentage": 41.2, "resets_at": 1738857600 }
  },
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl"
}

Beyond those there are entries for a git worktree, the repository parsed from the origin remote, an open pull request or GitLab merge request, the reasoning effort, fast mode, thinking, the vim mode, the output style and the prompt cache. The workspace.git_worktree field is worth knowing about because it is not the same as the worktree object: the first appears in any linked worktree, the second only while the session is in a worktree session.

Two rules cover most of the confusion. A number of fields are absent rather than empty when they do not apply, so a lookup for them returns nothing at all: vim with vim mode off, pr when no pull request is open, rate_limits on an API key. And two are null at particular moments: current_usage is null before the first API call and again straight after /compact until the next call repopulates it, and the two percentages can be null early in a session. Handle both in the script, and a null stops being a blank bar later.

One thing your script cannot do is ask the terminal how wide it is. Claude Code captures the output instead of connecting it to the terminal, so tput cols cannot see the size; read the COLUMNS and LINES environment variables, which Claude Code sets before each run.

When the status line updates

The script runs once when a session starts, including on resume, and after that on events: a new assistant message, a finished /compact, a permission mode change, a vim mode toggle, a change to the command itself, a rate limit window reaching its reset time, or a warm prompt cache reaching its expiry. Updates are debounced at 300ms, and a new trigger cancels a run still in flight.

That list is the reason a clock or a git branch goes stale. The event-driven triggers go quiet while the main session is idle, for instance while a coordinator waits on background subagents, and the row keeps showing what it last printed. refreshInterval is the fix: it re-runs the command every N seconds, minimum 1, on top of the events. It was added in 2.1.97, so a build older than that ignores the field.

Something else competes for that row. Outside fullscreen rendering, notifications appear on the same line as your status line, on the right-hand side, and verbose mode adds a token counter there showing your context size as the last API response reported it. On a narrow terminal those notifications can truncate your own output, which is one more reason to keep the script's text short.

Editing the script itself does not repaint the row. The change appears the next time a trigger runs it, so if you edit and see nothing, send a message before deciding the edit did not work. A change to the command string is the exception, and runs immediately.

Why the status line is blank

Anthropic lists three reasons a configured status line shows nothing: the folder you are in has not been trusted, the script fails, or a setting has switched the row off. They look identical on screen, so work them in this order rather than guessing.

The fastest way through that list is claude --debug. It logs your script's stderr on every invocation, and its exit code on the first one in a session, which separates “never ran” from “ran and failed” in a single line.

The trust case leaves a signature worth recognising: the debug log says Status line command skipped: workspace trust not accepted. Anthropic fixed a build that showed nothing at all here in 2.1.79, and the trust rule itself is deliberate, because a status line is a shell command and runs under the same rule as a hook in a settings file.

If the row shows a placeholder rather than nothing, that is a different problem with the same fix: fields can be null before the first API response completes, so the percentage reads empty until one lands. Give the value a fallback such as // 0 in jq, and restart Claude Code if it is still empty after several messages.

Two live reports describe a blank row that the checklist above will not explain, and both were still open when this page was checked. In #101734 a correctly configured statusLine is never invoked at all on macOS on 2.1.296, with a minimal script and a plugin both behaving the same way. In #95759 one failed invocation blanks the row until the next success, because the last good output is not kept, so a script that fails occasionally flickers on a schedule rather than leaving a stale line.

Why the number is wrong

The token number has one honest definition and several ways to get it wrong. The definition: context_window describes the context as of the most recent API response, not a running total for the session. That distinction was a bug once. Builds before 2.1.132 sent cumulative session totals instead, which is how a 200,000-token window came to display 169% used.

If you want your own arithmetic, match Anthropic's: used_percentage is the sum of input_tokens, cache_creation_input_tokens and cache_read_input_tokens, divided by the window. Adding output tokens to that sum is the commonest way to disagree with the built-in percentage.

The zero after compaction is the one worth writing a guard for, because it is expected rather than broken. current_usage is null immediately after /compact until the next API call fills it, and a script that computes its own percentage from that object prints 0 for that tick. Printing the pre-calculated used_percentage with a fallback is steadier than recomputing it.

One more number people misread: exceeds_200k_tokens. It is a fixed 200,000 threshold whatever your window size, so it answers a different question from the one a percentage answers. On a 200,000-token window it turns true only when that window is nearly full. On a 1,000,000-token window it turns true at 200,000 tokens, about a fifth of the way in, and stays true for most of a long session until a compaction brings the last response back under 200,000. Use context_window_size for the denominator and used_percentage for the reading.

Rate limits and quota in the status line

People asked for subscription usage on the bar for months before it existed, and the two requests that carry the ask are #5621 in August 2025 and #20636 in January 2026. Anthropic added the rate_limits object in 2.1.80: a rolling five_hour window and a weekly seven_day window, each with used_percentage from 0 to 100 and resets_at in Unix epoch seconds. The request that asked for it, #20636, was closed with a note that it was fixed as of that version.

It arrives under narrow conditions, and that is the usual reason a script shows nothing here. The object is present only for a claude.ai Pro or Max subscriber, or behind a Claude apps gateway that sets a spend limit, and only after the session's first API response. Each window can be absent independently, and a window is dropped once its resets_at passes. Handle all three: use // empty in jq so an absent window prints nothing rather than the string null.

Behind a gateway there is a third object, spend_limit, carrying a percentage and a reset time from 2.1.251, and dollar figures from 2.1.284 on both the gateway and Claude Code. The dollar fields are optional even when the object is there, and Claude Code reads them from the gateway in a separate request, about every five minutes while you send requests, so they can trail the percentage by minutes and briefly disagree with it.

Two gaps are worth knowing before you debug your own script. An enterprise claude.ai login reports its usage in /usage but sends no rate_limits in the payload at all (#96543), and on 2.1.278 a report found the field missing entirely despite the documented version (#95918). A pre-reset percentage that would not go back down after a window reset was fixed in 2.1.243, so check your build before believing a stale figure.

What people have reported

On October 25, 2026, 694 issues in Anthropic's Claude Code tracker carried statusline in the title, 60 of them open. These are the six that answer this page's two questions most directly, each read on that day.

The two requests that shaped the JSON are worth reading for a different reason. #5621 asked for quota in the payload in August 2025 and was closed by a stale-issue bot rather than by a fix. #20636 asked for the two percentages in January 2026 and was answered by 2.1.80. Whether a report is closed is not the same question as whether the behaviour changed, which is why every row above is dated.

Status line or mod?

They overlap at exactly one point and are otherwise different things. A status line is this page's subject: one settings field pointing at a shell command that prints text. A mod is a UI extension, a plugin whose hooks can draw inside the app, and drawing a status line entry is only one of the things it can do. The mods guide owns that question and this page does not re-answer it.

Where Omniscio fits

Plainly: the status line is Claude Code's own, it lives in a settings file, and nothing on this page needs Omniscio. Where Omniscio sits is one level up. It is a desktop app for running many Claude Code agents side by side, built around one calm inbox rather than a wall of terminals, and its own line is “Any model, any harness — Claude Code, Codex, OpenCode, Devin, Pi, and Hermes all supported.”

The row itself is part of the interactive screen, and Omniscio's own agent sessions are not that. It starts the Claude CLI with -p and --output-format stream-json --input-format stream-json, Claude Code's print mode, so what those sessions show you is Omniscio's session list rather than a terminal row. A status line you configure still applies to any claude you run in a terminal yourself.

That includes one inside Omniscio: its inbuilt terminal is a real shell in the project's folder, and it is a Labs feature that is off by default. If you want the row and the dashboard side by side, that is the combination to use.

Two defaults are worth knowing before you read a cost or usage figure off any bar. Omniscio's per-session spend cap applies to sessions on a metered model key or on Omniscio credits, and never to a Claude Pro or Max subscription session. And the Free plan covers 8 projects and 10 agents at once, with Pro at $20/month or $192/year. The features page lists what the app does today and the pricing page has the plans.