Zest

CLAUDE CODE · STATUS LINE

Claude Code status line
with model, context and limits.

The Claude Code status line is a command set under statusLine in ~/.claude/settings.json: it reads the session as JSON on stdin (model, context, cost, rate limits) and Claude Code shows what it prints at the bottom. /statusline writes one for you from a plain request.

Start free
npx @winding-labs/zest

Free for 3 seats · No credit card · One command signs in every agent on your machine

Sample data

Stack in the Zest app: how well your setup is wired, and what raises the score

USED BY ENGINEERING TEAMS AT

Flyps Charm Wildfires Geoforge MisaLabs

How to set up a Claude Code statusline

The quick way is /statusline with what you want in plain words, such as /statusline show model name and context percentage with a progress bar. Claude Code writes a script in ~/.claude/ and points your settings at it. /statusline delete removes it again.

By hand, add statusLine to ~/.claude/settings.json or a project's settings. command is a script path or an inline shell command. padding adds spaces, refreshInterval also re-runs it every N seconds (1 or more) for clocks and other time-based parts, and hideVimModeIndicator hides the built-in vim mode text when your script prints it.

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

When the command runs and what it can print

Claude Code runs the command with the session JSON on stdin and shows what it prints to stdout. Like a hook in settings, it waits until you trust the folder.

  • It runs when a session starts or resumes, after each assistant message and /compact, when the permission mode or vim mode changes, and when a rate-limit window resets. Updates are debounced by 300 ms, and a new update cancels a run still in progress.
  • Each line printed becomes a row. ANSI colors work, and OSC 8 links are clickable in terminals that support them.
  • tput cols can't see the terminal from inside the script; read the COLUMNS and LINES environment variables instead.
  • Keep it fast and cache slow parts such as git status: while a slow script runs, the line stays stale.

The JSON a status line command receives

The fields worth a place on the line. Some are absent or null early in a session, so give each one a fallback, such as // 0 or // empty in jq:

Status line input fields in Anthropic's status line docs.
FieldWhat it holds
model.display_name, model.idThe current model
context_window.used_percentageShare of the context window in use, counted from input tokens only
context_window.context_window_size200,000 tokens, or 1,000,000 on extended-context models
rate_limits.five_hour, rate_limits.seven_dayused_percentage and resets_at for each limit. Pro and Max only, after the first response
cost.total_cost_usdClaude Code's own estimate at list price, not your bill. Resets on /clear
cost.total_duration_ms, cost.total_lines_addedSession time and lines changed
effort.level, fast_modeEffort level and whether fast mode is on
workspace.current_dir, workspace.repoWorking directory, and the origin remote's host, owner and name
pr.number, pr.review_stateThe open pull request for the branch
prompt_cache.warm, prompt_cache.hit_ratioThe main conversation's cache state
session_id, transcript_pathFor scripts that read the session's transcript; Claude Code session history covers the format

A status line recipe: model, context and 5-hour limit

Save this jq program as ~/.claude/statusline.jq. It prints a line such as Opus 5.5 · 44% context · 5h limit 23%, and leaves the limit out where rate_limits is absent, such as on an API key. Ready-made meters on the same fields, with reset countdowns and forecasts, are on Claude usage trackers.

Then point statusLine at it, and test it with a sample of the JSON before you rely on it:

~/.claude/statusline.jq
[
  .model.display_name,
  "\(.context_window.used_percentage // 0 | floor)% context",
  (.rate_limits.five_hour.used_percentage // empty | "5h limit \(floor)%")
] | join(" · ")
~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "jq -r -f ~/.claude/statusline.jq"
  }
}
Test it
echo '{"model":{"display_name":"Opus 5.5"},"context_window":{"used_percentage":44},"rate_limits":{"five_hour":{"used_percentage":23}}}' \
  | jq -r -f ~/.claude/statusline.jq

Why is my status line blank?

Run the command yourself with sample input first. If it works there, start claude --debug: the log records the script's stderr on every run and its exit code on the first, and says Status line command skipped: workspace trust not accepted when trust is the cause.

Status line problems and their fixes, from Anthropic's status line docs.
CauseFix
The folder isn't trusted yetRestart Claude Code and accept the trust dialog
The script isn't executablechmod +x ~/.claude/statusline.sh
It prints to stderr, or exits non-zeroPrint to stdout and exit 0
disableAllHooks is trueIt turns your status line off too; only one from managed settings still runs
Your organization sets allowManagedHooksOnlyOnly a status line from managed settings runs
Values show -- or emptyFields are null until the first response; add fallbacks

When a plugin wants the status line: Zest's wrapper

Claude Code runs one statusLine command, so a plugin that wants the slot has to replace yours or wrap it. Copy your entry before you install one, and check which it does.

Zest's plugin wraps. It saves your command in ~/.claude-zest/statusline-proxy.json, runs it with the same JSON and shows the first line it prints, adding nothing of its own. With no status line of yours, Zest's notices (plugin update, standup ready, sync error) show only after /zest:enable-notify. While it wraps, it keeps a snapshot of each session's model, effort, context use and limit meters, with no prompts or message text. On Pro and Max, where Claude Code sends the limit meters, a lead sees who keeps running out of the five-hour window before choosing plans on Claude Code pricing. More on Claude Code usage.

From the snapshots kept for one engineer's 186 work sessions (September 23 to October 4, 2026, all on Opus 5.5 with a 1M window): the median session ended at 44.5% of the context window, and 12% ended at 80% or more. Effort was xhigh in 53% and medium in the rest. Of the 147 sessions that carried a weekly meter, 16 ended at 90% or more. These are each session's last snapshot only.

Spend in the Zest app: your agent usage at list prices, by week and by modelSample data

TRY IT ON YOUR TEAM

See what your team ships with AI.

Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month. See pricing

Start free
npx @winding-labs/zest

A FEW THINGS TO KNOW

Questions

How do I remove the status line?+

Run /statusline delete, or delete the statusLine field from your settings.json.

Why doesn't my status line show usage limits?+

Claude Code sends rate_limits only to Claude.ai Pro and Max subscribers, or behind a gateway that sets a spend limit, and only after the session's first response. Elsewhere the field is absent, so give it a fallback.

Does the status line use tokens?+

No. Anthropic's docs say the status line runs locally and doesn't consume API tokens.

Can I change how subagents show below the prompt?+

Yes. The subagentStatusLine setting runs a command that rewrites each subagent's row in the agent panel, under the same trust rules as statusLine.