Show a status line - Claude.ai Documentation

The status line is one line of your organization’s own text, such as budget used or a data-handling label, above the message box in Cowork, Chat, and Code sessions. Claude Desktop on third-party (3P) runs a program that you install on the user’s device and shows the first line the program prints.

The Claude Desktop message box. Above it, right-aligned in small gray text, a ten-square bar and the words 82% of $500 used this month. The first eight squares and the 82% are colored. — A status line that shows budget use, with made-up data.

These cases are covered on other pages:

A notice across the top of the app window, with no program to install: set the banner key
Your own message when your gateway blocks a user at a spend limit: see Block requests at a spend limit

Turn on the status line

The status line requires Claude Desktop 4.4212.0 or later and is off until you set the sessionStatusLine key. The status line isn’t available on a self-hosted install.

Install the program

Put the program where users can’t change it. Claude Desktop runs it only from a location that meets these rules:

macOS and Linux: root owns the file and every parent folder, with no write access for group or others
Windows: the file is under Program Files or Program Files (x86) on the drive where Windows is installed

To try the macOS and Linux sample on a test device, save it as status-line and run these commands in your terminal:

sudo mkdir -p /opt/example/bin
sudo cp status-line /opt/example/bin/status-line
echo "410 500" | sudo tee /opt/example/budget.txt
sudo chown -R 0:0 /opt/example
sudo chmod 755 /opt/example /opt/example/bin /opt/example/bin/status-line
sudo chmod 644 /opt/example/budget.txt

Set the key

Set the key’s command field to the program’s full path, with no arguments or shell syntax:

{ "sessionStatusLine": { "command": "/opt/example/bin/status-line" } }

In JSON, double each backslash in a Windows path:

{ "sessionStatusLine": { "command": "C:\\Program Files\\Example\\status-line.ps1" } }

Add the key to the same configuration source as your other keys.

macOS profile or Windows registry: write the value as a JSON string
Bootstrap server: the key applies after the user approves it in a dialog, unless the device trusts the server’s values without prompting

Restart Claude Desktop and check the line

Quit and reopen Claude Desktop, then open an existing session, or start a new one and send a message. The line appears above the message box.

Write the status line program

Claude Desktop starts the status line program with no arguments and no window, as the user who runs Claude Desktop.

File type: on macOS and Linux, an executable file, such as a compiled program or a script that starts with #!. On Windows, an .exe file or a .ps1, .cmd, or .bat script. A .ps1 script runs in Windows PowerShell, not PowerShell 7.
Input: one line of JSON on standard input, with the session ID and the model. A field with no value is left out, so handle a missing model.
{"session_id":"local_1f0c2a9e-7b3d-4c58-9a16-5e2d8b40c7f3","model":{"id":"claude-sonnet-4-5","display_name":"Claude Sonnet 4.5"}}
Output: the first non-empty line of standard output, up to 200 characters. Markup and links show as plain text. A line wider than the message box ends in ”…” and shows in full on hover.
Colors: text is gray by default. ANSI codes 31 to 36 and 91 to 96 show red, green, yellow, blue, magenta, and cyan, in shades that fit the light or dark theme, and 0 or 39 returns to gray. Other colors show gray, and codes such as bold have no effect.
Paths: the working directory is / (System32 on Windows). PATH is /usr/bin:/bin:/usr/sbin:/sbin, or the System32, Windows, and Windows PowerShell folders on Windows, so call other tools by their full path.
Environment: the app’s variables, minus ANTHROPIC_*, CLAUDE_*, ELECTRON_*, and variables that make an interpreter load code, such as PYTHONPATH.
Time limit: 10 seconds, after which Claude Desktop stops the program and anything it started. On Windows, the time PowerShell takes to start counts toward the limit.

Sample status line programs

Both samples print a budget line, ■■■■■■■■□□ 82% of $500 used this month. The macOS and Linux sample reads its numbers from a file that your own scheduled job keeps up to date. The Windows sample prints fixed numbers and shows how a PowerShell script prints UTF-8, reads the input, and writes the escape character.

macOS and Linux
Windows

#!/bin/sh
# Prints, for example: ■■■■■■■■□□ 82% of $500 used this month
# Your own scheduled job keeps this file up to date. It holds dollars used and
# the limit as two whole numbers, for example: 410 500
BUDGET_FILE=/opt/example/budget.txt

# Unless the file holds two whole numbers, print nothing so no line shows.
[ -r "$BUDGET_FILE" ] || exit 0
read -r used limit < "$BUDGET_FILE"
case "$used" in ''|0?*|*[!0-9]*) exit 0 ;; esac
case "$limit" in ''|0*|*[!0-9]*) exit 0 ;; esac

percent=$((used * 100 / limit))
if [ "$percent" -ge 90 ]; then color=31      # red
elif [ "$percent" -ge 70 ]; then color=33    # yellow
else color=32                                # green
fi

full="" empty=""
for step in 10 20 30 40 50 60 70 80 90 100; do
  if [ "$percent" -ge "$step" ]; then full="${full}■"; else empty="${empty}□"; fi
done

printf '\033[%sm%s\033[0m%s \033[%sm%s%%\033[0m of $%s used this month\n' \
  "$color" "$full" "$empty" "$color" "$percent" "$limit"

# Print UTF-8, so that characters outside ASCII show correctly.
[Console]::OutputEncoding = New-Object Text.UTF8Encoding $false

# Read the session data, one line of JSON. Use fields such as $session.model.display_name.
$line = [Console]::In.ReadLine()
$session = $line | ConvertFrom-Json

# Fixed numbers keep the sample short. Replace them with your own budget data.
$esc = [char]27
$yellow = $esc + '[33m'
$reset = $esc + '[0m'
$full = ([string][char]0x25A0) * 8
$empty = ([string][char]0x25A1) * 2
$bar = $yellow + $full + $reset + $empty
Write-Output ($bar + ' ' + $yellow + '82%' + $reset + ' of $500 used this month')

When the status line updates

Claude Desktop runs the status line program at these moments:

A session opens
Claude finishes a turn
The user picks another model
The app regains focus

There’s no timer, so new data shows the next time one of these happens. If the program fails, prints nothing, or takes longer than 10 seconds, the line disappears and the user sees no error. The next successful run brings the line back.

Troubleshoot a missing status line

Search main.log in the logs directory on the user’s device for sessionStatusLine. One entry can stand for many failures of the same kind, and the entries don’t include the program’s output.

was not run: fix the cause the entry gives, such as a folder that users can write to or a Windows path outside Program Files
ended with exit code 127: a command that the script runs wasn’t found, so call each tool by its full path
was stopped after 10 seconds: the program hit the time limit. On Windows, a .ps1 script can be slow to start in the first minutes after Claude Desktop first launches. If the line appears after a later turn ends or the app regains focus, nothing needs fixing.
No entry: the program printed nothing, which isn’t logged, or the key hasn’t reached the app. Restart Claude Desktop and check which configuration source applies.

​Turn on the status line

​Write the status line program

​Sample status line programs

​When the status line updates

​Troubleshoot a missing status line

Turn on the status line

Write the status line program

Sample status line programs

When the status line updates

Troubleshoot a missing status line