Skip to main content
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:

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.
1

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, and the path isn’t under /home, /net, or /Volumes
  • 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:
2

Set the key

Set the key’s command field to the program’s full path, with no arguments or shell syntax:
In JSON, double each backslash in a Windows path:
Add the key to the same configuration source as your other keys.If one configuration serves several operating systems, such as a bootstrap server’s response, add platformOverrides with a command under win32 (Windows), darwin (macOS), or linux. In a macOS profile, a Windows registry policy, or the Linux configuration file, set only command. Versions before 4.16336.0 reject the whole key and show no status line, so add platformOverrides only after every device has updated. The top-level command is required and runs on any system you don’t list:
3

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.
On Claude Desktop 4.16336.0 or later, if inferenceModelPricingEnabled is also on, the status line replaces the “Session cost (estimate)” line.

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 #!. Claude Desktop doesn’t check the interpreter that a #! line names, so install it where users can’t change it too. Python also runs code from the user’s folders unless you start it with -I, for example #!/usr/bin/python3 -I. On Windows, an .exe file or a .ps1, .cmd, or .bat script.
  • Input: one line of JSON on standard input, with the session ID, the model, and the session cost. A field with no value is left out, so handle a missing model or cost. Later versions can add fields, so ignore any that the program doesn’t use. Don’t build a file path from these values.
  • Output: the first non-empty line of standard output, read as UTF-8, 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, 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_*, GIT_*, and variables that change which code a program loads, such as PYTHONPATH or LD_LIBRARY_PATH.
  • Time limit: 10 seconds, after which Claude Desktop stops the program and anything it started.

Session cost in the status line input

cost.total_cost_usd is the session’s estimated cost so far. Claude Desktop sends it only while inferenceModelPricingEnabled is on and the session has an estimate. The value is a number in US dollars with up to six decimal places and no exponent. It’s for display only and can differ from your provider’s bill.
  • Source: Claude Desktop’s own sum for the session, added up on the user’s device. It covers Cowork, Chat, and Code sessions, including Code sessions over SSH. With no status line set, the built-in “Session cost (estimate)” line above the message box shows the same sum.
  • Models with no price: a model ID that can’t be matched to a Claude model, such as an opaque gateway alias, adds nothing. After you give that ID a rate in inferenceModelPricing, only its later usage counts. The input doesn’t show that the sum is partial.
  • Missing cost: don’t show $0. Check for each of these causes:
    • inferenceModelPricingEnabled is off
    • The session has no priced estimate yet, such as before Claude Desktop records its first turn’s cost or when it has used only models with no price
    • Claude Desktop couldn’t read its usage ledger, the local record of these estimates
  • Scripts written for Claude Code: Claude Code’s status line always sends cost, among many other fields. Claude Desktop sends only the fields in the sample input, so check a script that you carry over for other fields and for a fallback to 0. Claude Desktop’s sum can also differ from Claude Code’s total, for example after /clear.
This macOS and Linux script prints the cost. While cost is missing it prints nothing, so no line shows:

Status line scripts on Windows

A .ps1 script runs in Windows PowerShell, not PowerShell 7.
  • Execution policy: if Group Policy allows only signed scripts, sign the .ps1 script with a certificate that each device trusts, and add it to each device’s Trusted Publishers store. If Group Policy turns scripts off, use a .cmd or .exe file.
  • Encoding: a script must print UTF-8, or characters outside ASCII can show as ”�” or ”?”. In a .ps1 script, set UTF-8 output in the first statement, as the Windows sample does, and save the file as UTF-8 with BOM. In a .cmd or .bat script, put chcp 65001 >nul right after @echo off, and save the file as UTF-8 without BOM.

Sample status line programs

Both samples print a budget line, ■■■■■■■■□□ 82% 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
  • A turn’s result arrives
  • The user picks another model
  • The app regains focus
There’s no timer, so new data shows the next time one of these happens. A turn’s result closes the turn, and Claude Desktop doesn’t add the turn to the session cost until the result arrives. That can be seconds after Claude’s answer ends, for example when a Stop hook runs first. The program can then run twice for the turn, and the first run’s cost may not include the turn yet. If the program exits with a code other than 0, 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. Claude Desktop doesn’t log every failure of the same kind, so restart it after each fix. The entries don’t include the program’s output.
  • Failed to parse managed config or was not applied: Claude Desktop rejected the whole key. A Failed to parse entry says what is wrong. A version before 4.16336.0 logs sessionStatusLine.platformOverrides ignored, so update that device.
  • 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: any code other than 0 hides the line, even if the program printed one
    • macOS and Linux: code 127 means that a command the script runs wasn’t found, so call each tool by its full path
    • Windows: a .ps1 script that an execution policy blocks ends with code 1
  • was stopped after 10 seconds: the program hit the time limit. On Windows, a .ps1 script can be slow to start for a few minutes after a user first opens Claude Desktop, and a .cmd or .exe file starts faster. If the line appears after a later turn ends or the app regains focus, nothing needs fixing.
  • runs without the session's cost: Claude Desktop couldn’t read its usage ledger, the local record of cost estimates, so the program ran with no cost in its input. The entry gives the cause. If cost comes back 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.
To see the program’s own error messages, run it in a new terminal window with Claude Desktop’s working directory and PATH: