[Docs] Undocumented `statusline` configuration feature

Resolved 💬 2 comments Opened Aug 8, 2025 by coygeek Closed Aug 9, 2025

Title: [Docs] Undocumented statusline configuration feature

Body:

Summary

I've discovered what appears to be a powerful statusline configuration feature in settings.json for customizing the interactive prompt. This feature is not mentioned anywhere in the official documentation, making it difficult for users to discover, use, or understand its full capabilities.

How I Discovered It

I discovered this feature after running a subagent named statusline-setup. This agent automatically modified my user-level ~/.claude/settings.json file, adding a statusLine object. This implies it's an intended, albeit undocumented, feature.

Observed Functionality

Based on the configuration and its effect on the CLI, the statusline feature appears to:

  1. Be configured in settings.json with a type of "command".
  2. Execute a shell command to generate the prompt's status line.
  3. Receive session data as a JSON object via standard input to the command. This JSON contains keys like workspace.current_dir and model.display_name.
  4. Allow for rich, dynamic prompts using tools like jq to parse the session data and echo with ANSI codes for color.
My Configuration Example

Here is the configuration that was added to my settings.json file by the statusline-setup agent:

{
  "statusLine": {
    "type": "command",
    "command": "input=$(cat); echo \"\\033[1;32m➜\\033[0m \\033[36m$(echo \"$input\" | jq -r '.workspace.current_dir' | sed \"s|^$HOME|~|\" | sed 's|.*/||')\\033[0m \\033[90m[$(echo \"$input\" | jq -r '.model.display_name')]\\033[0m\""
  }
}

This produced a fantastic, context-aware prompt showing my current directory and active model, which is a great user experience.

Request

Could you please add official documentation for the statusline feature?

Ideally, the documentation would cover:

  • Purpose and Scope: A high-level explanation of what the statusline feature is for.
  • Configuration: The structure of the statusLine object in settings.json.
  • Input Schema: The full JSON schema of the data that is piped to the command. Knowing all available fields is crucial for customization.
  • Examples: A few examples ranging from a simple static prompt to a more advanced, dynamic one like the one above.
  • Feature Status: Clarification on whether this feature is considered stable, beta, or experimental.

This feature is a fantastic addition for power users who want to customize their CLI experience. Documenting it would allow the wider community to benefit from it.

Thank you for building such a great tool

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