# Technical Documentation: sirmalloc/ccstatusline > โ„น๏ธ **Provenance:** Multi-Tier Ingestion ยท [CodeWiki Reference](https://codewiki.google/github.com/sirmalloc/ccstatusline) ### Overview (`README.md`) 
              _        _             _ _            
  ___ ___ ___| |_ __ _| |_ _   _ ___| (_)_ __   ___ 
 / __/ __/ __| __/ _` | __| | | / __| | | '_ \ / _ \
| (_| (__\__ \ || (_| | |_| |_| \__ \ | | | | |  __/
 \___\___|___/\__\__,_|\__|\__,_|___/_|_|_| |_|\___|
# ccstatusline **๐ŸŽจ A highly customizable status line formatter for Claude Code CLI** *Display model info, git branch, token usage, and other metrics in your terminal* [](https://www.npmjs.com/package/ccstatusline) [](https://www.npmjs.com/package/ccstatusline) [](https://github.com/sirmalloc/ccstatusline/blob/main/LICENSE) [](https://nodejs.org) [](https://packagephobia.com/result?p=ccstatusline) [](https://github.com/sirmalloc/ccstatusline/graphs/commit-activity) [](https://github.com/hesreallyhim/awesome-claude-code) [](https://claudelog.com/)

## ๐Ÿ“š Table of Contents - [Recent Updates](#-recent-updates) - [Features](#-features) - [Localizations](#-localizations) - [Quick Start](#-quick-start) - [Windows Support](docs/WINDOWS.md) - [Usage](docs/USAGE.md) - [Development](docs/DEVELOPMENT.md) - [Contributing](#-contributing) - [License](#-license) - [Related Projects](#-related-projects)
## ๐Ÿ†• Recent Updates ### v2.2.32 - Safer imports, proxy handling, and rendering fixes - **๐Ÿ“ฅ Review imported commands** - Config imports show new shell commands in full and require confirmation with Cancel selected by default; control characters are displayed as escaped text. - **๐Ÿ”’ Private settings stay private** - Saves preserve restrictive settings-file permissions, Claude settings backups inherit the source permissions, and installation stops rather than overwriting unreadable Claude settings. - **๐ŸŒ Proxy exclusions and deadlines** - Usage and Claude Status requests honor `NO_PROXY` and `no_proxy` and have total five-second deadlines; JJ commands also time out after five seconds. - **โณ Accurate cache timer state** - Interrupts and local slash commands such as `/cost` no longer leave Cache Timer reporting `HOT`. - **โšก Faster Git and text rendering** - Git widgets skip unnecessary calls outside repositories and keep separate caches per working directory; text-width calculations reuse Unicode measurements, and Git file/URL parsing avoids quadratic slowdowns. - **๐Ÿ“ Reliable styled-text truncation** - Width limits remain correct when ANSI styling or hyperlinks split an emoji or another display cluster. - **๐Ÿ›ก๏ธ Command and file handling** - Update versions are validated before installation, fonts download into private temporary folders, branch/host names stay literal CLI arguments, and Skills logs reject unsafe session IDs. - **๐Ÿ”„ Reliable usage backoff** - Successful usage requests preserve rate-limit backoff written by concurrent renders. ### v2.2.31 - Cost tracking, customization, and broad reliability improvements Across the updates since the September 3 release, 64 PRs have been incorporated, plus additional security fixes and test isolation. - **๐Ÿฉน Miscellaneous bug fixes** - 29 dedicated bug-fix PRs since September 3 cover usage/account caching, transcript reading, Git/JJ and directory displays, Unicode truncation, Powerline colors and layout, keyboard controls, settings recovery, hooks, and installation/update flows. - **๐Ÿ”’ Security fixes** - Three additional fixes restrict repository-controlled Git commands, resolve Windows helper executables from PATH, and filter terminal control sequences while preserving colors and hyperlinks. - **๐Ÿ’ฐ Session Cost Rate** - Track session cost per hour of active API time or total session time, with a one-minute minimum before showing a rate. - **๐Ÿ“… Extra Usage Daily Budget** - Spread the remaining monthly spending limit over the remaining UTC days, with an option to skip future weekend days. - **๐Ÿท๏ธ Editable labels** - Press `e` to customize text labels. - **โšก Faster rendering** - Piped status lines skip loading the interactive TUI, reducing startup work on every repaint. - **๐Ÿงฐ Maintenance** - Shared widget and editor implementations, broader regression coverage, more reliable tests, dependency updates, and CI actions pinned to commit SHAs. ### v2.2.29 - v2.2.30 - Faster rendering, command caching, and reliable usage - **โšก Faster terminal width detection** - Linux can probe the terminal directly without subprocesses, portable fallbacks skip shell wrappers, and configurable caching reuses failed width probes across renders while detected widths refresh on the next render. - **๐Ÿ”ง Custom command caching and timeouts** - Opt into output caching for up to 60 seconds from Configure Status Line, and enforce command timeouts even when descendants retain output pipes. - **๐Ÿ”ฃ More customizable Git/JJ symbols** - Press `g` to edit insertion/deletion signs, Git clean/dirty markers, and the JJ Revision prefix, including empty glyphs for compact layouts. - **๐Ÿ™ˆ Hide reset-timer placeholders** - Block Reset Timer and Weekly Reset Timer can hide loading and error output through `h`; use `f` for 12/24-hour format and `o` for weekly hours-only display. - **๐Ÿ‘ค Reliable usage account selection** - macOS usage lookup respects the active config profile's Keychain credentials, and access-token refreshes preserve cached usage when the refresh token is unchanged. - **๐Ÿ“Š Unused model quotas show zero** - Weekly model usage widgets recognize an explicit 0% quota even before the API supplies a reset timestamp. - **โ†”๏ธ Full-width layouts by default** - New configurations and settings without an explicit flex mode now use Full width always. - **โฑ๏ธ Bounded Git commands** - Cached Git commands have a five-second timeout so a stalled Git invocation cannot block the status line indefinitely. ### v2.2.28 - v2.2.29 - Service health, flexible formatting, and resilient rendering - **๐Ÿฉบ Claude service health** - Added a `Claude Status` widget with live severity, a cached 48-hour incident-history strip, stale-data fallback, and graceful `?` output when status data is unavailable. - **๐Ÿ™ˆ Unified conditional hiding** - Numeric, Git, JJ, usage, cache, and other widgets now share an `h` checklist for supported hide conditions, with automatic migration of existing settings and optional merge-target hiding for decorative text or symbols. - **๐Ÿ”ข Configurable number formatting** - Numeric widgets can use precise, compact, or whole-number styles per widget or globally by token, speed, percent, memory, and cost type, while advanced configs can set decimal precision explicitly. - **๐Ÿ“œ Faster, reliable large-session rendering** - Transcript-backed token, duration, speed, compaction, effort, and session-name metrics now stream JSONL records through one shared scan instead of loading an entire transcript into a single string, while no-active-block results are briefly cached to avoid repeated full-history scans. - **โš ๏ธ Git conflict display controls** - Git Conflicts can hide when the count is zero or show either `โš 0` or a customizable clean glyph when the tree is conflict-free. - **๐Ÿฉน Self-healing usage locks** - Usage widgets ignore impossible fetch-lock deadlines more than 24 hours ahead, allowing poisoned locks caused by clock jumps or old test artifacts to recover on the next render. - **๐Ÿงน Bounded Git cache cleanup** - Failed persistent Git-cache writes clean up their temporary file and reuse one stable fallback name, preventing Windows file locks from leaking thousands of orphaned temp files. - **๐Ÿ“Š Consistent timer bars** - Block Timer, Block Reset Timer, and Weekly Reset Timer now round progress-bar fill to the nearest cell, matching the other progress widgets. ### v2.2.27 - Portable configuration import and export - **๐Ÿ“ฆ Config import/export** - Export the current TUI configuration to JSON, validate and preview imports, then replace all settings or merge only supplied fields while preserving local installation metadata and leaving the result unsaved for review. ### v2.2.25 - v2.2.26 - Fable usage, migrated usage API support, compaction accuracy, and rendering reliability - **๐Ÿช„ Weekly Fable usage** - Added a `Weekly Fable Usage` widget with percentage, progress-bar, remaining-mode, and time-cursor controls. - **๐Ÿ“Š Reshaped usage API support** - Session and all-model weekly usage can fall back to the newer `limits[]` response, while Sonnet, Opus, and Fable weekly widgets read authoritative `weekly_scoped` entries so migrated accounts do not show stale or frozen values. - **๐Ÿง  Correct post-compaction context** - Context length and percentage widgets reset immediately from `compact_boundary.postTokens` after `/compact`, then switch to the first new turn instead of retaining the pre-compaction size. - **๐Ÿงน Reliable hidden-widget separators** - Manual separators now look past widgets that render empty, preserve the intended visible boundary, and inherit colors from the actual preceding visible widget. - **โšก Non-blocking Git PR/CI refreshes** - Git PR and CI widgets render from a versioned disk cache while stale data refreshes in the background, preventing slow `gh` calls from blocking the status line. ### v2.2.22 - v2.2.24 - Powerline flex mode, cache/CI/sandbox visibility, layout controls, composable metrics, and safer config - **โณ Prompt cache timer** - Added a `Cache Timer` widget with live `HOT` state, TTL countdown, configurable 5-minute/1-hour windows, and customizable state glyphs. - **โœ… GitHub CI status** - Added a `Git CI Status` widget that summarizes failing, pending, and successful checks for the current branch's pull request. - **๐Ÿ”’ Sandbox status** - Added a `Sandbox Status` widget with glyph, text, and Nerd Font formats that follows Claude Code's layered sandbox setting on each refresh. - **โ†”๏ธ One-sided default padding** - Default widget padding can now apply to both sides, the left only, or the right only in standard and Powerline layouts. - **โšก Powerline flex mode** - Flex separators now work in Powerline mode, letting Powerline status lines right-align content or absorb available width. - **๐ŸŒ— Per-widget dim styling** - The color editor can dim an entire widget or only parenthesized text, with reset and clear-all actions covering dim state. - **๐Ÿงฏ Safer settings recovery** - Invalid `settings.json` files are left untouched, defaults render in memory, and the status line shows an invalid-config warning. - **๐Ÿงญ Selective Powerline alignment** - Press `x` in the line editor to let a widget and the rest of its line keep their natural widths while earlier Powerline columns stay auto-aligned. - **๐Ÿ“ Git widget width limits** - `Git Branch` and `Git Root Dir` can cap their visible width with ellipsis-safe truncation while preserving hyperlink targets. - **๐Ÿ”ฃ Current directory glyphs** - `Current Working Dir` can prepend an optional custom glyph, including in raw-value mode. - **๐Ÿง  Configurable context fallback** - `CCSTATUSLINE_CONTEXT_SIZE_FALLBACK` overrides the default 200k last-resort context window when Claude Code and the model name do not report one. - **๐Ÿงฉ Composable compaction metrics** - `Compaction Counter` can render count, auto, manual, unknown, or reclaimed-token values independently for custom layouts. - **๐Ÿท๏ธ CLI version flag** - `ccstatusline --version` now prints the installed package version and exits. - **๐Ÿ›ก๏ธ Guarded invalid-config saves** - The TUI warns when it loaded defaults for an invalid settings file and requires confirmation before replacing that file. - **๐Ÿ”„ Usage display and cache fixes** - Used/remaining direction now works in every percentage mode, account switches invalidate cached usage, and fetch locks no longer cause repeated requests or stale timeout output. - **โฑ๏ธ Calmer reset timer startup** - Reset timers show labeled loading placeholders instead of transient rate-limit errors while Claude Code's embedded usage-window data is still arriving. - **๐Ÿ”‡ Quieter install detection** - Best-effort npm and Bun probes no longer leak expected package-manager errors into the TUI. ### v2.2.21 - Cache widgets, compaction details, extra usage currency, and package fixes - **๐Ÿ”ฃ Custom widget glyphs** - Git and JJ symbol widgets can override or suppress their built-in glyphs from the TUI. - **๐Ÿ” Compaction counter details** - `Compaction Counter` now counts explicit `compact_boundary` markers and can optionally show trigger splits plus tokens reclaimed. - **๐Ÿ’ธ Extra usage improvements** - Added `Extra Usage Used` and formats extra usage amounts with the billing currency reported by the usage API. - **๐Ÿ“ Custom command width context** - `Custom Command` widgets receive `terminal_width` in stdin JSON when ccstatusline can detect the terminal width. - **๐Ÿง  Prompt cache widgets** - Added `Cache Hit Rate`, `Cache Read`, and `Cache Write` widgets with turn/session scopes and hide-when-empty behavior. - **๐Ÿ”ข Token rounding fix** - Token counts from `999950` through `999999` now render as `1.0M` instead of `1000.0k`. ### v2.2.20 - Gradients, token accuracy, usage reliability, and Git PR/MR fixes - **๐ŸŒˆ Gradient colors** - Added per-widget and whole-line foreground gradients with named presets, custom hex stops, TUI picker support, and Powerline-aware rendering. Press `g` on the Edit Colors screen for widget gradients, or press `g` for Override FG Color in Global Overrides for a line-wide gradient. - **๐ŸŽฏ More accurate token counts** - `Tokens Input` and `Tokens Output` now prefer cumulative transcript metrics before falling back to context-window totals. - **๐Ÿ’ธ Extra usage no-limit fix** - Extra usage widgets no longer get stuck on `[Timeout]` for accounts with overage enabled but no monthly limit configured. - **๐Ÿ” Compaction glitch filtering** - `Compaction Counter` ignores transient below-1% context readings so incomplete status frames do not create false compaction counts. - **๐Ÿ”€ SSH alias Git PR/MR detection** - Git PR/MR detection resolves SSH host aliases while preserving canonical GitHub and GitLab hosts for CLI selection and fallback repo links. - **๐Ÿงช Usage test cache isolation** - Usage-fetch test probes now isolate `HOME`, `USERPROFILE`, `CLAUDE_CONFIG_DIR`, and proxy variables so local tests cannot touch the real ccstatusline cache. - **๐Ÿ“ฆ Dependency refresh** - Refreshed React/React DOM and Bun lockfile development-tooling resolutions for the release. ### v2.2.14 - v2.2.19 - Version pinning, npm provenance, usage overage widgets, and Git lock avoidance - **๐Ÿ“Œ Version pinning support** - Added support for pinned global installs so Claude Code can keep running a specific ccstatusline version. - **๐Ÿ” npm provenance attestations** - Published packages now use trusted publishing provenance so users can verify where releases were built while avoiding long-lived npm publish tokens. - **๐Ÿ”„ Moving from auto-update installs** - If you currently use an auto-updating install, use the TUI uninstall option first, then reinstall to go through the version pinning flow. Your ccstatusline settings are preserved when uninstalling. - **๐Ÿ’ธ Extra usage widgets** - Added Extra Usage Utilization and Extra Usage Remaining widgets for monthly pay-as-you-go overage limits, with null rate-limit buckets handled as zero usage. - **๐Ÿ”’ Git lock avoidance** - Git helpers now pass `--no-optional-locks` so background status checks avoid creating `index.lock` races. - **๐Ÿงฑ Older Git compatibility** - Git widgets avoid newer command forms so repository status works on older Git installations. - **โšก Persistent Git cache** - Git command output is cached under `~/.cache/ccstatusline/git-cache` with configurable TTL and `.git/HEAD`/`.git/index` mtime checks to reduce repeated subprocess work. - **๐Ÿงญ Install flow polish** - Pinned global install is now the default install option, with clearer wording for install and migration flows. - **๐ŸชŸ Hidden helper processes** - Runtime child processes set `windowsHide` so helper commands do not open extra windows on Windows. - **๐Ÿ“ Terminal width override** - `CCSTATUSLINE_WIDTH` can provide an explicit terminal width when automatic probing is unavailable. ### v2.2.13 - Weekly model usage, voice status, hooks, and docs - **๐Ÿ“Š Weekly Sonnet/Opus usage widgets** - Added separate weekly usage widgets for Sonnet and Opus API buckets, matching Claude Code's `/usage` model split. - **๐ŸŽค Voice Status widget** - Added a widget that shows whether Claude Code voice input is enabled, with icon, text, word, and optional Nerd Font display modes. - **๐Ÿ“‰ Timer short bars** - Block Timer, Block Reset Timer, and Weekly Reset Timer now support compact short-bar progress displays. - **๐Ÿ”• Quieter hook output** - Hook handling now suppresses no-op JSON output so non-status updates stay silent.
Older updates (v2.2.12 and earlier) ### v2.2.9 - v2.2.12 - GitLab support, reset timers, context, compaction, and git widgets - **๐ŸฆŠ GitLab PR/MR support** - `Git Branch` and `Git PR/MR` now support GitHub, GitLab, and compatible self-hosted remotes, using `gh` or `glab` as appropriate. - **๐Ÿ”„ Status line refresh interval** - Installed configs can set Claude Code's `statusLine.refreshInterval` from the TUI when Claude Code >=2.1.97 supports it. - **๐Ÿงญ Wrap-around TUI navigation** - Menu/list navigation and move/reorder modes now wrap at the first and last items. - **๐Ÿ“‹ Clone widget shortcut** - Press `k` in the item editor to duplicate the selected widget, with fresh Powerline background color for cloned Powerline items. - **๐Ÿ“Š Short bar display modes** - Context percentage, Context Bar, Session Usage, Weekly Usage, Block Timer, and reset timer widgets can use compact bar variants. - **โฑ๏ธ Usage time cursor** - Session Usage and Weekly Usage progress bars can show the elapsed time position within the current usage window. - **๐Ÿ•’ Reset timer timestamps** - Block and Weekly Reset Timer widgets can show exact reset timestamps with compact formatting, 12/24-hour display, IANA time zones, and locale selection. - **๐ŸชŸ Context Window widget** - Added a `Context Window` widget for total model window size, keeping `Context Length` focused on current context usage. - **๐Ÿ” Compaction Counter widget** - Added a `Compaction Counter` widget that tracks session context compactions, with icon/text/number formats, optional Nerd Font icon, and hide-when-zero behavior. - **๐Ÿงฎ Git file status widgets** - Added `Git Staged Files`, `Git Unstaged Files`, `Git Untracked Files`, and `Git Clean Status` for file counts and clean/dirty state. - **๐Ÿท๏ธ Clear context percentage labels** - `Context %` and `Context % (usable)` now label rendered values as used or left when toggling used/remaining mode. - **โšก More Powerline caps** - The Powerline separator editor now supports more than three start/end caps. - **๐Ÿง  Thinking Effort updates** - Added `xhigh`, show `default` when no effort is set, mark unknown future effort levels with `?`, and track live status JSON plus `/effort` command changes. Claude Code reports Ultracode as `xhigh` in status line data. - **๐Ÿงฎ More accurate token counts** - Streaming duplicate JSONL entries are deduped so token widgets do not overcount live Claude Code output. - **๐Ÿท๏ธ Cleaner model display** - The Model widget strips trailing context suffixes like `(1M context)`; use `Context Window` when you want the total window size shown. - **๐Ÿงน Cleaner empty-widget separators** - Manual separators now collapse around widgets that render empty, avoiding dangling separators when hide-when-empty widgets disappear. - **๐Ÿงฑ More resilient Git helpers** - Git widgets handle missing or unusual git command output more defensively. ### v2.2.8 - Git widgets, smarter picker search, and minimalist mode - **๐Ÿ”€ New Git PR widget** - Added a `Git PR` widget with clickable PR links plus optional status and title display for the current branch. - **๐Ÿงฐ Major Git widget expansion** - Added `Git Status`, `Git Staged`, `Git Unstaged`, `Git Untracked`, `Git Ahead/Behind`, `Git Conflicts`, `Git SHA`, `Git Origin Owner`, `Git Origin Repo`, `Git Origin Owner/Repo`, `Git Upstream Owner`, `Git Upstream Repo`, `Git Upstream Owner/Repo`, `Git Is Fork`, `Git Worktree Mode`, `Git Worktree Name`, `Git Worktree Branch`, `Git Worktree Original Branch`, and `Custom Symbol`. - **๐Ÿ‘ค Claude Account Email widget** - Added a session widget that reads the signed-in Claude account email from `~/.claude.json` while respecting `CLAUDE_CONFIG_DIR`. - **๐Ÿงผ Global Minimalist Mode** - Added a global toggle in `Global Overrides` that forces widgets into raw-value mode for a cleaner, label-free status line. - **๐Ÿ”Ž Smarter widget picker search** - The add/change widget picker now supports substring, initialism, and fuzzy matching, with ranked results and live match highlighting. - **๐Ÿ“ Better terminal width detection** - Flex separators and right-alignment now work more reliably when ccstatusline is launched through wrapper processes or nested PTYs. - **๐ŸŽจ Powerline theme continuity** - Built-in Powerline themes can now continue colors cleanly across multiple status lines instead of restarting each line. ### v2.2.0 - v2.2.6 - Speed, widgets, links, and reliability updates - **๐Ÿš€ New Token Speed widgets** - Added three widgets: **Input Speed**, **Output Speed**, and **Total Speed**. - Each speed widget supports a configurable window of `0-120` seconds in the widget editor (`w` key). - `0` disables window mode and uses a full-session average speed. - `1-120` calculates recent speed over the selected rolling window. - **๐Ÿงฉ New Skills widget controls (v2.2.1)** - Added configurable Skills modes (last/count/list), optional hide-when-empty behavior, and list-size limiting with most-recent-first ordering. - **๐ŸŒ Usage API proxy support (v2.2.2)** - Usage widgets honor the uppercase `HTTPS_PROXY` environment variable for their direct API call to Anthropic. - **๐Ÿง  New Thinking Effort widget (v2.2.4)** - Added a widget that shows the current Claude Code thinking effort level. - **๐ŸŽ Better macOS usage lookup reliability (v2.2.5)** - Improved reliability when loading usage API tokens on macOS. - **โŒจ๏ธ New Vim Mode widget (v2.2.5)** - Added a widget that shows the current vim mode, with ASCII and optional Nerd Font icon display. - **๐Ÿ”— Git widget link modes (v2.2.6)** - `Git Branch` can render clickable GitHub branch links, and `Git Root Dir` can render clickable IDE links for VS Code and Cursor. - **๐Ÿค Better subagent-aware speed reporting** - Token speed calculations continue to include referenced subagent activity so displayed speeds better reflect actual concurrent work. ### v2.1.0 - v2.1.10 - Usage widgets, links, new git insertions / deletions widgets, and reliability fixes - **๐Ÿงฉ New Usage widgets (v2.1.0)** - Added **Session Usage**, **Weekly Usage**, **Block Reset Timer**, and **Context Bar** widgets. - **๐Ÿ“Š More accurate counts (v2.1.0)** - Usage/context widgets now use new statusline JSON metrics when available for more accurate token and context counts. - **๐ŸชŸ Windows empty file bug fix (v2.1.1)** - Fixed a Windows issue that could create an empty `c:\dev\null` file. - **๐Ÿ”— New Link widget (v2.1.3)** - Added a new **Link** widget with clickable OSC8 rendering, preview parity, and raw mode support. - **โž• New Git Insertions widget (v2.1.4)** - Added a dedicated Git widget that shows only uncommitted insertions (e.g., `+42`). - **โž– New Git Deletions widget (v2.1.4)** - Added a dedicated Git widget that shows only uncommitted deletions (e.g., `-10`). - **๐Ÿง  Context format fallback fix (v2.1.6)** - When `context_window_size` is missing, context widgets now infer 1M models from long-context labels such as `[1m]` and `1M context` in model identifiers. - **โณ Weekly reset timer split (v2.1.7)** - Added a separate `Weekly Reset Timer` widget. - **โš™๏ธ Custom config file flag (v2.1.8)** - Added `--config ` support so ccstatusline can load/save settings from a custom file location. - **๐Ÿ”ฃ Unicode separator hex input upgrade (v2.1.9)** - Powerline separator hex input now supports 4-6 digits (full Unicode code points up to `U+10FFFF`). - **๐ŸŒณ Bare repo worktree detection fix (v2.1.10)** - `Git Worktree` now correctly detects linked worktrees created from bare repositories. ### v2.0.26 - v2.0.29 - Performance, git internals, and workflow improvements - **๐Ÿง  Memory Usage widget (v2.0.29)** - Added a new widget that shows current system memory usage (`Mem: used/total`). - **โšก Block timer cache (v2.0.28)** - Cache block timer metrics to reduce JSONL parsing on every render, with per-config hashed cache files and automatic 5-hour block invalidation. - **๐Ÿงฑ Git widget command refactor (v2.0.28)** - Refactored git widgets to use shared git command helpers and expanded coverage for failure and edge-case tests. - **๐ŸชŸ Windows UTF-8 piped output fix (v2.0.28)** - Sets the Windows UTF-8 code page for piped status line rendering. - **๐Ÿ“ Git Root Dir widget (v2.0.27)** - Added a new Git widget that shows the repository root directory name. - **๐Ÿท๏ธ Session Name widget (v2.0.26)** - Added a new widget that shows the current Claude Code session name from `/rename`. - **๐Ÿ  Current Working Directory home abbreviation (v2.0.26)** - Added a `~` abbreviation option for CWD display in both preview and live rendering. - **๐Ÿง  Context model suffix fix (v2.0.26)** - Context widgets now recognize the `[1m]` suffix across models, not just a single model path. - **๐Ÿงญ Widget picker UX updates (v2.0.26)** - Improved widget discovery/navigation and added clearer, safer clear-line behavior. - **โŒจ๏ธ TUI editor input fix (v2.0.26)** - Prevented shortcut/input leakage into widget editor flows. - **๐Ÿ“„ Repo docs update (v2.0.26)** - Migrated guidance from `CLAUDE.md` to `AGENTS.md` (with symlink compatibility). ### v2.0.16 - Add fish style path abbreviation toggle to Current Working Directory widget ### v2.0.15 - Block Timer calculation fixes - Fix miscalculation in the block timer ### v2.0.14 - Add remaining mode toggle to Context Percentage widgets - **Remaining Mode** - You can now toggle the Context Percentage widgets between usage percentage and remaining percentage when configuring them in the TUI by pressing the 'u' key. ### v2.0.12 - Custom Text widget now supports emojis - **๐Ÿ‘พ Emoji Support** - You can now paste emoji into the custom text widget. You can also turn on the merge option to get emoji labels for your widgets like this: ### v2.0.11 - Unlimited Status Lines - **๐Ÿš€ No Line Limit** - Configure as many status lines as you need - the 3-line limitation has been removed ### v2.0.10 - Git Updates - **๐ŸŒณ Git Worktree widget** - Shows the active worktree name when working with git worktrees - **๐Ÿ‘ป Hide 'no git' message toggle** - Git widgets now support hiding the 'no git' message when not in a repository (toggle with 'h' key while editing the widget) ### v2.0.8 - Powerline Auto-Alignment - **๐ŸŽฏ Widget Alignment** - Auto-align widgets across multiple status lines in Powerline mode for a clean, columnar layout (toggle with 'a' in Powerline Setup) ### v2.0.7 - Current Working Directory & Session Cost - **๐Ÿ“ Current Working Directory** - Display the current working directory with configurable segment display - Set the number of path segments to show (e.g., show only last 2 segments: `.../Personal/ccstatusline`) - Supports raw value mode for compact display - Automatically truncates long paths with ellipsis - **๐Ÿ’ฐ Session Cost Widget** - Track your Claude Code session costs (requires Claude Code 1.0.85+) - Displays total session cost in USD - Supports raw value mode (shows just `$X.YZ` vs `Cost: $X.YZ`) - Real-time cost tracking from Claude Code session data - Note: Cost may not update properly when using `/resume` (Claude Code limitation) - **๐Ÿ› Bug Fixes** - Fixed Block Timer calculations for accurate time tracking across block boundaries - Improved widget editor stability with proper Ctrl+S handling - Enhanced cursor display in numeric input fields ### v2.0.2 - Block Timer Widget - **โฑ๏ธ Block Timer** - Track your progress through 5-hour Claude Code blocks - Displays time elapsed in current block as hours/minutes (e.g., "3hr 45m") - Progress bar mode shows visual completion percentage - Two progress bar styles: full width (32 chars) or compact (16 chars) - Automatically detects block boundaries from transcript timestamps ### v2.0.0 - Powerline Support & Enhanced Themes - **โšก Powerline Mode** - Beautiful Powerline-style status lines with arrow separators and customizable caps - **๐ŸŽจ Built-in Themes** - Multiple pre-configured themes that you can copy and customize - **๐ŸŒˆ Advanced Color Support** - Basic (16), 256-color (with custom ANSI codes), and truecolor (with hex codes) modes, plus multi-stop **gradients** (per-widget or spanning the whole line) - **๐Ÿ”— Widget Merging** - Merge multiple widgets together with or without padding for seamless designs - **๐Ÿ“ฆ Easy Installation** - Install directly with `npx` or `bunx` - no global package needed - **๐Ÿ”ค Custom Separators** - Add multiple Powerline separators with custom hex codes for font support - **๐Ÿš€ Auto Font Install** - Automatic Powerline font installation with user consent

## โœจ Features - **๐Ÿ“Š Real-time Metrics** - Display model name, git branch, token usage, Sonnet/Opus/Fable weekly usage, extra usage limits, voice input state, session duration, compaction count, block timer, and more - **๐ŸŽจ Fully Customizable** - Choose what to display and customize colors for each element - **โšก Powerline Support** - Beautiful Powerline-style rendering with arrow separators, caps, and custom fonts - **๐Ÿ“ Multi-line Support** - Configure multiple independent status lines - **๐Ÿ–ฅ๏ธ Interactive TUI** - Built-in configuration interface using React/Ink - **๐Ÿ”Ž Fast Widget Picker** - Add/change widgets by category with search and ranked matching - **โš™๏ธ Global Options** - Apply consistent formatting across all widgets (padding, separators, bold, minimalist mode, and color overrides) - **๐Ÿ“ฆ Portable Configurations** - Export settings to JSON and preview replace-or-merge imports for backups and sharing - **๐Ÿš€ Cross-platform** - Works seamlessly with both Bun and Node.js - **๐Ÿ”ง Flexible Configuration** - Supports custom Claude Code config directory via `CLAUDE_CONFIG_DIR` environment variable - **๐Ÿ“ Smart Width Detection** - Automatically adapts to terminal width with flex separators - **โšก Zero Config** - Sensible defaults that work out of the box
## ๐ŸŒ Localizations The localizations in this section are third-party forks maintained outside this repository. They are not maintained, reviewed, or endorsed by this repository, so review their code and releases before using them. - ๐ŸŒ **ไธญๆ–‡็‰ˆ (Chinese):** [ccstatusline-zh](https://github.com/huangguang1999/ccstatusline-zh)
## ๐Ÿš€ Quick Start ### No installation needed! Use directly with npx or bunx: ```bash # Run the configuration TUI with npm npx -y ccstatusline@latest # Or with Bun (faster) bunx -y ccstatusline@latest ``` Both commands launch the same TUI. During the initial setup flow, choose **Pinned global install** if you want Claude Code to stay on the ccstatusline version you are running instead of following `@latest`; the TUI will install that version globally with npm or Bun and write the pinned `ccstatusline` command to Claude Code settings. After a pinned install, you can run `ccstatusline` directly to launch the TUI in the future.
Configure ccstatusline The interactive configuration tool provides a terminal UI where you can: - Configure multiple separate status lines - Add/remove/reorder status line widgets - Customize colors for each widget - Configure flex separator behavior - Configure Claude Code status line refresh interval when supported - Edit custom text widgets - Export JSON backups and preview imported configs before replacing or merging settings - Install/uninstall to Claude Code settings - Preview your status line in real-time > ๐Ÿ’ก **Tip:** Your settings are automatically saved to `~/.config/ccstatusline/settings.json` > ๐Ÿ”ง **Custom Claude Config:** If your Claude Code configuration is in a non-standard location, set the `CLAUDE_CONFIG_DIR` environment variable: > ```bash > # Linux/macOS > export CLAUDE_CONFIG_DIR=/custom/path/to/.claude > ``` > ๐ŸŒ **HTTPS proxy:** Usage and Claude Status requests honor uppercase `HTTPS_PROXY`, with exclusions from both `NO_PROXY` and `no_proxy`. See [proxy settings](docs/USAGE.md#proxy-settings) for host, domain, and port matching. > ๐ŸชŸ **Windows Support:** PowerShell examples, installation notes, fonts, troubleshooting, WSL, and Windows Terminal configuration are in [docs/WINDOWS.md](docs/WINDOWS.md). > ๐Ÿซฅ **Status line empty in one folder?** Claude Code only runs the status line command in trusted workspaces, and nested git repositories stopped inheriting trust in Claude Code 2.1.232. See [Status line empty in one folder](docs/USAGE.md#status-line-empty-in-one-folder-but-fine-elsewhere).
Claude Code settings.json format When you install from the TUI, ccstatusline writes a `statusLine` command object to your Claude Code settings: ```json { "statusLine": { "type": "command", "command": "npx -y ccstatusline@latest", "padding": 0, "refreshInterval": 10 } } ``` `refreshInterval` is written only when your Claude Code version supports it (>=2.1.97). The TUI can set it to `1-60` seconds, or remove it by leaving the input empty. Other supported command values are: - `bunx -y ccstatusline@latest` - `ccstatusline` (for self-managed/global installs) The status line command runs once per repaint, so what it costs to invoke is paid over and over. Under Bun that cost depends on the specifier: `bunx` re-resolves the `latest` dist-tag against the registry on every run, because a dist-tag is not cacheable. Measured on Windows with a warm cache, median of five runs of `--version`, which exits before rendering: | command | median | | --- | --- | | `bunx -y ccstatusline@latest` | 633 ms | | `bunx -y ccstatusline@2.2.27` | 202 ms | | `bunx -y ccstatusline` | 207 ms | Dropping `@latest` is worth about 430 ms per repaint there. npm does not behave this way: `npx -y ccstatusline@latest` and `npx -y ccstatusline@2.2.27` measured 1082 ms and 1135 ms, so pinning buys nothing under `npx`. A **Pinned global install**, which writes `"command": "ccstatusline"`, avoids the resolution entirely on both. For pinned installs, launch the TUI with `npx -y ccstatusline@latest` or `bunx -y ccstatusline@latest`, then choose **Pinned global install**. The TUI pins the active version by installing it globally and writing `"command": "ccstatusline"` to `settings.json`; afterward, you can run `ccstatusline` directly to open the TUI.
## ๐Ÿค Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## Support If ccstatusline is useful to you, consider buying me a coffee: Buy Me A Coffee ## ๐Ÿ“„ License [MIT](LICENSE) ยฉ Matthew Breedlove ## ๐Ÿ‘ค Author **Matthew Breedlove** - GitHub: [@sirmalloc](https://github.com/sirmalloc) ## ๐Ÿ”— Related Projects - [ccstatusline-editor](https://github.com/refinist/ccstatusline-editor) - A visual editor for building ccstatusline configurations โ€” drag, drop, preview, ship. - [tweakcc](https://github.com/Piebald-AI/tweakcc) - Customize Claude Code themes, thinking verbs, and more. - [ccusage](https://github.com/ryoppippi/ccusage) - Track and display Claude Code usage metrics. - [ccsidekick](https://ccsidekick.krayong.com/) - A Claude Code status-line with a reactive character plus cost, git, and usage widgets. - [codachi](https://github.com/vincent-k2026/codachi) - A tamagotchi-style statusline pet that grows with your context window. - [AIWatch](https://ai-watch.dev) - Live status monitor for 30+ AI APIs and apps; pairs with a Custom Command widget to surface provider outages in your status line. - [ccsessions](https://github.com/treebird7/ccsessions) - CLI session manager for Claude Code; includes `cc-session-num`, a Custom Command widget that shows the current session's rank (`#1`, `#2`, โ€ฆ). - [crispy-recall](https://github.com/TheSylvester/crispy-recall) - Searchable memory for your Claude Code and Codex sessions. Local, fast, no daemon. - [statuslin.es](https://statuslin.es) - Community gallery of Claude Code status lines with live, sandbox-rendered previews. - [claude-carbon](https://github.com/gwittebolle/claude-carbon) - Live CO2 estimate for your Claude Code sessions, next to the cost. Ships a `--segment` mode built to embed as a Custom Command widget. - [claudenews](https://github.com/bhpark1013/claudenews) - Developer news in your status line while the agent works: Hacker News, GitHub Trending, and per-language sources, with optional translation and short summaries. Ships a `--segment` mode built to embed as a Custom Command widget. ## ๐Ÿ™ Acknowledgments - Built for use with [Claude Code CLI](https://claude.ai/code) by Anthropic - Powered by [Ink](https://github.com/vadimdemedes/ink) for the terminal UI - Made with โค๏ธ for the Claude Code community
## Star History Star History Chart
### ๐ŸŒŸ Show Your Support Give a โญ if this project helped you! [](https://github.com/sirmalloc/ccstatusline/stargazers) [](https://github.com/sirmalloc/ccstatusline/network/members) [](https://github.com/sirmalloc/ccstatusline/watchers) [](https://www.npmjs.com/package/ccstatusline) [](https://www.npmjs.com/package/ccstatusline) [](https://github.com/sirmalloc/ccstatusline/blob/main/LICENSE) [](https://bun.sh) [](https://github.com/sirmalloc/ccstatusline/issues) [](https://github.com/sirmalloc/ccstatusline/pulls) [](https://github.com/sirmalloc/ccstatusline/graphs/contributors) ### ๐Ÿ’ฌ Connect [Report Bug](https://github.com/sirmalloc/ccstatusline/issues) ยท [Request Feature](https://github.com/sirmalloc/ccstatusline/issues) ยท [Discussions](https://github.com/sirmalloc/ccstatusline/discussions)
--- ### DEVELOPMENT (`docs/DEVELOPMENT.md`) # Development Development setup, project structure, and API documentation for `ccstatusline`. If you want the main project overview, return to [README.md](../README.md). ## Prerequisites - [Bun](https://bun.sh) (v1.0+) - Git - Node.js 14+ (optional, for running the built `dist/ccstatusline.js` binary or npm publishing) ## Setup ```bash # Clone the repository git clone https://github.com/sirmalloc/ccstatusline.git cd ccstatusline # Install dependencies bun install ``` ## Development Commands ```bash # Run in TUI mode bun run start # Test piped mode with example payload bun run example # Run tests bun test # Run typecheck + eslint checks without modifying files bun run lint # Apply ESLint auto-fixes intentionally bun run lint:fix # Build for distribution bun run build # Generate TypeDoc documentation bun run docs ``` ## Configuration Files - `~/.config/ccstatusline/settings.json` - ccstatusline UI/render settings - `~/.claude/settings.json` - Claude Code settings (`statusLine` command object) - `~/.cache/ccstatusline/block-cache-*.json` - block timer cache, including one-minute no-active-block results (keyed by Claude config directory hash) - `~/.cache/ccstatusline/git-cache/git-*.json` - persistent git widget command cache - `~/.cache/ccstatusline/git-review/git-review-*.json` - cached Git PR/MR lookup results - `~/.cache/ccstatusline/custom-command-cache/cmd-*.json` - opt-in custom command results, grouped by working directory and keyed by command, timeout, session ID, and terminal width - `~/.cache/ccstatusline/terminal-width.json` - per-session no-width probe results; detected numeric widths are not persisted by the renderer - `~/.cache/ccstatusline/usage.json` and `~/.cache/ccstatusline/usage.lock` - usage API data cache and fetch backoff lock - `~/.cache/ccstatusline/usage-credentials.lock` - 30-second backoff after a usage credential lookup finds no OAuth login, tagged with the profile it applies to - `~/.cache/ccstatusline/claude-status.json` and `~/.cache/ccstatusline/claude-status.lock` - Claude service-status cache and failed-fetch backoff lock - `~/.cache/ccstatusline/skills/skills-.jsonl` - skill hook records; session IDs must contain only ASCII letters, digits, `-`, or `_` If you use a custom Claude config location, set `CLAUDE_CONFIG_DIR` and ccstatusline will read/write that path instead of `~/.claude`. On macOS, usage credentials for a custom profile come from `Claude Code-credentials-`, then that profile's `.credentials.json`; the lookup does not fall back to another profile's Keychain entry. The hash uses the raw `CLAUDE_CONFIG_DIR` value normalized to NFC, without path resolution. `CLAUDE_SECURESTORAGE_CONFIG_DIR` overrides that hash input, including an empty value to force the default service lookup. Default lookup tries the plain service, discovered suffixed services, then the credentials file. Other platforms use the credentials file directly. Each Keychain subprocess has a five-second timeout; a missing OAuth login triggers a profile-specific 30-second lookup backoff. Usage-cache identity prefers a truncated SHA-256 fingerprint of the refresh token and falls back to the access token when no refresh token is available. Access-token rotation preserves the cache when the refresh token is unchanged. Legacy caches carrying the current access-token hash remain readable; the next successful fetch stores the preferred fingerprint. Mismatched account fingerprints are rejected even for stale-cache fallback during API backoff. Settings saves are atomic and preserve symlinked `settings.json` files by writing through the resolved target. Invalid or unreadable settings are never overwritten during load; `loadSettings()` returns in-memory defaults, records `getConfigLoadError()`, and renderer paths surface that state with an invalid-config warning badge. The TUI captures that load error, keeps a visible warning active, and guards both save paths with an overwrite confirmation until a valid configuration is saved. The atomic temporary file uses the replaced target's permission bits, or `0666` for a new file, subject to umask. Claude settings backups are recreated with the source mode so an older, more permissive backup does not retain its permissions. Installation reads and parses existing Claude settings before backing them up or modifying them; a read or parse failure stops installation. Configuration exports snapshot the live TUI settings and add an `exportedBy` package version. Imports reject newer schema versions before current-schema parsing, migrate supported older formats, and retain the source payload's present-key set so merge mode changes only explicitly supplied settings. `applyImport()` filters machine-local installation, schema-version, and update-message metadata; replace mode restores the current installation metadata, while merge mode preserves every omitted value. `ImportPreviewDialog` compares the selected mode's effective Custom Command strings with the current settings, lists new commands without duplicates, and requires confirmation with Cancel selected by default before applying them. Imports without new commands keep the direct apply flow. Preview paths, values, and commands escape C0/C1 controls as visible `\uXXXX` text. Usage-fetch tests spawn subprocess probes. Keep those probes sandboxed by setting `HOME`, `USERPROFILE`, `CLAUDE_CONFIG_DIR`, and proxy variables explicitly so tests cannot read or write a developer's live ccstatusline usage cache. Usage-lock deadlines more than 24 hours ahead are treated as poisoned and ignored, so mocked clocks, system clock jumps, or old test artifacts cannot suppress usage fetching indefinitely. Valid deadlines up to 24 hours ahead, including API `Retry-After` backoffs, remain active. Likewise, a `usage.json` modified more than its 180-second lifetime in the future counts as stale rather than fresh. After a complete successful usage fetch, the process clears the lock only if its contents still match the in-flight record it wrote, preserving a concurrent render's newer rate-limit backoff. ## Widget Data Sources - **Transcript-backed widgets** stream the active JSONL transcript once per render through `getTranscriptAnalysis()`, collecting token, duration, speed, compaction, thinking-effort, and session-name data in one pass without materializing the whole file. Referenced subagent transcripts are streamed separately only when speed metrics include subagents. - **Block Timer** caches a detected block until its five-hour window expires. When a full scan finds no active block, that empty result is cached for one minute so subsequent repaints do not repeatedly walk and read the entire transcript history. - **Cache Timer** reads the transcript tail directly on every render. It expands the read backward when a trailing JSONL record exceeds the initial window, ignores sidechain and synthetic API-error rows, and anchors the countdown only on assistant requests with cache activity. Interrupt markers and local slash-command records end the working state without refreshing the anchor. It does not create a separate cache file. - **Claude Status** reads `status.claude.com` through HTTPS, honors `HTTPS_PROXY` unless `NO_PROXY` excludes the host, and caches successful responses for five minutes. It requests incident data only when at least one configured Claude Status widget enables history, applies a 30-second backoff after failed fetches, and serves a usable stale cache when available. - **Local Git widgets** cache command results in memory and under `~/.cache/ccstatusline/git-cache`, with one persistent file per repository/working-directory pair. A conservative filesystem check skips Git when the directory is definitely outside a repository, while explicit Git environment overrides still allow invocation. Cache misses invoke Git with a five-second timeout; failures, including timeouts, are cached as `null`. Persistent writes use one stable `.tmp` path per cache file and attempt best-effort cleanup on failure, bounding orphaned files when Windows virus scanners or sync clients temporarily hold a handle. - **JJ widgets** invoke `runJjArgs()` with a five-second timeout and use their normal missing-data behavior when the command fails or times out. - **Git PR and Git CI Status** render from the versioned disk cache under `~/.cache/ccstatusline/git-review`. Missing or stale entries are refreshed in a detached helper so network-bound `gh` or `glab` calls do not block rendering. Git CI Status adds GitHub's `statusCheckRollup`; if the authenticated `gh` token cannot read checks, the refresh retries with PR metadata only so Git PR still works. - **Usage widgets** merge Claude Code's stdin `rate_limits` with `/api/oauth/usage` only for fields required by the active widgets. Session and aggregate weekly fields prefer the flat API buckets and fall back to `limits[]`; per-model weekly fields prefer `weekly_scoped` entries. A model-scoped entry reporting 0% without `resets_at` is valid zero usage, while unscoped empty placeholders remain filtered out. `WEEKLY_MODEL_USAGE_BUCKETS` in `src/utils/usage-types.ts` is the shared registry for Sonnet, Opus, and Fable widget wiring, field requirements, reset fields, and scoped-limit matching. Session and weekly percentage widgets delegate rendering and editor behavior to `src/widgets/shared/usage-percent-widget.ts`; the Fable label is `Weekly Fable:`. Spend Limit Usage and Spend Limit Amount read `rate_limits.spend_limit` from stdin only (no `USAGE_WIDGET_REQUIREMENTS` entry, so they never trigger an API fetch); the percentage widget goes through the same shared renderer with `ignoreApiError` set and no time cursor. - **Custom Command** delegates to `src/utils/custom-command.ts`. `customCommandCacheTtlSeconds` defaults to `0` (disabled), with a maximum of 60 seconds. Both successes and failures are cached, with TTL measured from command completion; without a session ID, entries stay in process memory. Other stdin fields are deliberately excluded from the key. A helper in the current runtime captures stdout in memory, limits it to 1 MiB, and retains at most 16,384 characters; it enforces command deadlines and closes inherited pipes, terminating the process group on POSIX or the shell on Windows when a command times out. Cached raw output is formatted separately by each widget, and previews never execute commands. - **Terminal width** is memoized once per render, including a `null` probe result. Linux first probes ancestor terminal devices through `/proc` and `tty.WriteStream`; portable fallbacks use `execFileSync` for `ps` and `stty`. `CCSTATUSLINE_WIDTH` takes precedence, including on Windows where probing is disabled. Only no-width results are persisted per session, for `terminalWidthCacheTtlSeconds` (default 5, range 0โ€“300); `0` disables cross-process reuse. Numeric widths are re-probed on the next render. - **Context length transcript fallback** treats the latest `compact_boundary` as the start of the current context. It uses the first main-chain usage entry after that boundary, then `compactMetadata.postTokens`, then zero, while session token totals remain cumulative. - **Sandbox Status** reads `sandbox.enabled` from Claude Code's layered project-local, project, user-local, and user settings on every refresh. This reflects `/sandbox` file updates but remains a best-effort indicator when managed or CLI settings take precedence. - **Skills** reads only logs for session IDs accepted by `getSkillsFilePath()`. Rejected IDs return no metrics, and the hook handler exits before creating directories or writing a log. Both usage and service-status requests honor uppercase `HTTPS_PROXY` and share `isExcludedFromProxy()` for the `NO_PROXY`/`no_proxy` rules described in [Usage](USAGE.md#proxy-settings). Each request has a total five-second deadline in addition to its socket timeout. On expiry, `createProxyAgent().close()` aborts the pending proxy connection when `AbortController` is available; on older runtimes without it, that connection can remain open. The proxy integration tests require permission to listen on a local socket. ## Widget Implementation Shared implementations under `src/widgets/shared/` cover Git counts, status indicators and remotes, JJ widgets, token counts, extra-usage amounts, and usage percentages. Reuse the matching base class or helper when adding related widgets. `format-options.ts` shares display-format and Nerd Font controls, while `searchable-option-editor.tsx` serves the locale and timezone editors. A widget opts into label editing with `getLabelPrefix(item)` and renders through `formatRawOrLabeledValue()`. The common `e` action stores a verbatim override in `metadata.label`; an empty string suppresses the label, raw mode bypasses it, and resetting removes the override. Keep mode-dependent default labels in `getLabelPrefix()` so previews and rendered output agree. Session Cost Rate reads `cost.total_cost_usd` and either `cost.total_api_duration_ms` (default) or `cost.total_duration_ms` from stdin; it requires at least 60,000 ms of the selected duration. Extra Usage Daily Budget uses the usage API's limit, spend, and currency fields, with UTC day counting in `shared/daily-budget.ts`; the current day always counts, even in weekdays-only mode. ## Git Commands and Terminal Output `execGit()` in `src/utils/git.ts` disables fsmonitor and sets `safe.bareRepository=explicit` (honored by Git 2.38+). Status/diff calls suppress repository-defined filters, external diff/textconv commands, and dirty-submodule inspection. Standard Git LFS filters and recognized absolute git-crypt commands outside the worktree remain allowed, as do filters defined in user/system config. If repository filters cannot be inspected or overridden, the command fails through the normal widget fallback. Git invoked by PR/CI helpers receives the fsmonitor and bare-repository settings through the environment. PR/MR lookups pass explicit branch names after `--` to `gh` and `glab`, and SSH alias resolution passes the host after `ssh -G --`. Git directory-file and remote-URL parsing avoid regex backtracking on long whitespace or slash sequences. On Windows, `resolveExecutable()` selects Git, JJ, SSH, `gh`, `glab`, and `chcp.com` from absolute PATH entries, skipping empty and relative entries. This keeps the current project directory out of implicit executable lookup. `sanitizeTerminalText()` filters widget text before layout and piped output before printing. It retains SGR styling, OSC 8 links with control-free, space-free URLs, tabs, and newlines; other terminal controls are removed. Hyperlink construction also validates URLs. Custom Command's preserve-colors option does not bypass this filtering. Width measurement fast-paths printable ASCII and caches up to 4,096 display-cluster widths per process. Truncation measures clusters across intervening ANSI escapes, preserving styling and hyperlink boundaries without exceeding the requested width. Widget hook synchronization installs ccstatusline hooks only when the configured status line command contains `ccstatusline`; otherwise it removes ccstatusline's managed hooks and preserves unrelated hooks. Update checks and global package installs both validate release-version strings before constructing install commands, including npm's Windows shell invocation. Powerline font installation uses a fresh `mkdtempSync()` directory and `execFileSync()` for Git and the downloaded installer, with cleanup in `finally`. ## Build Notes - The entry point imports the TUI lazily for interactive mode; keep the Ink initialization path out of piped rendering. The distribution build uses code splitting, so ship the complete `dist/` directory. - Build target is Node.js 14+ (`dist/ccstatusline.js`) - `postbuild` replaces the bundled `__PACKAGE_VERSION__` placeholder from `package.json`; `ccstatusline --version` reads that value and exits before mode detection - During install, `ink@6.2.0` is patched to fix backspace handling on macOS terminals - React and React DOM are exact-version pins; dependency refreshes should update `package.json` and `bun.lock` together ## API Documentation [`llms.txt`](../llms.txt) provides a short project overview and links to the hand-written guides for coding agents. Complete API documentation is generated using TypeDoc and includes detailed information about: - **Core Types**: Configuration interfaces, widget definitions, and render contexts - **Widget System**: All available widgets and their customization options - **Utility Functions**: Helper functions for rendering, configuration, and terminal handling - **Status Line Rendering**: Core rendering engine and formatting options ### Generating Documentation To generate the API documentation locally: ```bash # Generate documentation bun run docs # Clean generated documentation bun run docs:clean ``` The documentation will be generated in the `typedoc/` directory and can be viewed by opening `typedoc/index.html` in your web browser. ### Documentation Structure - **Types**: Core TypeScript interfaces and type definitions - **Widgets**: Individual widget implementations and their APIs - **Utils**: Utility functions for configuration, rendering, and terminal operations - **Main Module**: Primary entry point and orchestration functions ## Project Structure ```text ccstatusline/ โ”œโ”€โ”€ src/ โ”‚ โ”œโ”€โ”€ ccstatusline.ts # Main entry point โ”‚ โ”œโ”€โ”€ tui/ # React/Ink configuration UI โ”‚ โ”‚ โ”œโ”€โ”€ App.tsx # Root TUI component โ”‚ โ”‚ โ”œโ”€โ”€ index.tsx # TUI entry point โ”‚ โ”‚ โ””โ”€โ”€ components/ # UI components โ”‚ โ”‚ โ”œโ”€โ”€ MainMenu.tsx โ”‚ โ”‚ โ”œโ”€โ”€ LineSelector.tsx โ”‚ โ”‚ โ”œโ”€โ”€ ItemsEditor.tsx โ”‚ โ”‚ โ”œโ”€โ”€ ColorMenu.tsx โ”‚ โ”‚ โ”œโ”€โ”€ PowerlineSetup.tsx โ”‚ โ”‚ โ””โ”€โ”€ ... โ”‚ โ”œโ”€โ”€ widgets/ # Status line widget implementations โ”‚ โ”‚ โ”œโ”€โ”€ Model.ts โ”‚ โ”‚ โ”œโ”€โ”€ GitBranch.ts โ”‚ โ”‚ โ”œโ”€โ”€ TokensTotal.ts โ”‚ โ”‚ โ”œโ”€โ”€ OutputStyle.ts โ”‚ โ”‚ โ””โ”€โ”€ ... โ”‚ โ”œโ”€โ”€ utils/ # Utility functions โ”‚ โ”‚ โ”œโ”€โ”€ config.ts # Settings management โ”‚ โ”‚ โ”œโ”€โ”€ renderer.ts # Core rendering logic โ”‚ โ”‚ โ”œโ”€โ”€ powerline.ts # Powerline font utilities โ”‚ โ”‚ โ”œโ”€โ”€ colors.ts # Color definitions โ”‚ โ”‚ โ””โ”€โ”€ claude-settings.ts # Claude Code integration (supports CLAUDE_CONFIG_DIR) โ”‚ โ””โ”€โ”€ types/ # TypeScript type definitions โ”‚ โ”œโ”€โ”€ Settings.ts โ”‚ โ”œโ”€โ”€ Widget.ts โ”‚ โ”œโ”€โ”€ PowerlineConfig.ts โ”‚ โ””โ”€โ”€ ... โ”œโ”€โ”€ dist/ # Built files (generated) โ”œโ”€โ”€ docs/ # Hand-written repository docs โ”œโ”€โ”€ typedoc/ # Generated API docs โ”œโ”€โ”€ package.json โ”œโ”€โ”€ tsconfig.json โ””โ”€โ”€ README.md ``` --- ### USAGE (`docs/USAGE.md`) # Usage Usage documentation for `ccstatusline`. If you want the main project overview, return to [README.md](../README.md). Once configured, `ccstatusline` automatically formats your Claude Code status line. The status line appears at the bottom of your terminal during Claude Code sessions. ## Runtime Modes - **Interactive mode (TUI)**: Launches when there is no stdin input - **Piped mode (renderer)**: Parses Claude Code status JSON from stdin and prints one or more formatted lines - **Version mode**: Prints the installed ccstatusline package version and exits when passed `--version` ```bash # Interactive TUI bun run start # Piped mode with example payload bun run example # Print the installed package version ccstatusline --version ``` ## Available Widgets ### Claude & Session - **Model** / **Output Style** / **Version** - Show the active Claude model, output style, and Claude Code CLI version. Model names omit trailing context suffixes like `(1M context)`; use **Context Window** when you want the total window size shown. - **Claude Session ID** / **Session Name** / **Claude Account Email** - Show session identifiers plus the currently signed-in Claude account email. - **Claude Status** - Show the current Claude/Anthropic service status from `status.claude.com` (`ok` when the indicator is `none`, otherwise the indicator word such as `minor`, `major`, `critical`, or `maintenance`). Press `h` in the editor to add a 48-hour incident-history strip of eight six-hour blocks (oldest to newest), each colored by the worst incident overlapping that block: green (none), yellow (minor), orange (major), red (critical). Responses are cached for about five minutes; on network failure the widget shows stale data when available or degrades to `?`. With the history strip enabled the widget colors itself by severity, so per-widget foreground colors and theme foregrounds are skipped, like Custom Command's preserve-colors mode. Press `l` to make the widget a link to the status page (`https://status.claude.com`), in terminals that support OSC 8 hyperlinks. - **Voice Status** - Show whether Claude Code voice input is enabled. It can render as an icon, icon plus text, plain text, or `voice on/off`, with optional Nerd Font microphone icons. - **Sandbox Status** - Show the effective `sandbox.enabled` value from Claude Code's layered project and user settings. It can render as a glyph, `SB: ON/OFF`, or `Sandbox: ON/OFF`, with optional Nerd Font lock icons. The value is refreshed after `/sandbox` changes, but is best effort when managed or CLI settings override files or sandbox initialization fails. - **Thinking Effort** / **Vim Mode** / **Skills** - Show Claude thinking effort, the current vim editing mode, and skill activity from hook data. Thinking Effort reads live status JSON first, then `/model` or `/effort` transcript output, then settings fallback; it supports `low`, `medium`, `high`, `xhigh`, and `max`, shows `default` when no effort is set, and marks unknown future values with `?`. Claude Code reports Ultracode as `xhigh` in status line data; it does not expose Ultracode as a separate effort level. - **Session Clock** / **Session Cost** / **Session Cost Rate** - Show elapsed session time, the current session cost in USD, and that cost per hour (`Rate: $5.00/hr`). Session Cost Rate divides by the time Claude spent working (API time) by default, or by the whole session with clock time on, and shows nothing until a full minute of that time has passed. ### Git - **Git Branch** / **Git Root Dir** / **Git PR** - Show the current branch, repository root directory, and PR/MR details for the current branch with optional links. With a detached HEAD, Git Branch shows the short commit SHA in parentheses. Git Branch and Git Root Dir can cap their visible labels to a per-widget maximum width; truncation keeps OSC 8 hyperlink targets intact. Works with GitHub (`gh`) and GitLab (`glab`); SSH remote aliases are resolved with `ssh -G` before provider detection, while canonical GitHub/GitLab remotes keep their original forge hosts. For self-hosted hosts whose name contains neither token, whichever CLI is authenticated against that host (`gh auth status --hostname ` / `glab auth status --hostname `) is used. - **Git CI Status** - Summarize GitHub checks for the current branch's pull request as failing (`โœ—`), pending (`โ—`), and successful (`โœ“`) counts. Raw-value mode renders `failing`, `pending`, or `passing`; `-` means no pull request or readable check rollup. This widget is GitHub-only and uses the same cached `gh` lookup as Git PR. - **Git Changes** / **Git Insertions** / **Git Deletions** - Show combined or separate insertion/deletion counts, with customizable signs through `g`. - **Git Status** / **Git Staged** / **Git Unstaged** / **Git Untracked** / **Git Ahead/Behind** / **Git Conflicts** / **Git SHA** - Show compact repo-state indicators, upstream divergence, merge-conflict count, and the current short commit SHA. - **Git Staged Files** / **Git Unstaged Files** / **Git Untracked Files** / **Git Clean Status** - Show file-level status counts and clean/dirty state. Git Clean Status supports custom clean/dirty glyphs through `g`; raw mode shows the words `clean` or `dirty`. - **Git Origin Owner** / **Git Origin Repo** / **Git Origin Owner/Repo** - Show parsed `origin` remote metadata. - **Git Upstream Owner** / **Git Upstream Repo** / **Git Upstream Owner/Repo** / **Git Is Fork** - Show upstream remote metadata and whether the current repo is a fork. Git Is Fork displays `โ‘‚` for forks by default; press `g` to customize it, or use raw mode for `true`/`false`. - **Git Worktree** / **Git Worktree Mode** / **Git Worktree Name** / **Git Worktree Branch** / **Git Worktree Original Branch** - Show worktree status plus the active worktree's name and branch metadata. ### Jujutsu (JJ) - **JJ Revision** / **JJ Bookmarks** / **JJ Workspace** - Show the current change ID, bookmarks, or workspace name, with customizable prefix glyphs through `g`. - **JJ Changes** / **JJ Insertions** / **JJ Deletions** - Show combined or separate insertion/deletion counts, with customizable signs through `g`. - **JJ Root Dir** / **JJ Description** - Show the repository root directory name or current change description. ### Tokens, Usage & Context - **Tokens Input** / **Tokens Output** / **Tokens Cached** / **Tokens Total** - Show current-session token counts. Input/output prefer cumulative transcript metrics and fall back to `context_window.total_input_tokens` / `context_window.total_output_tokens` when transcript metrics are unavailable; cached/total use transcript metrics. - **Cache Hit Rate** / **Cache Read** / **Cache Write** - Show prompt-cache efficiency. Cache Hit Rate uses cache reads divided by cache reads plus cache writes; Cache Read and Cache Write include each value's share of prompt context. They default to the latest turn from `context_window.current_usage`, can switch to cumulative session totals, and can hide when empty. - **Cache Timer** - Estimate time remaining before the current prompt-cache entry expires. It shows `HOT` while a main-chain turn is active, then counts down from the latest assistant request with cache activity and becomes `COLD` just before expiry. Interrupts and local slash commands such as `/cost` end the working state without refreshing that cache anchor. The default TTL is 5 minutes; it can switch to 1 hour, hide when no cache anchor is available, and customize the glyph for each state. Because Claude Code transcripts expose cache token activity rather than the actual expiry timestamp, the countdown is best effort. - **Input Speed** / **Output Speed** / **Total Speed** - Show session-average token throughput with an optional per-widget rolling window (`0-120` seconds; `0` = full-session average). - **Context Length** / **Context Window** / **Context %** / **Context % (usable)** / **Context Bar** - Show current context length, total context window size, used/remaining percentage, usable-window percentage, or a progress bar. The window size is taken from Claude Code's reported `context_window.context_window_size` when present, then from a model-name hint (e.g. a `[1m]` suffix), and finally from a fixed fallback. Set `CCSTATUSLINE_CONTEXT_SIZE_FALLBACK` to a positive integer to override that last-resort fallback (defaults to `200000`) โ€” useful when an older Claude Code does not report the window size for a 1M-context model, so the bar would otherwise read against 200k. Immediately after `/compact`, transcript fallback uses the latest `compact_boundary.postTokens` value until a new main-chain turn reports the current size, so the widgets do not retain the pre-compaction context. - **Compaction Counter** - Show how many context compactions have been detected in the current session by scanning transcript compaction markers. It can render as icon plus number, text plus number, or number-only, and can hide while the count is zero. Two optional, independent per-item add-ons toggle extra detail: a trigger split (`โ†ป 3 (2 auto, 1 manual)`; a compaction whose trigger is missing or unrecognized is bucketed as `unknown`) and tokens reclaimed (`โ†ป 3 โ†“887.0k`, each compaction's `preTokens - postTokens` floored at 0 and summed, shown only when greater than 0 โ€” so very old transcripts predating the `postTokens` field display nothing). Its value selector can instead render the total count, one trigger count (`auto`, `manual`, or `unknown`), or reclaimed tokens as a standalone value; hide-when-zero applies to the selected value. - **Spend Limit Usage** / **Spend Limit Amount** - For developers behind a Claude apps gateway with spend limits (Claude Code 2.1.251 or later). Spend Limit Usage shows the share of the limit used, as a percentage or bar, and can show the remaining share instead. Spend Limit Amount shows `$314.12 / $500.00` and renders nothing until the gateway reports the dollar figures (Claude Code and gateway 2.1.284 or later). Both read `rate_limits.spend_limit` from the status line payload only and never call the usage API; without a spend limit they render nothing. - **Block Usage** / **Weekly Usage** / **Weekly Sonnet Usage** / **Weekly Opus Usage** / **Weekly Fable Usage** / **Extra Usage Utilization** / **Extra Usage Remaining** / **Extra Usage Used** / **Extra Usage Daily Budget** / **Block Timer** / **Block Reset Timer** / **Weekly Reset Timer** - Show usage percentages, monthly pay-as-you-go overage usage, and current block/reset timing. Block Usage and the all-model Weekly Usage read the legacy flat API buckets when available and fall back per field to `session` and `weekly_all` entries in the newer `limits[]` response. The per-model widgets prefer `weekly_scoped` entries for Sonnet, Opus, and Fable, with legacy Sonnet/Opus buckets as fallbacks; Weekly Fable Usage renders nothing when the API reports no Fable quota. Block Usage, the weekly percentage widgets, and Extra Usage Utilization can show either used or remaining percentage in every display mode. Block and weekly usage bars can also show a time cursor. Extra usage widgets accept known extra-usage state as complete when an account has no monthly limit configured, avoid repeated refetches and stale `[Timeout]` output, and format amounts with the API-reported billing currency when available. On accounts with no plan limits (usage-based Enterprise plans), extra usage is all of the account's spend rather than overage beyond a plan; the label editor can change the Extra Usage widgets' `Overage` labels to read `Spend`. Before the first charge of the month the API reports no utilization, so Extra Usage Utilization works it out from the amount spent and the monthly limit. Extra Usage Daily Budget divides what's left of the monthly limit by the days left in the month, today included, optionally skipping future weekend days (today always counts). It requires a monthly limit and amount spent, and displays zero once the limit is exhausted. Days are UTC days, since monthly limits reset at 00:00 UTC on the 1st. Reset timers can show remaining time, progress, or exact reset date/time with timezone and locale controls; while reset data is still arriving at startup, they show a labeled loading placeholder instead of a transient API error. An explicit per-model quota at 0% is shown even when its reset timestamp is still missing; the time cursor appears only once a usable window is available. Weekly Fable Usage uses the label `Weekly Fable:` and stays empty when the API reports no Fable quota. ### Environment, Layout & Custom - **Current Working Dir** / **Terminal Width** / **Memory Usage** - Show the current working directory, detected terminal width, and system memory usage. Current Working Dir can prepend an optional custom glyph, including when raw-value mode replaces the `cwd:` label. When combining home abbreviation with a segment limit, `~` is preserved without counting toward that limit. - **Custom Text** / **Custom Symbol** / **Custom Command** / **Link** - Add user-defined text, a single symbol or emoji, custom command output, or a clickable OSC 8 hyperlink. - **Separator** / **Flex Separator** - Add a manual divider or a width-filling flexible spacer. Manual separators are disabled in Powerline mode, but flex separators still work there as layout spacers. ## Terminal Width Options These settings affect where long lines are truncated, and where right-alignment occurs when using flex separators: - **Full width always** - Uses full terminal width (default; may wrap if auto-compact message appears or IDE integration adds text) - **Full width minus 40** - Reserves 40 characters for auto-compact message to prevent wrapping - **Full width until compact** - Dynamically switches between full width and minus 40 based on context percentage threshold (configurable, default 60%) The default applies to new configurations and settings without an explicit `flexMode`; saved mode choices are preserved. Flex separators expand against the detected width in both regular and Powerline rendering. If width detection is unavailable, they render like normal separators until a terminal width is available. If ccstatusline cannot detect your terminal width, set `CCSTATUSLINE_WIDTH` to a positive integer to override probing: ```bash CCSTATUSLINE_WIDTH=160 ccstatusline ``` The override is checked before automatic width detection, so it also works in wrapper processes, IDE integrations, nested PTYs, and Windows environments where probing may be unavailable. Invalid values such as `0`, negative numbers, or non-numeric strings are ignored and ccstatusline falls back to normal detection. On Linux, width detection first uses `/proc` and the terminal device directly, avoiding subprocesses when that probe succeeds. Portable `ps`/`stty` fallbacks run without shell wrappers. A probe result is reused throughout one render. If no width is found, that result can also be cached for the same session across renders (default: 5 seconds); a detected width is always re-probed on the next render so resizes take effect immediately. Adjust **Terminal Width Cache TTL** under **Configure Status Line**, or set `terminalWidthCacheTtlSeconds` to `0-300` in `settings.json`; `0` disables the cache across renders. ## Powerline Auto-Alignment Powerline Setup can align widgets into shared columns across multiple status lines; press `a` there to toggle **Align Widgets**. When auto-alignment makes a naturally wide value stretch later columns, select that widget in the line editor and press `x` (**exclude align**). The selected widget and everything after it on that line keep their natural widths, while earlier columns remain aligned. This control is available only when Powerline auto-alignment is enabled and the selected widget is not merged into the previous widget. ## Global Options Configure global formatting preferences that apply to all widgets: ### Default Padding & Separators - **Default Padding** - Add consistent padding around each widget - **Padding Side** - Choose whether default padding applies to **Both** sides (default), **Left only**, or **Right only** - **Default Separator** - Automatically insert a separator between all widgets - Press **(p)** to edit padding - Press **(d)** to cycle padding side - Press **(s)** to edit separator - Manual separators look past widgets that render empty, so the intended separator remains between visible neighbors without duplicating an earlier visible boundary. Inherited separator colors come from the actual preceding visible widget.
Global Formatting Options - **Inherit Colors** - Default separators inherit foreground and background colors from the preceding widget - Press **(i)** to toggle - **Global Bold** - Apply bold formatting to all text regardless of individual widget settings - Press **(o)** to toggle - **Minimalist Mode** - Force widgets into raw-value rendering globally for a cleaner, label-free status line - Press **(m)** to toggle - **Number Formatting** - Choose precise, compact, or whole-number output independently for token, speed, percent, memory, and cost values - Press **(n)** to configure each number type; a global choice overrides per-widget formatting for that type - **Override Foreground Color** - Force all widgets to use the same text color, or a whole-line **gradient** (see below) - Press **(f)** to cycle through colors - Press **(g)** to choose a gradient - Press **(x)** to clear override - **Override Background Color** - Force all widgets to use the same background color - Press **(b)** to cycle through colors - Press **(c)** to clear override
> ๐Ÿ’ก **Note:** These settings are applied during rendering and don't add widgets to your widget list. They provide a consistent look across your entire status line without modifying individual widget configurations. > โš ๏ธ **VSCode Users:** If colors appear incorrect in the VSCode integrated terminal, the "Terminal โ€บ Integrated: Minimum Contrast Ratio" (`terminal.integrated.minimumContrastRatio`) setting is forcing a minimum contrast between foreground and background colors. You can adjust this setting to 1 to disable the contrast enforcement, or use a standalone terminal for accurate colors. ## Widget Styling The color editor can adjust foreground color, background color, bold, dim, and gradients per widget: - Use `โ†` / `โ†’` to cycle the selected foreground or background color. - Press `f` to switch between foreground and background editing. - Press `b` to toggle bold. - Press `d` to cycle dim styling: off โ†’ whole widget โ†’ parenthesized text only โ†’ off. - Press `r` to reset styling on the selected widget, or `c` to clear styling on every widget in the line. ## Gradient Colors A foreground color can be a multi-stop **gradient** instead of a solid. Colors interpolate in OKLab for perceptually even blends. A gradient value takes one of three forms, all prefixed `gradient:`: - **Named preset** โ€” `gradient:atlas` (case-insensitive). Built-in presets: `atlas`, `cristal`, `teen`, `mind`, `morning`, `vice`, `passion`, `fruit`, `instagram`, `retro`, `summer`, `rainbow`, `pastel`. - **Dash stops** โ€” `gradient:RRGGBB-RRGGBB[-RRGGBB...]` (two or more bare or `#`-prefixed hex stops). - **Comma stops** โ€” `gradient:hex:RRGGBB,#RRGGBB,RRGGBB` (two or more `hex:`/`#`/bare stops). Gradients apply at **two scopes**: - **Per-widget** โ€” set a widget's color to a gradient so its text carries its own self-contained sweep. In the color menu (foreground, 256-color or truecolor mode), press **(g)** to open the gradient picker, then choose a preset or enter custom start/end hex stops. - **Whole line** โ€” set `overrideForegroundColor` to a gradient spec to paint the entire status line with one continuous sweep, each character colored by its column position. In the Global Overrides menu, press **(g)** on Override FG Color to open the same gradient picker, or author the value directly in `settings.json`. Gradients self-degrade where they can't render: at Basic or No Color levels, gradient settings are preserved but render as plain text. In Powerline mode, global foreground gradients color widget text while separators and caps keep Powerline's normal foreground/background contrast rules; per-widget gradients collapse to their first stop when using 256-color or truecolor output. ## Claude Code Status Line Settings When ccstatusline is installed in Claude Code, the main menu includes **Configure Status Line**. Claude Code versions >=2.1.97 support `statusLine.refreshInterval`; ccstatusline can set it to `1-60` seconds, defaults fresh supported installs to `10` seconds, and removes the setting when the input is left empty. The same menu controls these ccstatusline cache settings, saved with **Save & Exit** or `Ctrl+S`: | Setting | JSON key | Default | Range | Meaning of `0` | | --- | --- | --- | --- | --- | | Git Cache TTL | `gitCacheTtlSeconds` | 5 seconds | 0โ€“60 seconds | Reuse until `.git/HEAD` or `.git/index` modification times change; no age-based expiry | | Custom Command Cache TTL | `customCommandCacheTtlSeconds` | 0 seconds | 0โ€“60 seconds | Run commands on every render | | Terminal Width Cache TTL | `terminalWidthCacheTtlSeconds` | 5 seconds | 0โ€“300 seconds | Re-probe on every render, even after no width was found | Git commands run on cache misses with a five-second timeout. Persistent caches are separate for each repository and working directory, so sessions in different subdirectories do not evict each other's results. Calls are skipped when ccstatusline can determine that the directory is outside any repository. JJ commands also have a five-second timeout. A timed-out command follows the normal missing-data path for its widget. ### Status line empty in one folder but fine elsewhere Claude Code only runs a custom `statusLine` command in a workspace whose trust dialog has been accepted (since Claude Code 2.1.51). Since 2.1.232, a git repository nested under an already-trusted parent folder no longer inherits that trust, and Claude Code does not always show the trust dialog again. In such a folder, ccstatusline is never invoked, so the status line renders as an empty row even though running `ccstatusline` by hand in the same folder works and other folders still show it. To confirm, look up the project path in `~/.claude.json` under `projects` and check its `hasTrustDialogAccepted` value. Setting it to `true` (or accepting the trust dialog when Claude Code shows it) and starting a new session restores the status line. ## Usage Credentials and Cache Usage API requests read credentials from the active Claude config directory's `.credentials.json` on Linux and Windows. On macOS, a custom `CLAUDE_CONFIG_DIR` selects its matching Keychain service first, then falls back only to that profile's credentials file. `CLAUDE_SECURESTORAGE_CONFIG_DIR`, when set, overrides the value used to select the Keychain service; an empty value selects the default service lookup. With the default service lookup, ccstatusline tries `Claude Code-credentials`, then matching suffixed services, then the credentials file. The usage cache uses a fingerprint of the refresh token when available, falling back to the access token. Access-token rotation with an unchanged refresh token preserves fresh and stale usage snapshots, including during rate-limit backoff; a changed login fingerprint invalidates the old account's cache. Each macOS Keychain command has a five-second timeout. When no OAuth credentials are found, the lookup backs off for 30 seconds for that profile, so a newly signed-in account may take up to 30 seconds to appear. Usage cache files dated more than 180 seconds into the future are treated as stale. ### Proxy Settings Usage requests to `api.anthropic.com` and Claude Status requests to `status.claude.com` honor uppercase `HTTPS_PROXY`. Both `NO_PROXY` and `no_proxy` supply exclusions; matching either variable sends the request directly. Exclusions are separated by commas or whitespace and matched without regard to case. Use `*` for all hosts, a hostname such as `api.anthropic.com`, or a domain such as `anthropic.com`, `.anthropic.com`, or `*.anthropic.com` to match that domain and its subdomains. An optional `:443` suffix is supported; entries for other ports do not match these HTTPS requests. Each request has a total five-second deadline, including the wait for a proxy to answer CONNECT. The usual stale-cache and error-display behavior applies when the deadline expires. ## Configuration Import and Export The TUI main menu can move configurations between machines or preserve a backup: - **Export Config** writes the current in-memory configuration to a JSON file, including edits that have not been saved to `settings.json` yet. The default destination is `~/ccstatusline-config.json`; parent directories are created as needed, and the export records the ccstatusline version that created it. - **Import Config** reads a JSON file, validates it, migrates supported older formats, rejects files from newer schema versions, and shows the effective changes before anything is applied. The import preview follows the highlighted action: - **Replace All** replaces user-facing settings with the validated import and current defaults for omitted fields. - **Merge** overlays only fields explicitly present in the imported file, preserving current values for omitted settings. Both modes keep machine-local installation metadata and ignore schema/update metadata from the imported file. Applying an import updates only the TUI's working configuration; review the result, then choose **Save & Exit** or press `Ctrl+S` to persist it. If the selected mode adds Custom Command shell commands that are not already in the current configuration, the preview lists each new command in full. Choosing **Replace All** or **Merge** then opens a confirmation with **Cancel** selected by default. Choose **Apply and run these commands** to accept, or Cancel/Escape to return to the preview. Imports without new commands apply immediately. Preview values, paths, and commands display control characters as `\uXXXX`, making them visible without executing terminal controls. ## Settings Recovery If `settings.json` is unreadable or invalid, ccstatusline leaves the file unchanged, renders with built-in defaults for that run, and prepends an invalid-config warning badge to the status line. The TUI shows the same warning and asks for confirmation before either **Save & Exit** or `Ctrl+S` replaces the invalid file. Fix the JSON to preserve its contents, or confirm the save to replace it with the configuration currently shown in the TUI. Installation also stops if Claude Code's own `settings.json` cannot be read or parsed, leaving that file unchanged and showing the error. Correct the file before trying the installation again. On systems with POSIX file permissions, saving an existing ccstatusline settings file preserves restrictive permissions such as `0600`, including when saving through a symlink. Claude Code settings backups (`.bak` and `.orig`) are created with the source file's permissions, subject to the process umask. ## Block Timer Widget The Block Timer widget helps you track your progress through Claude Code's 5-hour conversation blocks: **Display Modes:** - **Time Display** - Shows elapsed time as "3hr 45m" (default) - **Progress Bar** - Full width 32-character progress bar with percentage - **Progress Bar (Short)** - Compact 16-character progress bar with percentage **Features:** - Automatically detects block boundaries from transcript timestamps - Floors block start time to the hour for consistent tracking - Shows "Block: 3hr 45m" in normal mode or just "3hr 45m" in raw value mode - Progress bars show completion percentage (e.g., "[โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘] 73.9%") - Use **(p)** to cycle time/full bar/short bar, **(s)** for compact time mode, and **(v)** to invert fill in progress mode ## Raw Value Mode Some widgets support "raw value" mode which displays just the value without a label: - Normal: `Model: Claude 3.5 Sonnet` โ†’ Raw: `Claude 3.5 Sonnet` - Normal: `Session: 2hr 15m` โ†’ Raw: `2hr 15m` - Normal: `Block: 3hr 45m` โ†’ Raw: `3hr 45m` - Normal: `Ctx: 18.6k` โ†’ Raw: `18.6k` To keep a label but change it, select the widget and press `e` (`(e)dit labelโ€ฆ`) instead. The label is replaced verbatim, so include any trailing space or colon yourself (e.g. `M ` renders `M Claude 3.5 Sonnet`); an empty label drops it, and Tab in the editor resets it to the default. Widgets whose label changes with their mode (e.g. `Ctx Used:`/`Ctx Left:`, or `Block:` vs `Block ` before a progress bar) use the one custom label in every mode, even one that matches the current mode's default. The editor row shows `(label: "M ")` while a custom label is set; `e` is hidden while raw value is on, since the label isn't rendered then. ## Number Formatting Numeric widgets support three display styles without changing their underlying values: - **Precise** (default) keeps the formatter's normal trailing zeros, such as `1.0M` or `$1.20` - **Compact** removes insignificant trailing zeros while preserving real fractions, such as `1M` or `1.1M` - **Whole** rounds the displayed value to zero decimal places, such as `1M` Select a numeric widget in the line editor and press `.` to cycle its style. In **Global Overrides**, press `n` to set a style for all token, speed, percent, memory, or cost widgets; that per-type global setting takes precedence over individual widget styles. Advanced configurations can also set `numberFormat.decimals` from `0` to `6` on a widget or number type in `settings.json`; the style then controls whether those decimal places are retained, trimmed, or suppressed. ## Widget Editor Keybinds Common controls in the line editor: - `โ†‘/โ†“` select widget - `โ†/โ†’` open the type picker for the selected widget - navigation wraps at list boundaries, including move/reorder mode - `a` add widget via the picker - `i` insert widget via the picker - `k` clone the selected widget - `Enter` enter/exit move mode - `d` delete selected widget - `c` clear the current line - `Space` cycle a manual separator character - `r` toggle raw value (supported widgets) - `e` edit the label shown before the value when raw value is off (labeled widgets) - `.` cycle precise/compact/whole number formatting (supported widgets) - `m` cycle merge mode (`off` โ†’ `merge` โ†’ `merge no padding`); on the last widget, clear an existing merge - `x` exclude the selected widget and the rest of its line from shared Powerline column widths (shown only when Powerline auto-alignment is enabled) - `Esc` go back Widget picker: - type to search categories and widgets - supports substring, initialism, and fuzzy matching - `โ†‘/โ†“` change selection, `Enter` continue/apply, `Esc` clear search/back/cancel The keybind footer in the TUI only shows shortcuts that apply to the currently selected widget. Plain-letter shortcuts ignore Ctrl and Alt/Option modifiers, so combinations such as `Ctrl+S` do not also trigger the letter action. Widget-specific shortcuts: - **Glyph widgets** (Git Branch, Git Worktree, Git Worktree Mode, Git Staged, Git Unstaged, Git Untracked, Git Conflicts, Git Ahead/Behind, Git Status, Git Changes, Git Insertions, Git Deletions, Git Clean Status, Git Is Fork, JJ Revision, JJ Bookmarks, JJ Workspace, JJ Changes, JJ Insertions, JJ Deletions): `g` set custom glyphs for the widget's symbols; Backspace in the editor renders without one, and multi-symbol widgets (Ahead/Behind, Status, Conflicts, Changes, Clean Status) edit each part in one list - **Git Branch**: `l` toggle clickable branch links (GitHub, GitLab, self-hosted), `w` set a maximum visible width (blank removes the limit) - **Git Root Dir**: `l` cycle IDE links (`off` โ†’ `VS Code` โ†’ `Cursor`), `w` set a maximum visible width (blank removes the limit) - **Git PR**: `s` toggle review status, `t` toggle title (renders "MR" for GitLab origins) - **Git remote widgets** (`Git Origin*` / `Git Upstream*`): `l` toggle clickable repo links - **Git Origin Owner/Repo**: `o` show only the owner when the repo is a fork - **Git Conflicts**: `z` toggles how a visible conflict-free tree renders (`โš 0` or the clean glyph); `g` edits the conflict and clean glyphs - **Context % widgets**: `u` toggle used vs remaining display, `p` cycle percentage/short bar/short bar only - **Session Cost Rate**: `t` switch between active time (how long Claude spent working, the default) and clock time (the whole session) - **Block Usage / Weekly Usage / Weekly Sonnet Usage / Weekly Opus Usage / Weekly Fable Usage / Spend Limit Usage / Extra Usage Utilization**: `p` cycle percentage/full bar/medium bar/short bar/short bar only and `u` switch between used and remaining percentage in every display mode. The editor row labels the current direction as `used` or `remaining`, while the `u` helper names the direction it will switch to. Block and weekly usage widgets use `t` to toggle the time cursor in bar modes. - **Extra Usage Daily Budget**: `w` toggle counting weekdays only (Saturday and Sunday, UTC, are skipped; today always counts) - **Block Timer**: `p` cycle time/full bar/short bar, `s` toggle compact time, `v` invert fill in progress mode - **Block Reset Timer**: `p` cycle time/full bar/short bar, `s` toggle compact time/date, `t` toggle exact reset date/time, `f` toggle 12/24-hour display in date mode, `z` edit timezone in date mode, `l` edit locale in date mode, `v` invert fill in progress mode - **Weekly Reset Timer**: `p` cycle time/full bar/short bar, `s` toggle compact time/date, `t` toggle exact reset date/time, `o` toggle hours-only in time mode, `f` toggle 12/24-hour display in date mode, `z` edit timezone in date mode, `l` edit locale in date mode, `v` invert fill in progress mode - **Context Bar**: `p` cycle medium/full/short/short-only progress bar - **Compaction Counter**: `v` cycle value (count/auto/manual/unknown/reclaimed), `f` cycle format, `n` toggle Nerd Font icon in icon mode, `s` toggle trigger split (auto/manual/unknown), `t` toggle tokens reclaimed - **Cache widgets** (Cache Hit Rate, Cache Read, Cache Write): `t` toggle turn/session scope - **Cache Timer**: `t` cycle 5-minute/1-hour TTL, `g` customize the working/fresh/draining/urgent/cold glyphs - **Sandbox Status**: `f` cycle glyph/text/word format, `n` toggle Nerd Font lock icons in glyph mode - **Claude Status**: `h` toggle the 48-hour incident-history strip, `l` toggle the link to the status page - **Voice Status**: `f` cycle format, `n` toggle Nerd Font microphone icons - **Current Working Dir**: `h` home abbreviation, `s` segment editor, `f` fish-style path, `g` optional leading glyph (off by default; pair with raw value to replace the `cwd:` label with the glyph) - **Skills**: `v` cycle view mode, `l` edit list limit in list mode - **Input Speed / Output Speed / Total Speed**: `w` edit the rolling window in seconds - **Custom Text / Custom Symbol**: `e` edit text or symbol - **Custom Command**: `e` command, `w` max width, `t` timeout, `p` preserve ANSI colors - **Link**: `u` URL, `e` link text - **Vim Mode**: `f` cycle format, `n` toggle Nerd Font icons ## Hiding Widgets Conditionally Widgets that can hide themselves share a single `h` (`(h)ideโ€ฆ`) keybind in the line editor. It opens a checklist of the hideable states the selected widget supports; toggle entries with `Space` and confirm with `Enter`. Enabled states appear in the editor as `(hide: no-git, zero)`. Supported states by widget family: - **Git widgets**: `no-git` hides the `(no git)` placeholder outside a repo - **Git count widgets** (`Git Changes`, `Git Insertions`, `Git Deletions`, `Git Staged/Unstaged/Untracked Files`, `Git Conflicts`): `zero` hides the widget while its count is zero - **JJ widgets**: `no-jj` hides the `(no jj)` placeholder outside a jj repo - **Git Origin widgets**: `no-remote` hides the `no remote` placeholder - **Git Upstream widgets / Git Ahead/Behind**: `no-upstream` hides the `no upstream` placeholder - **Git Ahead/Behind**: `zero` hides `โ†‘0โ†“0` when the branch is not diverged (enabled by default; uncheck it to show zeros) - **Git PR** (rendered as "MR" for GitLab origins): `no-data` hides the `(no PR)` placeholder, `status` and `title` hide those segments of the PR display - **Git CI Status**: `no-data` hides the `-` placeholder when the branch has no pull request or no readable check rollup - **Git Is Fork**: `not-fork` hides the widget when the repo is not a fork - **Token widgets**: `zero` hides `0` token counts at session start - **Session Cost**: `zero` hides `$0.00` - **Session Clock**: `zero` hides durations under one minute - **Block Timer**: `no-data` hides the `0hr 0m` / empty-bar display when no block is active - **Block Reset Timer / Weekly Reset Timer**: `no-data` hides both the `[Loading]` placeholder and the usage-error placeholders while no reset window is available - **Input/Output/Total Speed**: `no-data` hides the `โ€”` placeholder when no speed data exists - **Output Style**: `default-value` hides the widget when the style is `default` - **Compaction Counter**: `zero` hides the counter before any compaction occurs - **Skills**: `empty` hides the widget before any skill is used - **Extra Usage widgets**: `disabled` hides the `n/a` display when extra usage is off, `no-data` hides the error placeholder when usage data is unavailable - **Session / Weekly / Weekly Sonnet / Weekly Opus / Weekly Fable Usage**: `no-data` hides the error placeholder (`[No credentials]`, `[Timeout]`, `[Rate limited]`, `[API Error]`, `[Parse Error]`) when usage data is unavailable - **Cache widgets** (`Cache Hit Rate`, `Cache Read`, `Cache Write`, `Cache Timer`): `empty` hides the widget when there is no cache activity, and on Cache Timer when no cache anchor is available - **Custom Text / Custom Symbol**: `merge-target-hidden` hides the item when the widget it is merged with renders nothing, so icon prefixes/suffixes disappear together with their widget In `settings.json`, the enabled states are stored as a comma-separated list in the item's metadata, e.g. `"metadata": { "hide": "no-git,zero" }`. An empty list (`"hide": ""`) opts out of default-enabled states such as Git Ahead/Behind's `zero`. Configs from older versions that used per-widget boolean keys (`hideNoGit`, `hideNoJj`, `hideNoRemote`, `hideZero`, `hideWhenEmpty`, `hideIfDisabled`, `hideStatus`, `hideTitle`, `hideWhenNotFork`) are converted to the unified key automatically by the settings migration on first load. After that, downgrading to an older ccstatusline keeps the config readable, but older versions ignore the `hide` key, so previously hidden placeholders show again until you upgrade back. ## Custom Widgets ### Custom Text Widget Add static text to your status line. Perfect for: - Project identifiers - Environment indicators (dev/prod) - Personal labels or reminders ### Custom Symbol Widget Add a single symbol or emoji to your status line when you want a compact visual marker: - Nerd Font or Powerline-friendly glyphs - Status markers like `โ—`, `โœ“`, or `โš ` - Emoji shorthand for environments, workflows, or attention cues ### Custom Command Widget Execute shell commands and display their output dynamically: - Runs whenever Claude Code updates the status line by default; optionally reuse output with **Custom Command Cache TTL** under **Configure Status Line** (`customCommandCacheTtlSeconds`, `0-60` seconds, default `0`) - Receives the full Claude Code JSON data via stdin (model info, session ID, transcript path, etc.) - Also includes `terminal_width` โ€” the detected terminal width in columns, added by ccstatusline (omitted when it can't be determined) โ€” so scripts can adapt their output to the available space - Displays command output inline in your status line - Configurable timeout (default: 1000ms) - Optional max-width truncation - Optional ANSI color preservation (`preserve colors`) - Examples: - `pwd | xargs basename` - Show current directory name - `node -v` - Display Node.js version - `git rev-parse --short HEAD` - Show current commit hash - `date +%H:%M` - Display current time - `curl -s wttr.in?format="%t"` - Show current temperature - `npx -y ccusage@latest statusline` - Display Claude usage metrics (set timeout: 5000ms) - `cc-session-num` - Show current session rank (`#1`, `#2`, โ€ฆ) from [ccsessions](https://github.com/treebird7/ccsessions) With caching enabled, both output and failure markers are reused until the TTL expires. Entries are separated by command, working directory, session ID, terminal width, and timeout. Other stdin changes, such as token counts, do not invalidate an entry, so choose a TTL that suits how often the output needs to change. Without a session ID, reuse is limited to the current process. TUI previews show a command placeholder without executing it. > โš ๏ธ **Important:** Commands should complete quickly to avoid delays. Long-running commands are terminated at the configured timeout, and inherited output pipes cannot keep capture waiting indefinitely after that deadline. On Linux/macOS, timeout termination targets the command's process group; on Windows, it targets the shell process. If you're not seeing output from your custom command, try increasing the timeout value (press 't' in the editor). Rendered widget output filters terminal controls such as clipboard writes, title changes, cursor movement, and screen clearing. With **preserve colors** enabled, ANSI styling and OSC 8 hyperlinks remain supported; Powerline backgrounds are restored after command output resets its styling. Output capture is limited to 1 MiB; exceeding it displays `[Error]`. Successful output is limited to 16,384 characters before color handling and optional max-width truncation. > ๐Ÿ’ก **Tip:** Custom commands can be other Claude Code compatible status line formatters. They receive the same JSON via stdin that `ccstatusline` receives from Claude Code (augmented with a `terminal_width` field), allowing you to chain or combine multiple status line tools. ### Link Widget Create clickable links in terminals that support OSC 8 hyperlinks: - `metadata.url` - target URL (http/https) - `metadata.text` - optional display text (defaults to URL) - Falls back to plain text when URL is missing or unsupported ## Integration Example: ccusage [ccusage](https://github.com/ryoppippi/ccusage) is a tool that tracks and displays Claude Code usage metrics. You can integrate it directly into your status line: 1. Add a Custom Command widget 2. Set command: `npx -y ccusage@latest statusline` 3. Set timeout: `5000` (5 seconds for initial download) 4. Enable "preserve colors" to keep ccusage's color formatting > ๐Ÿ“„ **How it works:** The command receives Claude Code's JSON data via stdin, allowing ccusage to access session information, model details, and transcript data for accurate usage tracking. ## Integration Example: AIWatch [AIWatch](https://ai-watch.dev) monitors the live status of 30+ AI APIs and apps (Claude, GPT, Gemini, โ€ฆ). Surfacing it in your status line answers "is Claude slow because of me, or because the API is degraded?" without leaving the terminal. 1. Add a Custom Command widget 2. Set command: ```bash ( curl -sf --max-time 2 https://ai-watch.dev/api/status/cached | jq -r '[.services[] | select(.status != "operational") | "๐Ÿ”ด " + .name] | .[0:3] | join(" ")' ) 2>/dev/null || true ``` 3. Set timeout: `2000` (the `curl` itself caps at 2s; the outer `|| true` keeps the widget silent on any failure) 4. Leave "preserve colors" off โ€” the output is a plain emoji + name list When every tracked service is operational the command prints nothing, so the widget renders empty and manual separators collapse around it. The endpoint is JSON, CORS-enabled, and served with a ~5-minute cache. > ๐Ÿ“„ **Variants:** See [ai-watch.dev/#statusline](https://ai-watch.dev/#statusline) for count-only, compact, provider-scoped, and clickable OSC 8 link presets. ## Integration Example: ccsessions [ccsessions](https://github.com/treebird7/ccsessions) is a CLI session manager for Claude Code. Its companion script `cc-session-num` shows the current session's rank (`#1`, `#2`, โ€ฆ) matched against the same mtime-sorted list that `ccsessions` uses. 1. Install `cc-session-num`: ```bash curl -fsSL https://raw.githubusercontent.com/treebird7/ccsessions/main/cc-session-num \ -o ~/.local/bin/cc-session-num && chmod +x ~/.local/bin/cc-session-num ``` 2. Add a Custom Command widget 3. Set command: `cc-session-num` 4. Leave timeout at default (the script reads `~/.claude/projects/` locally and returns in milliseconds) The widget renders nothing when the current session isn't found, so manual separators collapse around it cleanly. > ๐Ÿ“„ **How it works:** `cc-session-num` reads `CLAUDE_CODE_SESSION_ID` from the environment (set by Claude Code), then ranks `~/.claude/projects/*/*.jsonl` files by modification time โ€” the same sort order `ccsessions` uses โ€” and prints the matching position. ## Smart Truncation When terminal width is detected, status lines automatically truncate with ellipsis (`...`) if they exceed the available width, preventing line wrapping. Truncation is ANSI/OSC-aware, so preserved color output and OSC 8 hyperlinks remain well-formed. --- ### WINDOWS (`docs/WINDOWS.md`) # Windows Support `ccstatusline` works on Windows across PowerShell (5.1+ and 7+), Command Prompt, and Windows Subsystem for Linux (WSL). If you want the main project overview, return to [README.md](../README.md). ## Installation on Windows ### Option 1: Using Bun (Recommended) ```powershell # Install Bun for Windows irm bun.sh/install.ps1 | iex # Run ccstatusline bunx -y ccstatusline@latest ``` ### Option 2: Using Node.js ```powershell # Using npm npx -y ccstatusline@latest ``` These commands launch the configuration TUI. To pin the install, start the TUI with `bunx -y ccstatusline@latest` or `npx -y ccstatusline@latest`, then choose **Pinned global install**. The TUI installs the active ccstatusline version globally with Bun or npm and configures Claude Code to run `ccstatusline`. After a pinned install, you can run `ccstatusline` directly to launch the TUI in the future. ## Claude Code Integration Configure `ccstatusline` in your Claude Code settings: **Settings location:** - Default: `%USERPROFILE%\.claude\settings.json` - Custom: set `CLAUDE_CONFIG_DIR` to use a different directory **PowerShell custom config example:** ```powershell $env:CLAUDE_CONFIG_DIR="C:\custom\path\.claude" ``` **For Bun users:** ```json { "statusLine": { "type": "command", "command": "bunx -y ccstatusline@latest", "padding": 0, "refreshInterval": 10 } } ``` **For npm users:** ```json { "statusLine": { "type": "command", "command": "npx -y ccstatusline@latest", "padding": 0, "refreshInterval": 10 } } ``` `refreshInterval` is optional and only supported by Claude Code >=2.1.97. You can configure it from ccstatusline's TUI after installation. The `bunx` and `npx` examples above follow `@latest`. If you choose **Pinned global install** in the TUI, it writes `"command": "ccstatusline"` instead after installing the selected version globally. You can also run `ccstatusline` directly for future TUI launches. ## Windows-Specific Features ### GitHub CI Status The **Git CI Status** widget requires the GitHub CLI to be installed and authenticated. It is GitHub-only and reads checks from the pull request associated with the current branch. ```powershell winget install --id GitHub.cli --source winget gh auth login ``` The widget displays `-` when the branch has no pull request, the pull request has no checks, or the authenticated token cannot read the check rollup. ### Powerline Font Support For optimal Powerline rendering on Windows: **Windows Terminal** (Recommended): - Supports Powerline fonts natively - Download from [Microsoft Store](https://aka.ms/terminal) - Auto-detects compatible fonts **PowerShell/Command Prompt**: ```powershell # Install JetBrains Mono Nerd Font via winget winget install DEVCOM.JetBrainsMonoNerdFont # Or download manually from: https://www.nerdfonts.com/font-downloads # Alternative: Download and install base JetBrains Mono font # from [JetBrains](https://www.jetbrains.com/lp/mono/) # or [GitHub](https://github.com/JetBrains/JetBrainsMono) # or [Google Fonts](https://fonts.google.com/specimen/JetBrains+Mono) ``` ### Helper Executables Git, JJ, GitHub/GitLab CLI, SSH, and the UTF-8 code-page helper are resolved from absolute directories in `PATH`. Empty and relative PATH entries are skipped, so a helper executable placed only in the current project directory is not selected. Install the tools you use in an absolute directory listed in `PATH`. ### Path Handling `ccstatusline` automatically handles Windows-specific paths: - Git repositories work with both `/` and `\` path separators - Current Working Directory widget displays Windows-style paths correctly - Full support for mapped network drives and UNC paths - Handles Windows drive letters (C:, D:, etc.) ## Windows Troubleshooting ### Common Issues & Solutions **Issue**: Status lines wrap because terminal width cannot be detected ```powershell # Set an explicit width before launching Claude Code $env:CCSTATUSLINE_WIDTH="160" claude ``` `CCSTATUSLINE_WIDTH` accepts a positive integer column width and is checked before automatic width detection. Set it in the same environment that starts Claude Code so the status line command inherits it. This is useful on Windows because native width probing is disabled when ccstatusline runs outside WSL. **Issue**: Powerline symbols showing as question marks or boxes ```powershell # Solution: Install a compatible Nerd Font winget install DEVCOM.JetBrainsMonoNerdFont # Then set the font in your terminal settings ``` **Issue**: Git commands not recognized ```powershell # Check if Git is installed and in PATH git --version # If not found, install Git: winget install Git.Git # Or download from: https://git-scm.com/download/win ``` **Issue**: Permission errors during installation ```powershell # Use non-global installation (recommended) npx -y ccstatusline@latest # Or run PowerShell as Administrator for global install ``` **Issue**: "Execution Policy" errors in PowerShell ```powershell # Temporarily allow script execution Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` **Issue**: Windows Defender blocking execution ```powershell # If Windows Defender flags the binary: # 1. Open Windows Security # 2. Go to "Virus & threat protection" # 3. Add exclusion for the ccstatusline binary location # Or use temporary bypass (not recommended for production): Add-MpPreference -ExclusionPath "$env:USERPROFILE\.bun\bin" ``` ## Windows Subsystem for Linux (WSL) `ccstatusline` works well in WSL environments: ```bash # Install in WSL Ubuntu/Debian curl -fsSL https://bun.sh/install | bash source ~/.bashrc bunx -y ccstatusline@latest ``` **WSL benefits:** - Native Unix-style path handling - Better font rendering in WSL terminals - Seamless integration with Linux development workflows ## Windows Terminal Configuration For the best experience, configure Windows Terminal with these recommended settings: ### Terminal Settings (`settings.json`) ```json { "profiles": { "defaults": { "font": { "face": "JetBrainsMono Nerd Font", "size": 12 }, "colorScheme": "One Half Dark" } } } ``` ## Performance on Windows `ccstatusline` includes Windows-specific runtime behavior: - **UTF-8 piped output fix**: In piped mode, it attempts to set code page `65001` for reliable symbol rendering - **Path compatibility**: Git and CWD widgets handle both `/` and `\` separators --- --- METRICS --- - Files Extracted: 4 - Estimated Token Budget: ~27504 tokens - Canonical Reference: https://codewiki.google/github.com/sirmalloc/ccstatusline