ccstatusline

Implements a pluggable widget architecture where each status line element (model info, git status, token usage, session duration) is a discrete, composable component that processes JSON input from Claude Code CLI and renders formatted output. Widgets are registered in a central registry, executed sequentially, and their outputs are combined with configurable separators (including Powerline arrow glyphs) to produce multi-segment status lines. The system supports up to 3 independent status lines with different widget configurations per line.

Provides a React/Ink-based terminal UI that allows users to interactively select widgets, configure their properties, choose color themes, and preview the resulting status line in real-time without restarting Claude Code. The TUI reads the current configuration, renders interactive screens for widget selection and property editing, and persists changes back to ~/.claude/settings.json. Configuration changes are immediately reflected in the preview pane, enabling iterative customization.

Manages configuration persistence by reading from and writing to ~/.claude/settings.json, the standard Claude Code configuration file. The system validates configuration against a schema, handles version migrations, and automatically registers the ccstatusline status line hook in Claude Code's settings. Configuration changes made in the TUI are immediately persisted, and Claude Code reads the updated configuration on the next execution. Supports configuration backup and rollback.

Processes JSON input from Claude Code CLI via stdin, parsing the payload and validating it against a predefined schema to ensure required fields are present. The system handles malformed JSON gracefully, providing error messages without crashing. Supports multiple JSON payload formats (different Claude Code versions) through schema versioning. Input validation ensures that widgets receive correctly-typed data and can fail fast on invalid input.

Provides a framework for developing custom widgets by implementing a standard widget interface (input/output types, render method, configuration schema). Widgets are written in TypeScript, compiled to JavaScript, and registered in the widget registry. The framework provides utilities for common tasks (color formatting, text truncation, number formatting) and handles widget lifecycle (initialization, configuration validation, rendering). Custom widgets can be packaged as npm modules or included inline in the configuration.

Integrates with local git repositories to extract and display real-time metrics including current branch name, commit status (staged/unstaged changes), ahead/behind commit counts relative to upstream, and repository state (clean/dirty). The git widget executes git commands (git rev-parse, git status, git rev-list) to gather this data and formats it with customizable separators and color coding based on repository state. Supports both short and long format output.

Extracts and formats token usage metrics (input tokens, output tokens, total tokens) and model information (model name, version) from JSON data passed by Claude Code CLI via stdin. The widget parses the JSON payload, calculates token statistics, and formats them with optional unit suffixes (K for thousands) and color coding based on token thresholds. Supports displaying cumulative session tokens or per-request token counts.

Calculates and displays elapsed time since the Claude Code session started, parsing session start timestamps from JSON input and formatting the duration in human-readable units (seconds, minutes, hours, days). The widget supports multiple format options including compact (1h 23m), verbose (1 hour 23 minutes), and numeric (1:23:45) formats. Updates in real-time as the session progresses without requiring external time sources.

Parses JSONL (JSON Lines) transcript files from Claude Code sessions to extract and display aggregate metrics such as total messages, conversation turns, message length statistics, and custom metrics derived from transcript analysis. The widget reads JSONL files line-by-line, parses each JSON object, and computes statistics without loading the entire file into memory. Supports filtering transcripts by date range or message type.

Executes arbitrary shell commands and captures their output to display custom metrics in the status line. The widget spawns a subprocess, runs the configured command, captures stdout, and formats the output with optional text transformation (trimming, truncation, case conversion). Supports environment variable substitution in command strings and timeout handling for long-running commands. Output is cached within a single render cycle to avoid redundant executions.

Integrates Powerline font glyphs (Unicode arrows and separators) for visually distinctive status line segments, with automatic fallback to ASCII separators for terminals that don't support Unicode. The rendering system detects terminal capabilities and selects appropriate separator characters (e.g., U+E0B0 powerline right arrow vs '>' for ASCII). Supports both left-to-right and right-to-left separator styles with configurable colors and background styling.

Supports configuring up to 3 independent status lines, each with its own widget composition, layout, and styling. The rendering system processes each configured line separately, allowing different widgets and separators per line. Lines can be positioned at different locations in the terminal (top, middle, bottom) and styled independently. Configuration is stored as an array of line configurations, each specifying widgets, separators, and formatting options.

Provides a theme system with predefined color schemes (dark, light, solarized, etc.) that define colors for widgets, separators, and status indicators. Themes are stored as JSON objects mapping semantic color names (e.g., 'success', 'warning', 'error') to ANSI color codes or 24-bit RGB values. Users can select a predefined theme or create custom themes by overriding color values. The rendering system applies theme colors to all widgets and separators during output generation.