
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
bannerkey - A message that each user can close, on the start screen or in a dialog: set the
organizationAnnouncementkey - 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 thesessionStatusLine 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 FilesorProgram Files (x86)on the drive where Windows is installed
status-line and run these commands in your terminal:2
Set the key
Set the key’s In JSON, double each backslash in a Windows path:Add the key to the same configuration source as your other keys.
command field to the program’s full path, with no arguments or shell syntax:- 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
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.
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.exefile or a.ps1,.cmd, or.batscript. -
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
modelorcost. 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
31to36and91to96show red, green, yellow, blue, magenta, and cyan, and0or39returns to gray. Other colors show gray, and codes such as bold have no effect. -
Paths: the working directory is
/(System32on Windows).PATHis/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 asPYTHONPATHorLD_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:inferenceModelPricingEnabledis 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.
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
.ps1script 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.cmdor.exefile. - Encoding: a script must print UTF-8, or characters outside ASCII can show as ”�” or ”?”. In a
.ps1script, set UTF-8 output in the first statement, as the Windows sample does, and save the file as UTF-8 with BOM. In a.cmdor.batscript, putchcp 65001 >nulright 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.
- macOS and Linux
- Windows
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
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
Searchmain.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 configorwas not applied: Claude Desktop rejected the whole key. AFailed to parseentry says what is wrong. A version before 4.16336.0 logssessionStatusLine.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 outsideProgram Filesended 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
.ps1script that an execution policy blocks ends with code 1
was stopped after 10 seconds: the program hit the time limit. On Windows, a.ps1script can be slow to start for a few minutes after a user first opens Claude Desktop, and a.cmdor.exefile 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 nocostin its input. The entry gives the cause. Ifcostcomes 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.
PATH:
- macOS and Linux
- Windows