# Claude Code status line: setup, examples, and the fields you can show

A line at the bottom of Claude Code that shows whatever your script prints: model, context, cost, limits, branch. How to set one up in a minute, and what to do when it stays blank.

Published 2026-10-08 by Richard Kaminsky and Mitchell Lipyansky, the co-founders of Poly. Canonical: https://usepoly.co/claude-code-statusline
Poly is a multiplayer AI coding workspace: a shared room where your team works with one AI agent, together. Free to start: https://usepoly.co/

**The Claude Code status line is "a customizable bar at the bottom of Claude Code that runs any shell script you configure." Claude Code sends your script a JSON description of the session on standard input, such as the model, how full the context window is, the session's estimated cost and your plan's usage limits, and shows whatever the script prints. The quickest setup is `/statusline` followed by what you want, which writes the script and the setting for you. It runs on your machine and "does not consume API tokens."**

## Key takeaways

- **Set it up:** `/statusline show model name and context percentage with a progress bar` ([Anthropic](https://code.claude.com/docs/en/statusline)).
- **Or by hand:** a `statusLine` object in settings.json pointing to a script.
- **What it can show:** model, context used, estimated cost, lines changed, rate limits, git worktree, pull request and more.
- **Updates:** after each message and other events, batched every 300ms, or on a timer with `refreshInterval`.
- **Blank?** Usually a script that isn't executable, writes to stderr or exits with an error, or a folder you haven't trusted yet.

## How do you set up the Claude Code status line?

**With `/statusline`:** describe what you want, and Claude Code "generates a script file in `~/.claude/` and updates your settings automatically." With no description it copies your shell prompt. To remove it, run `/statusline delete` ([Anthropic](https://code.claude.com/docs/en/statusline)).

**By hand:** add this to `~/.claude/settings.json` (or a project's `.claude/settings.json`):

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

`padding` adds horizontal space, and `refreshInterval` re-runs the script every N seconds (minimum 1) for things like a clock. Then make the script executable with `chmod +x`.

## A simple status line script

This one shows the model, how full the context window is and the session's estimated cost. It needs `jq`:

```bash
#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
printf '[%s] %s%% context | $%.2f\n' "$MODEL" "$PCT" "$COST"
```

Each line your script prints becomes a row, and ANSI colors and clickable OSC 8 links work. Anthropic's docs have ready-made Bash, Python and Node versions of a context bar, colored git status, cost and duration, a multi-line layout with color thresholds, a link to the repository, rate limits, and caching slow git calls ([Anthropic](https://code.claude.com/docs/en/statusline)).

## What data does the status line get?

The JSON on standard input includes ([Anthropic](https://code.claude.com/docs/en/statusline)):

- **Model and session:** `model.id`, `model.display_name`, `session_id`, `session_name`, `version`, `output_style.name`, effort level, thinking and fast mode.
- **Folders:** `cwd`, `workspace.current_dir`, `workspace.project_dir`, added directories, the git worktree and the repository's host, owner and name.
- **Context:** `context_window.used_percentage`, `remaining_percentage`, `context_window_size` and token counts from the last response.
- **Cost:** `cost.total_cost_usd`, "computed client-side at list price," so it "may differ from your actual bill," plus duration and lines added and removed.
- **Limits:** `rate_limits.five_hour` and `rate_limits.seven_day` with the percentage used and reset time, only "for claude.ai Pro and Max subscribers," and only after the first response.
- **Extras when present:** the prompt cache's state, vim mode, the agent's name, the current pull request and worktree details.

Fields can be null before the first response, so give them fallbacks, as `// 0` does above. For the context window, Anthropic recommends `used_percentage` ([Claude Code context window](/claude-code-context-window)).

## When does the status line update?

At the start of a session, after each new message, when `/compact` finishes, when the permission or vim mode changes, and on your `refreshInterval` timer. Claude Code "debounces updates at 300ms," and a new update cancels a script still running. Output appears only after the script exits with code 0, so a slow script leaves the line stale. Read the terminal width from the `COLUMNS` variable; `tput cols` can't see it from inside the script.

## Does the status line work on Windows?

Yes. Claude Code runs the command through Git Bash when it's installed, or through PowerShell otherwise. Use forward slashes in the path, because Git Bash strips backslashes and the command fails with no visible error. For a PowerShell script: `powershell -NoProfile -File C:/Users/you/.claude/statusline.ps1` ([Anthropic](https://code.claude.com/docs/en/statusline)).

## Why is my Claude Code status line not showing?

Anthropic's checklist ([Anthropic](https://code.claude.com/docs/en/statusline)):

1. **The script isn't executable:** `chmod +x ~/.claude/statusline.sh`.
2. **It prints to stderr,** not stdout, or prints nothing.
3. **It exits with an error.** Any non-zero exit leaves the line blank.
4. **The folder isn't trusted yet.** Because it runs a shell command, the status line waits for the workspace trust dialog, like [hooks](/claude-code-hooks).
5. **Backslashes in a Windows path.**
6. **`disableAllHooks` is on,** or your organization allows only managed hooks.

Run `claude --debug` to log the script's errors, and run the script yourself with sample JSON.

## Can a plugin add a status line?

Not the main one. Plugins can ship only an `agent` setting and a `subagentStatusLine`, which customizes the rows in the subagent panel ([Anthropic](https://code.claude.com/docs/en/plugins-reference)). Community status-line plugins instead include a setup command that writes the `statusLine` setting for you ([Claude Code plugins](/claude-code-plugins)).

## Popular Claude Code status lines on GitHub

Community projects, not Anthropic's, with GitHub stars on October 8, 2026:

- **[claude-hud](https://github.com/jarrodwatts/claude-hud)** (28,400 stars, MIT): a plugin showing context, rate limits, tools, agents and to-dos.
- **[ccusage](https://github.com/ccusage/ccusage)** (18,900 stars for the whole tool): its `ccusage statusline` command shows session and daily cost and the five-hour block.
- **[ccstatusline](https://github.com/sirmalloc/ccstatusline)** (13,200 stars, MIT): an interactive widget menu with powerline styles and themes; Anthropic's docs link to it.
- **[claude-powerline](https://github.com/Owloops/claude-powerline)** (1,200 stars, MIT): a vim-style powerline bar.

Read a community script before you run it: it executes on every update with your user's permissions ([Is Claude Code safe?](/claude-code-security)).

## How has the status line changed?

- **August 2025 (v1.0.71):** the status line and `/statusline` launched.
- **August 2025 to January 2026:** cost fields, then context window fields and percentages.
- **March to April 2026:** rate limits, `refreshInterval` and git worktree fields.
- **May 2026:** repository and pull request details, and `COLUMNS` for width.
- **August to October 2026:** prompt cache and spend-limit fields, and a Windows fix (v2.1.293).

From Anthropic's changelog ([GitHub](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)).

## Does Codex have a status line?

Yes, but you pick from built-in items rather than write a script: `tui.status_line` in `config.toml` is an "Ordered list of TUI footer status-line item identifiers," also set with `/statusline` ([OpenAI](https://developers.openai.com/codex/config-reference)).

## Seeing usage as a team

A status line shows one person's context and cost. In Poly (usepoly.co), a team works with one Claude Code or Codex agent in a shared browser room, and every turn's receipt shows who ran it, which model, how full the context is and what it cost. Free to start. [What is Poly?](/what-is-poly)

## Common questions

**How do I set up the status line in Claude Code?**

Run /statusline followed by what you want shown, for example model name and context percentage, and Claude Code writes the script and updates your settings. Or add a statusLine object with type command and the script's path to settings.json.

**Why is my Claude Code status line not showing?**

Usually the script isn't executable, prints to stderr or nothing, or exits with an error, or you haven't accepted the folder's trust dialog. On Windows, use forward slashes in the path. Run claude --debug to see the script's errors.

**Can the status line show my usage limits?**

Yes, on Pro and Max: the JSON includes rate_limits.five_hour and rate_limits.seven_day with the percentage used and when each resets, after the first response in a session.

**Does the Claude Code status line use tokens?**

No. It runs a script on your machine and does not consume API tokens. The /statusline command uses Claude once to write the script.

**Does the status line work on Windows?**

Yes. It runs through Git Bash if installed, otherwise PowerShell. Use forward slashes in the command path, and call a PowerShell script with powershell -NoProfile -File.

More guides: https://usepoly.co/guides · Security: https://usepoly.co/security · Pricing: https://usepoly.co/pricing