Customize your status line changedstatusline
Nearest release: v2.1.294, published an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 8 Oct 2026 02:40 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 8 Oct 2026 03:07 UTC.
Upstream edited
Recorded here
Lines+39added
Lines−31removed
From line
132
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits29to this page, all time
### When the status line updates ### What your script can output ### Size output to the terminal ### Status line not appearing ### Status line shows `--` or empty values ### Context percentage shows unexpected values ### OSC 8 links not clickable ### Display glitches with escape sequences ### Workspace trust required ### Script errors or hangs ### Notifications share the status line row
The whole hunk
from line 132, old and new numbered
/
from line 132
132132
133133Claude Code runs your script with [JSON session data](#available-data) on stdin and displays whatever the script prints to stdout.
134134
135**When it updates**
135<Note>The status line runs locally and does not consume API tokens. It temporarily hides during certain UI interactions, including the help menu and permission prompts.</Note>
136136
137### When the status line updates
138
137139Your script runs once when a session starts, including when you resume one. After that, it runs again when:
138140
139141* A new assistant message arrives
from line 151
149151
150152The event-driven triggers can go quiet when the main session is idle, for example while a coordinator waits on background subagents. To keep time-based or externally-sourced segments current during idle periods, set [`refreshInterval`](#manually-configure-a-status-line) to also re-run the command on a fixed timer.
151153
152**What your script can output**
154### What your script can output
153155
156Your script can print more than a single line of plain text:
157
154158* **Multiple lines**: each `echo` or `print` statement displays as a separate row. See the [multi-line example](#display-multiple-lines).
155159* **Colors**: use [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors) like `\033[32m` for green (terminal must support them). See the [git status example](#git-status-with-colors).
156160* **Links**: use [OSC 8 escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) to make text clickable (Cmd+click on macOS, Ctrl+click on Windows/Linux). Requires a terminal that supports hyperlinks like iTerm2, Kitty, or WezTerm. See the [clickable links example](#clickable-links).
157161
158**Sizing output to the terminal**
162### Size output to the terminal
159163
160164Claude Code captures your script's output instead of connecting it directly to the terminal, so `tput cols` and language-level width detection cannot read the terminal size from inside the script. Read the `COLUMNS` and `LINES` environment variables instead. Claude Code sets these to the current terminal dimensions before running your script.
161165
162<Note>The status line runs locally and does not consume API tokens. It temporarily hides during certain UI interactions, including the help menu and permission prompts.</Note>
163
164166## Available data
165167
166168Claude Code sends the following JSON fields to your script via stdin:
from line 1163
11611163
11621164## Troubleshooting
11631165
1164**Status line not appearing**
1166If the status line is blank, start with [Status line not appearing](#status-line-not-appearing). A folder you haven't trusted and a script that fails also leave it blank, as [Workspace trust required](#workspace-trust-required) and [Script errors or hangs](#script-errors-or-hangs) describe.
11651167
1168### Status line not appearing
1169
1170If you configured a status line and nothing shows at the bottom of the interface, work through these checks:
1171
11661172* Verify your script is executable: `chmod +x ~/.claude/statusline.sh`
11671173* Check that your script outputs to stdout, not stderr
11681174* Run your script manually to verify it produces output
from line 1178
11721178* Run `claude --debug` to log your script's stderr on every status line invocation, and its exit code on the first invocation in a session
11731179* Ask Claude to read your settings file and execute the `statusLine` command directly to surface errors
11741180
1175**Status line shows `--` or empty values**
1181### Status line shows `--` or empty values
11761182
1177* Fields may be `null` before the first API response completes
1178* Handle null values in your script with fallbacks such as `// 0` in jq
1179* Restart Claude Code if values remain empty after multiple messages
1183Fields may be `null` before the first API response completes, so handle null values in your script with fallbacks such as `// 0` in jq. Restart Claude Code if values remain empty after multiple messages.
11801184
1181**Context percentage shows unexpected values**
1185### Context percentage shows unexpected values
11821186
1183* Use `used_percentage` for the simplest accurate context state
1184* The status line reports the counts from the last API response, while `/context` adds an estimate for messages added since that response, so `/context` can read higher until the next response
1187The status line reports the counts from the last API response, while `/context` adds an estimate for messages added since that response, so `/context` can read higher until the next response. Use `used_percentage` for the simplest accurate context state. For the formula behind `used_percentage`, see [Context window fields](#context-window-fields).
11851188
1186**OSC 8 links not clickable**
1189### OSC 8 links not clickable
11871190
1191Whether a link is clickable depends on your terminal, on whether Claude Code detects hyperlink support in it, on whether SSH or tmux strips the escape sequence, and on how your script prints it:
1192
11881193* Verify your terminal supports OSC 8 hyperlinks (iTerm2, Kitty, WezTerm)
11891194
11901195* Terminal.app does not support clickable links
from line 1210
12051210
12061211* If escape sequences appear as literal text like `\e]8;;`, use `printf '%b'` instead of `echo -e` for more reliable escape handling
12071212
1208**Display glitches with escape sequences**
1213### Display glitches with escape sequences
12091214
1210* Complex escape sequences (ANSI colors, OSC 8 links) can occasionally cause garbled output if they overlap with other UI updates
1211* If you see corrupted text, try simplifying your script to plain text output
1212* Multi-line status lines with escape codes are more prone to rendering issues than single-line plain text
1215Complex escape sequences (ANSI colors, OSC 8 links) can occasionally cause garbled output if they overlap with other UI updates. Multi-line status lines with escape codes are more prone to rendering issues than single-line plain text.
12131216
1214**Workspace trust required**
1217If you see corrupted text, try simplifying your script to plain text output.
12151218
1216* Because `statusLine` executes a shell command, Claude Code runs it under the same [workspace trust rule as hooks in settings files](/docs/en/permissions#what-runs-before-you-trust-a-folder). Accepting the dialog for the folder, or for a parent directory whose trust extends to it, is enough.
1217* Until then, the status line stays blank, and `claude --debug` logs `Status line command skipped: workspace trust not accepted`. Restart Claude Code and accept the trust dialog to enable it.
1219### Workspace trust required
12181220
1219**Script errors or hangs**
1221Until you accept the workspace trust dialog, the status line stays blank. Because `statusLine` executes a shell command, Claude Code runs it under the same [workspace trust rule as hooks in settings files](/docs/en/permissions#what-runs-before-you-trust-a-folder). Accepting the dialog for the folder, or for a parent directory whose trust extends to it, is enough.
12201222
1223Until then, `claude --debug` logs `Status line command skipped: workspace trust not accepted`. Restart Claude Code and accept the trust dialog to enable it.
1224
1225### Script errors or hangs
1226
1227Claude Code displays your script's output only after the script exits with code 0:
1228
12211229* Scripts that exit with non-zero codes or produce no output cause the status line to go blank
12221230* Slow scripts block the status line from updating until they complete. Keep scripts fast to avoid stale output.
12231231* If a new update triggers while a slow script is running, the in-flight script is cancelled
12241232* Test your script independently with mock input before configuring it
12251233
1226**Notifications share the status line row**
1234### Notifications share the status line row
12271235
12281236Outside [fullscreen rendering](/docs/en/fullscreen), Claude Code shows notifications on the same row as your status line. In fullscreen rendering, Claude Code gives notifications a row of their own.
12291237
No line in this hunk matches that.