ccstatuslineはClaude Codeの表示をウィジェット単位で組み替える

表示を固定値から構成へ

ccstatuslineはClaude Code CLIのステータスラインを整形するTypeScript製ツールです。READMEの特徴は、複数の独立したライン、ウィジェットの追加・削除・並べ替え、色、区切り文字、カスタムテキスト、リアルタイムプレビューをTUIで編集できることです。多機能であることと値の正確性は別なので、表示された使用量やGit状態の取得元を個別に確認します。

npxと固定版インストール

初回はnpx -y ccstatusline@latestまたはbunx -y ccstatusline@latestでTUIを起動でき、READMEはグローバルインストール不要と説明します。Pinned global installを選ぶと、実行中の版を固定してClaude Code設定にcommandを登録します。latest追従と固定版には更新の扱いに差があるため、チーム運用ではsettings.jsonと実行版を一緒に管理します。

ウィジェットの情報源

Gitブランチ、PRやMR、ステージ状態、挿入削除行数、セッションと週次使用量、コンテキスト長、コンパクション、タイマー、メモリ、トークン速度、Vimモード、セッション名、コスト、作業ディレクトリなどが更新履歴に挙がります。READMEは現行版の完全な一覧ではないため、TUIで選択できる項目と実際のClaude Code版を組み合わせて確認します。

キャッシュで表示を止めない

Git PR/CIウィジェットは版付きディスクキャッシュから描画し、古い値をバックグラウンドで再取得します。Gitヘルパーは--no-optional-locksを使い、キャッシュは~/.cache/ccstatusline/git-cacheに置かれ、.git/HEADと.git/indexのmtimeが検査されます。利便性のためのキャッシュであり、リアルタイム性の保証ではありません。古い表示と更新中の表示をテストします。

版差と環境変数

refreshIntervalの書き込みはClaude Code 2.1.97以降だけとREADMEにあります。CLAUDE_CONFIG_DIRは設定場所、HTTPS_PROXYは使用量ウィジェット、CCSTATUSLINE_WIDTHは端末幅、CCSTATUSLINE_CONTEXT_SIZE_FALLBACKはコンテキストサイズ不明時の既定値に使います。Windows、PowerShell、WSL、フォントの注意点もあるため、端末環境を変えたら表示幅と設定パスを再確認します。

MITライセンスと評価方法

MITライセンスで、リリースv2.2.27では設定のインポートとエクスポートが扱われています。評価では、Git状態を変更して表示更新を観察し、APIを遮断したときの使用量ウィジェットの表示、無効なsettings.jsonを置いたときにファイルを壊さず既定値を描画するか、/compact後のコンテキスト値が戻るかを確認します。表示の便利さと監視用途の信頼性を混同しません。

最初はnpxでTUIを起動し、Gitブランチ、作業ディレクトリ、コンテキスト、タイマーの少数ウィジェットだけを置きます。settings.jsonを保存してClaude Codeのcommand設定と照合し、固定版インストールへ切り替えた際に実行版が変わらないことを確認します。Gitのステージ、未追跡、HEAD変更を順に作り、キャッシュ更新前後の表示とmtimeの関係を観察します。HTTPS_PROXYを無効にしたとき使用量ウィジェットがどう表示されるか、無効な設定JSONで既存ファイルが保持されるかも確認します。端末幅をCCSTATUSLINE_WIDTHで固定し、WindowsやWSLでは設定パス、フォント、PowerShellの起動結果を別記録にします。

ステータスラインは見た目より、情報が古いときに利用者が誤解しないことを評価します。Gitリポジトリの大きさやネットワーク遅延を変え、キャッシュから表示される値に更新時刻を示せるかを確認します。使用量APIが空の応答や項目の違う応答を返すケースで、フォールバックが崩れないかを調べます。複数ラインと長いブランチ名では幅がはみ出さないか、カスタムテキストが重要な状態を隠さないかを端末幅ごとに確認します。設定をエクスポートして別端末へ移し、秘密情報を意図せず含まないことも確認します。

表示の更新間隔は、利用者が必要とする判断時間に合わせます。古いGitや使用量の値を現在値と誤認しないよう、重要な作業では元のCLIやGitコマンドを併用して照合します。

ccstatuslineの検証では、表示が空や古い場合の意味を決めます。TUIの設定を持ち運ぶ前に、設定ファイルに秘密値がなく、端末幅とClaude Codeの版が適合することを確認します。

導入前には、対象版のリリースと実行環境を記録します。入力と出力を固定した小さな試験を作り、成功だけでなく失敗時の状態も保存します。設定ファイルの既定値を確認し、変更した値を一覧にします。権限は必要な範囲に絞り、管理者操作と通常利用を分けます。ログには時刻、版、対象、結果を残します。外部サービスを使う場合は通信先と認証の境界を確認します。更新時は同じ試験を再実行し、以前の結果との差を見ます。素材にない性能や安全性を数値として補いません。READMEの機能説明と実際の動作が異なる場合は、動作を優先して原因を調べます。

編集部の結論

Claude Codeの反復作業中に、Git状態や使用量、コンテキストを一つの表示で見たい開発者に向きます。表示値の取得元や更新遅延を監視システムの代わりに扱う用途には不向きです。まずnpxのTUIで設定を作り、settings.json、Claude Code側のcommand、Gitキャッシュ、使用量APIの失敗時表示を確認し、必要なウィジェットだけを有効にします。

公式情報源

1. Official README
2. Project repository
3. Release notes