Development setup, project structure, and API documentation for ccstatusline.
If you want the main project overview, return to README.md.
- Bun (v1.0+)
- Git
- Node.js 14+ (optional, for running the built
dist/ccstatusline.jsbinary or npm publishing)
# Clone the repository
git clone https://github.com/sirmalloc/ccstatusline.git
cd ccstatusline
# Install dependencies
bun install# Run in TUI mode
bun run start
# Run in TUI mode with in-place reload: ctrl+r restarts on the latest code,
# keeping unsaved settings, the current screen and cursor. --config is
# optional and keeps a scratch setup separate from your real config.
CCSTATUSLINE_DEV_RELOAD=1 bun run start --config /tmp/ccstatusline-dev.json
# 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 docsWith CCSTATUSLINE_DEV_RELOAD=1, Ctrl+R restarts the interactive process with its original arguments, restoring unsaved settings, supported screens, and the selected line/widget. Confirmations, import/export, and install/update screens return to the main menu; transient editor drafts are not part of the snapshot. Reload is ignored while an action is in flight. After a crash, fix the code and press Enter to retry, or q to quit. The supervisor uses a private temporary snapshot directory and removes it when it exits; piped rendering is unaffected.
~/.config/ccstatusline/settings.json- ccstatusline UI/render settings~/.claude/settings.json- Claude Code settings (statusLinecommand 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-<profileHash>.jsonand~/.cache/ccstatusline/usage-<profileHash>.lock- per-profile usage API data cache and fetch backoff lock~/.cache/ccstatusline/usage-<profileHash>.credentials.lock- per-profile 30-second backoff after a usage credential lookup finds no OAuth login, also tagged with its credential source~/.cache/ccstatusline/usage-account.json- the account each usage login fingerprint belongs to (itself fingerprinted), looked up from/api/oauth/profilefor today's extra usage spend by the request Claude Account Email also makes~/.cache/ccstatusline/daily.jsonand~/.cache/ccstatusline/daily.json.lock- UTC-day extra-usage baselines and a nonblocking write lock; account/organization identity keeps the baseline stable across token refreshes when profile lookup succeeds~/.cache/ccstatusline/session-usage-history.jsonand~/.cache/ccstatusline/session-usage-history.json.lock- 5-hour usage readings for Block Forecast and Block Limit Timer, per Claude config directory and login, and the lock a render holds while writing them~/.cache/ccstatusline/account-email-<loginFingerprint>.json,.lock, and.inflight- owner-only Claude Account Email caches, independent failure backoffs, and exclusive in-flight leases per login~/.cache/ccstatusline/claude-status.jsonand~/.cache/ccstatusline/claude-status.lock- Claude service-status cache and failed-fetch backoff lock;claude-status.inflightcoordinates concurrent fetches~/.cache/ccstatusline/skills/skills-<sessionId>.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-<sha256(configDir)[:8]>, 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, then the same service scoped to os.userInfo().username if no OAuth token was found, then discovered suffixed services and the credentials file. If the OS username cannot be resolved, the account-scoped retry is skipped. Both access and refresh tokens are preserved for cache identity checks. Other platforms use the credentials file directly. Each Keychain subprocess has a five-second timeout; a timeout stops further Keychain probes for that lookup (including the username retry) and continues with the current profile’s credentials file, while an ordinary miss continues to the next source. A missing OAuth login triggers a profile-specific 30-second lookup backoff.
Usage file names use the first 16 hex characters of SHA-256 of path.resolve(getClaudeConfigDir()), including for the default profile. This file identity is separate from the raw environment value used for Keychain service selection. All usage cache freshness checks, stale reads, request locks, lock cleanup, and no-credentials backoff files use that profile's names. Profiles sharing one home keep independent data and backoff deadlines, even if they use the same login.
The old shared usage.json, usage.lock, and usage-credentials.lock files are ignored and left untouched. They are not migrated because the originating profile cannot be established reliably. Each profile starts with a cold cache and obtains its own data on the next eligible API lookup; legacy shared backoff deadlines are not carried over. The legacy empty-lock format is still supported within a profile's new lock file.
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. Top-level keys the schema no longer defines, such as the removed flexMode and compactThreshold, are dropped when settings are parsed, so they load without an error and disappear on the next save. 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.
A load that migrates an older config writes the result back only after it validates and after the original is copied to <settings path>.v<N>.bak beside the configured path (not the symlink target), recreated with the original's mode. A failed backup is not a load error: loadSettings() returns the migrated settings without writing them, minus any update message (counting one down rewrites the file), and getConfigLoadNotice() reports it for the TUI banner, with no status line badge or stderr output. Every load tries the backup again, and saveInstallationMetadata() skips its write. saveSettings() reads the file again before replacing it: if it still needs migrating, it backs up the bytes it holds now, under their own version, and throws without writing if that fails; if another run has migrated it in the meantime, that run's backup is left as it is. needsMigration() reads a version-less config as v1 only when it has none of the keys SettingsSchema gained over SettingsSchema_v1; otherwise known legacy widget hide flags are normalized in memory before validation as the current version, without changing widget IDs or rewriting the file on load. Import validation shares that check and takes merge keys from the file's own keys, before migration.
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 cache file 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.
Stale-cache fallback removes each expired window's usage and reset fields while retaining other usable fields. Partial fallback data can carry an error for missing required fields without suppressing widgets whose data remains valid. getUsageFetchedAtMs() preserves the original fetch time (disk-cache mtime for cached answers), rather than treating a stale read as a new observation.
- 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. Cumulative token totals deduplicate nonemptymessage.idvalues across the transcript, retaining the first counted input/cache snapshot and the maximum output count; records without IDs count independently. Speed collectors also deduplicate response IDs per transcript, use the latest input count and maximum output count, and keep separate active intervals for interleaved records so idle gaps do not become processing time. Session names prefer the latest validcustom-title, falling back to the latest validai-title. - 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. The transcript fallback scans relative to the config directory to preserve literal path characters, excludes sidechain and API-error rows, and extends its lookback when a gap may be filled by older transcripts. Future block starts and empty-cache deadlines more than one minute ahead are rejected after clock changes.
- Cache Timer prefers usable
prompt_cachestate from stdin:expires_atis a Unix timestamp in seconds,warm: falsemeans cold, andttl(5mor1h) controls glyph thresholds.caching_observed: falseor missing usable state falls back to the transcript tail; only this fallback shows the working state and estimates expiry using the configured TTL. 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.comthrough HTTPS, honorsHTTPS_PROXYunlessNO_PROXYexcludes 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 while that cache is under an hour old. - 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 asnull. Cache TTL starts at command completion so slow calls still receive the full reuse interval. Persistent writes use one stable.tmppath 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-boundghorglabcalls do not block rendering. Git CI Status adds GitHub'sstatusCheckRollup; if the authenticatedghtoken cannot read checks, the refresh retries with PR metadata only so Git PR still works. - Usage widgets merge Claude Code's stdin
rate_limitswith/api/oauth/usageonly for fields required by the active widgets. Session and aggregate weekly fields prefer the flat API buckets and fall back tolimits[]; per-model weekly fields preferweekly_scopedentries. A model-scoped entry reporting 0% withoutresets_atis valid zero usage, while unscoped empty placeholders remain filtered out.WEEKLY_MODEL_USAGE_BUCKETSinsrc/utils/usage-types.tsis 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 tosrc/widgets/shared/usage-percent-widget.ts; the Fable label isWeekly Fable:. Spend Limit Usage and Spend Limit Amount readrate_limits.spend_limitfrom stdin only (noUSAGE_WIDGET_REQUIREMENTSentry, so they never trigger an API fetch); the percentage widget goes through the same shared renderer withignoreApiErrorset and no time cursor. - Idle usage refresh dates stdin percentages from the transcript's last response. After three minutes,
usage-prefetch.tsalso requests the active widgets' percentage fields through the shared API cache. An API reading fetched after that response replaces a payload percentage only for the same reset window with no lower usage, or for a current window after the payload's window has reset. Failed requests preserve the payload values. - Block Forecast / Block Limit Timer share one
computeSessionForecastIfNeeded()call per render. With either widget configured, it records the block percentage in history scoped by config directory and login, then measures the last 30 minutes of usage with a minimum 10-minute span. Projections cap at 100%; the limit timer appears only when the projected limit precedes reset. Both hide once the block is at its limit, including the API-based limit check when the paired hide states require it. - Fast Mode reads only the boolean
fast_modefield from stdin and renders nothing when it is absent. - Claude Account Email asks
/api/oauth/profilewhich account the usage credentials belong to. Answers are cached under the usage cache's login fingerprint, so an access-token refresh reuses them and only a login change triggers another request. The same request names the account and organization that Extra Usage Today keeps the day's spend under (lookUpUsageAccount()), so with both widgets on a line a login is looked up once, and each keeps its part of the answer in its own cache. A lookup that fails, or leaves out the part its caller needs, backs off for that login only: 30 seconds, or after a 429 the server'sRetry-After(five minutes without one, a day at most).fetchAccountEmail()distinguishes an available email, no OAuth credentials, and an unavailable email for an existing login. Only the no-credentials case falls back tooauthAccount.emailAddressin.claude.json; a failed or backed-off lookup for an existing login hides the widget. Independent lock files retain each login’s deadline across alternating failures and access-token refreshes. An exclusive 30-second lease coordinates requests and writes for each login; the request itself still has a five-second deadline. Expired owners cannot write results, and a failure never shortens an existing valid backoff. Cache entries are written atomically to separate owner-only files, so concurrent logins cannot discard each other’s answers. Matching entries in the old sharedaccount-email.jsonremain readable; the shared file is never rewritten. - Custom Command delegates to
src/utils/custom-command.ts.customCommandCacheTtlSecondsdefaults to0(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. Persistent writes use one stable.tmppath per cache file with best-effort cleanup on failure, as the Git cache does. - Terminal width is memoized once per render, including a
nullprobe result. Linux first probes ancestor terminal devices through/procandtty.WriteStream; portable fallbacks useexecFileSyncforpsandstty.CCSTATUSLINE_WIDTHtakes precedence, then theCOLUMNSvariable Claude Code (2.1.153+) sets for the statusline; both apply on Windows where probing is disabled and skip the no-width cache. Only no-width results are persisted per session, forterminalWidthCacheTtlSeconds(default 5, range 0–300);0disables cross-process reuse. Numeric widths are re-probed on the next render. Cache writes use one stable.tmppath with best-effort cleanup on failure, as the Git cache does. The renderer truncates and expands flex separators against that width minus 5 columns, in piped output and the TUI preview alike. - Context length transcript fallback treats the latest
compact_boundaryas the start of the current context. It uses the first main-chain usage entry after that boundary, thencompactMetadata.postTokens, then zero, while session token totals remain cumulative. - Sandbox Status reads
sandbox.enabledfrom Claude Code's layered project-local, project, user-local, and user settings on every refresh. This reflects/sandboxfile 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.
Usage, account profile, service-status and update-check (npm registry) requests honor uppercase HTTPS_PROXY and share isExcludedFromProxy() for the NO_PROXY/no_proxy rules described in Usage. Each request has a total five-second deadline; the usage, account profile and service-status requests also set a 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.
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.
formatUsageBar() in shared/usage-display.ts centralizes percentage/bar formatting, and shared/context-percentage-widget-base.ts shares the context-percentage widgets' editor behavior. Thinking Effort opts into colorsOnlyItsRuns() so its explicit level colors coexist with the renderer's label and bracket colors; defaults and unknown levels retain the widget color, while a global foreground override still takes precedence.
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. Return undefined in modes that do not support label editing; the editor offers e only when a label prefix is available and raw mode is off.
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.
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, and newlines; tabs become single spaces, matching the one column width measurement gives them; 8-bit SGR and OSC 8 forms are normalized to their 7-bit equivalents, while other terminal sequences are removed whole. 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. The hooks follow the config that command loads: the path after its --config, read as the shell passes it on (getStatusLineConfigPath()), or else the default config. A wrapper script counts as loading the default config unless the command passes it --config. Saving any other config, such as one opened with --config for testing, leaves the hooks as they are. syncWidgetHooks() and saveSettings() return SkippedWidgetHooks when an existing non-ccstatusline command prevents needed hooks from being added, so both save flows can name the affected widgets and explain wrapper setup. If a wrapper drops the --hook argument, piped input with a supported hook_event_name (PreToolUse or UserPromptSubmit) and a nonempty session_id is dispatched to the hook handler before status validation, without rendering a status line.
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.
- 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) postbuildreplaces the bundled__PACKAGE_VERSION__placeholder frompackage.json;ccstatusline --versionreads that value and exits before mode detection- During install,
ink@6.2.0is patched to fix backspace handling on macOS terminals and to re-measure a text when a string is inserted before an existing part of it (fixed upstream in ink 6.8.0) - React and React DOM are exact-version pins; dependency refreshes should update
package.jsonandbun.locktogether
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
To generate the API documentation locally:
# Generate documentation
bun run docs
# Clean generated documentation
bun run docs:cleanThe documentation will be generated in the typedoc/ directory and can be viewed by opening typedoc/index.html in your web browser.
- 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
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