{"id":40700,"library":"ccstatusline","title":"ccstatusline","description":"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.","status":"active","version":"2.2.19","language":"javascript","source_language":"en","source_url":"https://github.com/sirmalloc/ccstatusline","tags":["javascript","claude","claude-code","cli","status-line","terminal"],"install":[{"cmd":"npm install ccstatusline","lang":"bash","label":"npm"},{"cmd":"yarn add ccstatusline","lang":"bash","label":"yarn"},{"cmd":"pnpm add ccstatusline","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ccstatusline is ESM-only; CommonJS require() will fail with ERR_REQUIRE_ESM.","wrong":"const ccstatusline = require('ccstatusline')","symbol":"default","correct":"import ccstatusline from 'ccstatusline'"},{"note":"The function uses camelCase, not snake_case.","wrong":"import { format_status_line } from 'ccstatusline'","symbol":"formatStatusLine","correct":"import { formatStatusLine } from 'ccstatusline'"},{"note":"Available since v2.0.0 for building custom widgets.","symbol":"createWidget","correct":"import { createWidget } from 'ccstatusline'"},{"note":"TypeScript consumers should use type import for configuration types.","symbol":"StatusLineConfig","correct":"import type { StatusLineConfig } from 'ccstatusline'"},{"note":"Use type import when defining custom widgets to avoid runtime overhead.","symbol":"WidgetDefinition","correct":"import type { WidgetDefinition } from 'ccstatusline'"}],"quickstart":{"code":"import ccstatusline, { formatStatusLine } from 'ccstatusline';\nimport { createWidget } from 'ccstatusline';\n\n// Basic usage: log formatted status line\nconst status = formatStatusLine({\n  hostname: true,\n  git: true,\n  model: 'claude-sonnet-4-20250514',\n  tokenUsage: { prompt: 150, completion: 80 },\n});\nconsole.log('ccstatusline output:', status);\n\n// Custom widget example\nconst uptimeWidget = createWidget({\n  name: 'uptime',\n  updateInterval: 60000,\n  render: () => `Uptime: ${Math.floor(process.uptime())}s`,\n});\n\nconst line = formatStatusLine({\n  widgets: [uptimeWidget],\n  separator: ' | ',\n});\nconsole.log(line);","lang":"typescript","description":"Shows how to import ccstatusline (ESM), format a status line with git/model/token info, and create a custom widget with intervals."},"warnings":[{"fix":"Switch to ESM imports (import ccstatusline from 'ccstatusline') or use dynamic import() in CJS contexts.","message":"ccstatusline v2.x dropped CommonJS support; require() fails with ERR_REQUIRE_ESM.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Uninstall auto-update version via TUI, then reinstall using the new pinned global install flow. Settings are preserved.","message":"Auto-updating install pattern is deprecated in favor of version pinned global installs.","severity":"deprecated","affected_versions":">=2.2.14"},{"fix":"Upgrade to >=2.2.14 which passes --no-optional-locks and caches Git output in ~/.cache/ccstatusline/git-cache.","message":"Git helpers create index.lock races in concurrent Claude Code sessions if not using the persistent cache.","severity":"gotcha","affected_versions":"<2.2.14"},{"fix":"Set CCSTATUSLINE_WIDTH environment variable to an explicit width (e.g., 80) before running Claude Code.","message":"Terminal width auto-detection fails in some CI or pipe environments; status line may truncate.","severity":"gotcha","affected_versions":"<2.2.14"},{"fix":"Upgrade to >=2.2.14 which sets windowsHide=true on helper commands. See docs/WINDOWS.md for additional steps.","message":"Windows users: child processes may flash console windows if not running recent versions.","severity":"gotcha","affected_versions":"<2.2.14"}],"env_vars":null,"search_vec":"'14.0.0':85 '2.2.19':29 'activ':31 'attest':82 'branch':16 'built':67 'cach':53 'ccstatuslin':1 'chain':77 'claud':8,69,92,94 'claude-cod':93 'cli':10,61,96 'code':9,70,95 'compat':56 'configur':73 'current':25 'customiz':3 'differenti':58 'display':12 'extra':40 'formatt':6 'generic':60 'git':15,52 'github':90 'go':48 'improv':57 'includ':37 'info':14 'javascript':91 'limit':50 'line':5,99 'local':72 'maintain':88 'metric':21 'model':13 'node.js':84 'npm':33,80 'overag':49 'pay':45 'pay-as-you-go':44 'persist':51 'pin':39 'proven':81 'purpos':66 'purpose-built':65 'recent':35 'releas':30 'requir':83 'secur':78 'stabl':26 'status':4,98 'status-lin':97 'suppli':76 'support':71 'termin':24,100 'token':17 'tool':62 'tui':74 'updat':36 'usag':18,41 'version':27,38 'via':79 'widget':42 'window':55","created_at":"2026-06-04T18:48:50.946944+00:00","updated_at":"2026-06-04T18:48:50.946944+00:00","problems":[{"fix":"Replace require('ccstatusline') with import 'ccstatusline' or use dynamic import('ccstatusline').","cause":"Trying to CommonJS require() an ESM-only module (v2.x+).","error":"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."},{"fix":"Ensure you use named import: import { formatStatusLine } from 'ccstatusline'.","cause":"Using wrong function name or importing default incorrectly.","error":"TypeError: (0 , _ccstatusline.formatStatusLine) is not a function"},{"fix":"Run 'npm install ccstatusline' in your project directory.","cause":"Package not installed or not in node_modules.","error":"Error: Cannot find module 'ccstatusline'"},{"fix":"Update ccstatusline to >=2.2.14 or set environment variable GIT_OPTIONAL_LOCKS=0.","cause":"Running older version (<2.2.14) with concurrent Git operations.","error":"ccstatusline: error: Git status race condition - index.lock exists"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/sirmalloc/ccstatusline#readme","github":"https://github.com/sirmalloc/ccstatusline","docs":null,"changelog":null,"pypi":null,"npm":"ccstatusline","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}