DOCSEARCHbyAlgolia
Submit Docs

cc-statusline

repository·main·Indexed 20 days ago

https://github.com/chongdashu/cc-statusline

An interactive CLI tool for generating custom, high-performance statuslines for Claude Code. It provides real-time visibility into directory paths, git branches, model information, context usage, costs, and session timers. The tool includes an interactive initialization process, a preview mode with performance metrics, and support for multiple visual themes (minimal, detailed, compact). Advanced features like token statistics and context window progress bars require the installation of jq.

Tokens
7.7K
Snippets
31
Records
39
Agent score
70%

What's inside cc-statusline

  1. Install jq for advanced statusline features

    main

    While cc-statusline works with a basic fallback parser, installing jq (a JSON processor) is strongly recommended to enable advanced features like context window progress bars, token statistics, and session timers.

    macOS

    brew install jq

    Linux

    Ubuntu/Debian:

    sudo apt-get install jq

    CentOS/RHEL/Fedora:

    sudo yum install jq

    Arch Linux:

    sudo pacman -S jq

    Windows

    Using Package Managers:

    # Chocolatey
choco install jq

# Scoop
scoop install jq

# Winget
winget install jqlang.jq

    Manual Installation:

    1. Download the appropriate version (jq-windows-amd64.exe or jq-windows-i386.exe) from the jq releases page.
    2. Rename the file to jq.exe.
    3. Place it in C:\Windows\System32\ or add it to your PATH.
    4. Verify with jq --version (requires 1.6 or higher).
    # Example for Ubuntu/Debian
sudo apt-get install jq

  2. Quick Start with cc-statusline

    main

    To quickly set up a custom statusline for Claude Code, run the initialization command. You will be prompted with a few questions to configure your preferences. After completing the setup, restart Claude Code to see the changes.

    npx @chongdashu/cc-statusline@latest init

  3. Update Claude Code `settings.json` for statusline

    main

    The installation process modifies the settings.json file located within the .claude directory to enable the statusline.

    Configuration Schema

    The statusLine object added to settings.json follows this structure:

    "statusLine": {
  "type": "command",
  "command": "<path_to_script>",
  "padding": 0
}

    Platform-Specific Command Paths

    The installer automatically determines the correct command path based on the operating system:

    • Windows: Uses bash <path_to_script>.
    • Unix/Linux/macOS: Uses the direct path (e.g., ~/.claude/statusline.sh for global or .claude/statusline.sh for local).

    Conflict Handling

    If settings.json already contains a statusLine.command that does not include statusline.sh, the installer will prompt the user to confirm if they wish to replace the existing configuration.

  4. How usage and cost statistics are extracted

    main

    The usage feature extracts data from Claude Code's native input. It uses two different methods depending on the environment:

    1. JQ Method (Preferred): If HAS_JQ is set to 1, the system uses jq to parse the .cost and .context_window fields from the input JSON.
    2. Bash Fallback: If jq is unavailable, the system uses grep and sed to parse the raw text for total_cost_usd, total_duration_ms, total_input_tokens, and total_output_tokens.

    Calculated Metrics:

    • Burn Rate ($/hour): Calculated from total_cost_usd and total_duration_ms using awk.
    • Tokens Per Minute (tpm): Calculated from total tokens and duration if showTokens and showBurnRate are enabled.
    • Session Progress: If showSession is enabled, the system attempts to run the ccusage command (with a 5s timeout) to fetch session reset times and calculate the percentage of the session elapsed.

  5. Manual Claude Code configuration for cc-statusline

    main

    If the automatic installation fails to update your Claude Code settings, you can manually configure the statusline by adding the following object to your .claude/settings.json file:

    {
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh",
    "padding": 0
  }
}

  6. Configure features in StatuslineConfig

    main

    When generating a Bash statusline, the StatuslineConfig object determines which features are included in the script's logic and display.

    Supported feature keys in config.features include:

    • directory: Displays the current working directory.
    • git: Displays the current Git branch.
    • model: Displays the AI model name and version.
    • context: Displays the context window usage/remaining percentage.
    • usage, session, tokens, burnrate: These control the display of cost and token analytics. Note that for usage features to work, ccusageIntegration must also be enabled in the config.

    Other configuration properties affecting the output:

    • theme: Can be set to 'minimal', 'compact', etc. This affects visual density and progress bar rendering.
    • colors: Boolean determining if ANSI color codes are used.
    • logging: Boolean to enable logging of extracted data to a statusline.log file in the script's directory.

  7. Install `jq` for enhanced statusline functionality

    main

    The cc-statusline tool uses jq to process data. While the statusline will function without it, installing jq is strongly recommended to enable:

    • Context remaining percentage display
    • Token statistics
    • Improved performance

    Installation Commands by Platform:

    macOS (Darwin):

    • Homebrew: brew install jq
    • MacPorts: sudo port install jq

    Linux:

    • Ubuntu/Debian: sudo apt-get install jq
    • CentOS/RHEL/Fedora: sudo yum install jq
    • Arch Linux: sudo pacman -S jq

    Windows:

    • Chocolatey: choco install jq
    • Scoop: scoop install jq

  8. Initialize and install the statusline via `init` command

    main

    The init command starts an interactive configuration process to generate and install a custom statusline for Claude Code.

    Workflow:

    1. Dependency Check: The tool checks for jq. If jq is missing, certain features like context percentage and token statistics will be unavailable or slower. You can choose to continue without it or install it via your platform's package manager.
    2. Configuration: An interactive prompt (collectConfiguration) collects your preferences.
    3. Validation: The configuration is validated against internal rules.
    4. Generation: A Bash script (statusline.sh) is generated based on your settings.
    5. Preview: A visual preview of the statusline is displayed in the terminal.
    6. Installation: The script is saved to a specific path and integrated into Claude Code's settings.

    Installation Locations:

    • Global: If configured for global installation, the script is placed in ~/.claude/statusline.sh.
    • Project: Otherwise, it is placed in ./.claude/statusline.sh.

    Manual Configuration: If automatic settings updates fail (SETTINGS_UPDATE_FAILED), you must manually add the following to your settings.json (located in ~/.claude/ for global or .claude/ for project):

    {
  "statusLine": {
    "type": "command",
    "command": "/path/to/your/statusline.sh",
    "padding": 0
  }
}
    # Example usage (assuming the CLI is installed and available)
