DOCSEARCHbyAlgolia
Submit Docs

ccstatusline

repository·main·Indexed 9 days ago

https://github.com/sirmalloc/ccstatusline

A customizable status line formatter for the Claude Code CLI that provides visual terminal metrics including model info, git status, token usage, and session costs. Features an interactive TUI for configuration, Powerline and Flex modes for layout, and support for custom gradients and widget styling. Version 2.2.27 supports importing and exporting TUI configurations via JSON.

Tokens
16.9K
Snippets
57
Records
95
Agent score
95%

What's inside ccstatusline

  1. Overview of ccstatusline

    main
    ccstatusline is a highly customizable status line formatter designed specifically for the Claude Code CLI. It allows developers to display real-time metrics directly in their terminal, including model information, Git branch status, token usage, and other relevant development metrics.

  2. Customize widget colors and gradients

    main

    The color editor supports several advanced styling options:

    • Gradients: You can apply per-widget or whole-line foreground gradients. Use named presets or custom hex stops.
      • To edit widget gradients: Press g on the Edit Colors screen.
      • To edit global line gradients: Press g in Global Overrides for 'Override FG Color'.
    • Dim Styling: You can dim an entire widget or only the text within parentheses. Use the reset or clear-all actions to revert dim states.

  4. Import and export TUI configurations

    main
    As of v2.2.27, you can export your current TUI configuration to a JSON file. You can also import configurations, which allows you to validate and preview the import before applying it. When importing, you can choose to replace all existing settings or merge only the supplied fields (preserving local installation metadata). The imported result is left unsaved for your review before final application.

  5. Use Gradient Colors in Status Line

    main

    Gradients use OKLab interpolation for smooth blends. They can be applied per-widget (self-contained sweep) or as a whole-line override (continuous sweep across all characters).

    Gradient values must be prefixed with gradient: and follow one of these formats:

    1. Named preset: gradient:atlas (Presets: atlas, cristal, teen, mind, morning, vice, passion, fruit, instagram, retro, summer, rainbow, pastel).
    2. Dash stops: gradient:RRGGBB-RRGGBB[-RRGGBB...] (Hex stops).
    3. Comma stops: gradient:hex:RRGGBB,#RRGGBB,RRGGBB (Uses hex: prefix).

    Note on Rendering:

    • In Powerline mode, global foreground gradients color widget text, but separators/caps maintain standard contrast rules.
    • In 256-color mode, per-widget gradients collapse to their first stop.
    • At Basic/No Color levels, gradients render as plain text.
    // Named preset
gradient:atlas

// Dash stops
gradient:FF0000-00FF00

// Comma stops
gradient:hex:FF0000,#00FF00,0000FF

  6. Use Powerline mode and Flex mode

    main

    Powerline mode enables status lines with arrow separators and customizable caps.

    • Powerline Flex Mode: Allows flex separators to work within Powerline mode, enabling the status line to right-align content or absorb available width.
    • Selective Alignment: You can press x in the line editor to allow a specific widget and its line to maintain natural widths while earlier Powerline columns remain auto-aligned.
    • Auto-Alignment: In Powerline Setup, you can toggle auto-alignment (a) to align widgets across multiple status lines for a clean, columnar layout.

  7. Understand Raw Value Mode

    main

    Several widgets support a "raw value" mode, which strips the descriptive label to save space and provide a cleaner look. This is often used in conjunction with Minimalist Mode.

    Examples:

    • Model: Model: Claude 3.5 Sonnet $\rightarrow$ Claude 3.5 Sonnet
    • Session: Session: 2hr 15m $\rightarrow$ 2hr 15m
    • Block: Block: 3hr 45m $\rightarrow$ 3hr 45m
    • Context: Ctx: 18.6k $\rightarrow$ 18.6k

  8. How Powerline Auto-Alignment works

    main

    When Powerline Setup is enabled, widgets can be aligned into shared columns across multiple status lines.

    • Toggle Alignment: Press a in the Powerline setup to toggle Align Widgets.
    • Exclude from Alignment: If auto-alignment causes a naturally wide value to stretch too far, select that widget in the line editor and press x (exclude align). This allows the selected widget and all subsequent widgets on that line to maintain their natural widths while keeping earlier columns aligned.

  9. Run ccstatusline in different modes

    main

    Depending on your needs, ccstatusline can be run in three distinct modes:

    1. Interactive mode (TUI): Launches the interactive terminal user interface when no stdin is provided. Use this for manual configuration and viewing.
    2. Piped mode (renderer): Parses Claude Code status JSON from stdin and prints one or more formatted lines. This is used for programmatic rendering.
    3. Version mode: Prints the installed package version and exits when the --version flag is passed.

    Usage Examples

    # Interactive TUI
bun run start

# Piped mode with example payload
bun run example

# Print the installed package version
ccstatusline --version
    # Interactive TUI
bun run start

# Piped mode with example payload
bun run example

# Print the installed package version
ccstatusline --version

  10. Use ccstatusline development commands

    main

    Use the following commands to run, test, and build the project using bun:

    CommandDescription
    bun run startRun in TUI mode
    bun run exampleTest piped mode with an example payload
    bun testRun tests
    bun run lintRun typecheck + eslint checks (no file modification)
    bun run lint:fixApply ESLint auto-fixes
    bun run buildBuild for distribution
    bun run docsGenerate TypeDoc documentation
    bun run start
bun run example
bun test
bun run lint
bun run lint:fix
bun run build
bun run docs

  11. Customize Widget Styling

    main

    Individual widgets can be styled independently of global settings. Use the color editor to adjust:

    • Foreground/Background Color: Use ← / → to cycle colors.
    • Switch Mode: Press f to switch between editing foreground and background.
    • Bold: Press b to toggle bold.
    • Dimming: Press d to cycle through: off → whole widget → parenthesized text only → off.
    • Resetting: Press r to reset styling on the selected widget, or c to clear styling on every widget in the line.
    Widget Styling Controls:
← / → : Cycle colors
f : Switch FG/BG editing
b : Toggle bold
d : Cycle dimming modes
r : Reset selected widget
c : Clear all widget styling

  12. Setup the ccstatusline development environment

    main

    To develop on ccstatusline, you need Bun (v1.0+) and Git installed. Node.js 14+ is optional but recommended for running the built binary or publishing to npm.

    Follow these steps to clone and prepare the repository:

    # Clone the repository
git clone https://github.com/sirmalloc/ccstatusline.git
cd ccstatusline

# Install dependencies
bun install
    git clone https://github.com/sirmalloc/ccstatusline.git
cd ccstatusline

bun install