Custom Command Statusline

Configure a fully custom status line using your own shell script with access to session context data.

When to Use This Setting

Apply this setting when you need to:

• Build a completely custom statusline tailored to your specific workflow and information needs
• Access session context data including model name, directory, and session ID via JSON stdin
• Maintain a reusable statusline script that can be shared across team members and projects Consider alternatives when:
• A pre-built statusline template already provides the information you need
• You do not want to maintain a custom script and prefer a configuration-only approach

Quick Start

Configuration

Copy
name: custom-command-statusline
type: setting
category: statusline

Example Application

Copy
claude setting:apply custom-command-statusline

Example Output

Setting applied. Changes:
- statusLine.type: command
- statusLine.command: ~/.claude/statusline.sh
- statusLine.padding: 0

Core Concepts

Custom Script Interface Overview

Aspect	Details
Input Format	Session context delivered as JSON via stdin to the script
JSON Fields	model.display_name, workspace.current_dir, session_id available in the input
Script Location	Any executable script, typically placed in ~/.claude/ for discoverability
Output	Script stdout becomes the statusline text, one line expected

Script Execution Architecture

+---------------------------+
|  Claude Code Engine       |
+---------------------------+
         |
         | JSON stdin
         v
+---------------------------+
|  ~/.claude/statusline.sh  |
+---------------------------+
|  Read JSON from stdin     |
|  Parse with jq/python     |
|  Compute custom metrics   |
|  Format output string     |
+---------------------------+
         |
         | stdout
         v
+---------------------------+
|  Status Line Display      |
|  (your custom output)     |
+---------------------------+

Configuration

Parameter	Type	Default	Description
statusLine.type	string	"command"	Must be set to "command" to enable script-based statusline
statusLine.command	string	"~/.claude/statusline.sh"	Path to the executable script that generates statusline content
statusLine.padding	number	0	Number of padding characters added around the statusline output
Script Permissions	string	"755"	The script must be executable (chmod +x) to run
JSON Input Schema	object	N/A	Session context object with model, workspace, and session fields

Best Practices

1. Start with a simple script and iterate - Begin with a script that outputs the model name and directory. Add complexity incrementally as you identify which metrics are most valuable for your workflow.
2. Use jq for JSON parsing - The session context arrives as JSON on stdin. Use jq for reliable field extraction rather than string manipulation with grep or sed.
3. Keep execution time under 100ms - The statusline script runs on every interaction. Slow scripts create noticeable delays. Avoid network calls or expensive file system scans in your script.
4. Handle missing data gracefully - Not all JSON fields may be present in every context. Use jq's default operators or shell fallbacks to prevent errors when fields are absent.
5. Version control your statusline script - Store the script in your dotfiles repository so it follows you across machines and can be shared with team members.

Common Issues

1. Script not found error - Verify the path in statusLine.command is correct and the script exists. Tilde expansion may not work in all contexts; use the full absolute path if needed. Check that the file has not been accidentally deleted or moved to a different directory.
2. Permission denied when running script - The script must be executable. Run chmod +x ~/.claude/statusline.sh to set the executable permission. On some systems you may also need to verify the shebang line at the top of the script matches an installed interpreter.
3. Empty statusline output - If the script produces no output, check that it reads from stdin correctly. The JSON input must be consumed via a read command or piped to a parser before the script can produce output. Test manually with echo '{}' | ~/.claude/statusline.sh to verify.