Skip to content

Latest commit

 

History

History
229 lines (165 loc) · 29.6 KB

DEVELOPMENT.md

File metadata and controls

229 lines (165 loc) · 29.6 KB

Development

Development setup, project structure, and API documentation for ccstatusline.

If you want the main project overview, return to README.md.

Prerequisites

  • Bun (v1.0+)
  • Git
  • Node.js 14+ (optional, for running the built dist/ccstatusline.js binary or npm publishing)

Setup

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

# Install dependencies
bun install

Development Commands

# 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 docs

With 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.

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-<profileHash>.json and ~/.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/profile for today's extra usage spend by the request Claude Account Email also makes
  • ~/.cache/ccstatusline/daily.json and ~/.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.json and ~/.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.json and ~/.cache/ccstatusline/claude-status.lock - Claude service-status cache and failed-fetch backoff lock; claude-status.inflight coordinates 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.

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. Cumulative token totals deduplicate nonempty message.id values 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 valid custom-title, falling back to the latest valid ai-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_cache state from stdin: expires_at is a Unix timestamp in seconds, warm: false means cold, and ttl (5m or 1h) controls glyph thresholds. caching_observed: false or 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.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 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 as null. Cache TTL starts at command completion so slow calls still receive the full reuse interval. 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.
  • Idle usage refresh dates stdin percentages from the transcript's last response. After three minutes, usage-prefetch.ts also 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_mode field from stdin and renders nothing when it is absent.
  • Claude Account Email asks /api/oauth/profile which 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's Retry-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 to oauthAccount.emailAddress in .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 shared account-email.json remain readable; the shared file is never rewritten.
  • 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. Persistent writes use one stable .tmp path per cache file with best-effort cleanup on failure, as the Git cache does.
  • 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, then the COLUMNS variable 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, for terminalWidthCacheTtlSeconds (default 5, range 0–300); 0 disables cross-process reuse. Numeric widths are re-probed on the next render. Cache writes use one stable .tmp path 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_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.

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.

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.

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.

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, 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.

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 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.json and bun.lock together

API Documentation

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:

# 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

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