ccstatusline

library2.2.19jsnpmunverified

A customizable status line formatter for Claude Code CLI that displays model info, git branch, token usage, and other metrics in the terminal. Current stable version is 2.2.19, released actively on npm with recent updates including version pinning, extra usage widgets for pay-as-you-go overage limits, persistent Git caching, and Windows compatibility improvements. Differentiates from generic CLI tools by being purpose-built for Claude Code, supporting localization, configurable TUI, and supply chain security via npm provenance attestations. Requires Node.js >=14.0.0 and is maintained on GitHub.

devops

npm install ccstatusline

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CCSTATUSLINE

ccstatusline

devopsjavascriptv2.2.19

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import ccstatusline from 'ccstatusline'

✗ const ccstatusline = require('ccstatusline')

ccstatusline is ESM-only; CommonJS require() will fail with ERR_REQUIRE_ESM.

formatStatusLine

✓ import { formatStatusLine } from 'ccstatusline'

✗ import { format_status_line } from 'ccstatusline'

The function uses camelCase, not snake_case.

createWidget

✓ import { createWidget } from 'ccstatusline'

Available since v2.0.0 for building custom widgets.

StatusLineConfig

✓ import type { StatusLineConfig } from 'ccstatusline'

TypeScript consumers should use type import for configuration types.

WidgetDefinition

✓ import type { WidgetDefinition } from 'ccstatusline'

Use type import when defining custom widgets to avoid runtime overhead.

Shows how to import ccstatusline (ESM), format a status line with git/model/token info, and create a custom widget with intervals.

import ccstatusline, { formatStatusLine } from 'ccstatusline'; import { createWidget } from 'ccstatusline'; // Basic usage: log formatted status line const status = formatStatusLine({ hostname: true, git: true, model: 'claude-sonnet-4-20250514', tokenUsage: { prompt: 150, completion: 80 }, }); console.log('ccstatusline output:', status); // Custom widget example const uptimeWidget = createWidget({ name: 'uptime', updateInterval: 60000, render: () => `Uptime: ${Math.floor(process.uptime())}s`, }); const line = formatStatusLine({ widgets: [uptimeWidget], separator: ' | ', }); console.log(line);

Debug

Known issues

breakingccstatusline v2.x dropped CommonJS support; require() fails with ERR_REQUIRE_ESM.

fix

Switch to ESM imports (import ccstatusline from 'ccstatusline') or use dynamic import() in CJS contexts.

affects: >=2.0.0

deprecatedAuto-updating install pattern is deprecated in favor of version pinned global installs.

fix

Uninstall auto-update version via TUI, then reinstall using the new pinned global install flow. Settings are preserved.

affects: >=2.2.14

gotchaGit helpers create index.lock races in concurrent Claude Code sessions if not using the persistent cache.

fix

Upgrade to >=2.2.14 which passes --no-optional-locks and caches Git output in ~/.cache/ccstatusline/git-cache.

affects: <2.2.14

gotchaTerminal width auto-detection fails in some CI or pipe environments; status line may truncate.

fix

Set CCSTATUSLINE_WIDTH environment variable to an explicit width (e.g., 80) before running Claude Code.

affects: <2.2.14

gotchaWindows users: child processes may flash console windows if not running recent versions.

fix

Upgrade to >=2.2.14 which sets windowsHide=true on helper commands. See docs/WINDOWS.md for additional steps.

affects: <2.2.14

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/ccstatusline/index.js from /path/to/script.js not supported. Instead change the require of index.js to a dynamic import() which is available in all CommonJS modules.

Trying to CommonJS require() an ESM-only module (v2.x+).

fix

Replace require('ccstatusline') with import 'ccstatusline' or use dynamic import('ccstatusline').

TypeError: (0 , _ccstatusline.formatStatusLine) is not a function

Using wrong function name or importing default incorrectly.

fix

Ensure you use named import: import { formatStatusLine } from 'ccstatusline'.

Error: Cannot find module 'ccstatusline'

Package not installed or not in node_modules.

fix

Run 'npm install ccstatusline' in your project directory.

ccstatusline: error: Git status race condition - index.lock exists

Running older version (<2.2.14) with concurrent Git operations.

fix

Update ccstatusline to >=2.2.14 or set environment variable GIT_OPTIONAL_LOCKS=0.

Upgrade

Version history

2.2.19latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/sirmalloc/ccstatusline ↗

packageccstatusline ↗

homepagehttps://github.com/sirmalloc/ccstatusline#readme ↗