cc-statusline init

  9. Troubleshoot cc-statusline issues

    main

    Statusline not appearing

    1. Restart Claude Code: The changes require a fresh session.
    2. Verify settings: Ensure .claude/settings.json contains the statusLine configuration.
    3. Check permissions: Ensure the script is executable: chmod +x .claude/statusline.sh.

    Missing features (Context, Tokens, Timer)

    • Install jq: Most advanced features require jq to be installed on your system.
    • ccusage setup: Usage tracking works via npx ccusage@latest.
    • Git info missing: Ensure git is installed.

    Performance issues

    • Test performance: Run cc-statusline preview .claude/statusline.sh to check execution time.
    • Optimize: Disable heavy features if execution exceeds 500ms.
    • Disable ccusage: Remove usage tracking if it causes lag.

  10. Preview your statusline output

    main

    Before applying changes and restarting Claude Code, you can preview how your statusline will look using mock data. This is useful for testing configuration changes or verifying performance.

    cc-statusline preview .claude/statusline.sh

    The preview command:

    1. Loads your generated statusline script.
    2. Runs it with realistic mock data.
    3. Displays the expected output.
    4. Reports performance metrics.

  11. Requirements for Session and Progress Bar features

    main

    To use the showSession or showProgressBar features within the UsageFeature configuration, the following must be true:

    1. The ccusage command must be available in the system's PATH.
    2. jq must be installed (as HAS_JQ must be 1).
    3. The system should ideally have timeout or gtimeout installed to prevent the ccusage command from hanging the status line.

  12. Custom Installation Options

    main

    You can control where and how the statusline is installed using CLI flags during the init process.

    • Generate to a custom location: Use --output to specify a custom path for the generated script.
    • Skip auto-installation: Use --no-install if you want to manually integrate the script into Claude Code.
    • Global Installation: To use the statusline across all projects, install the package globally via npm.
    # Generate to custom location
cc-statusline init --output ./my-statusline.sh

# Skip auto-installation (manual setup)
cc-statusline init --no-install

# Global installation
npm install -g @chongdashu/cc-statusline
    cc-statusline init --output ./my-statusline.sh