Claude Code statusline の設定方法:自作スクリプトと表示されないときの確認
Claude Code のステータスラインは、セッションの JSON を受け取るコマンドで作れます。すぐ試すなら /statusline、自分で表示を管理するなら手動設定を使い、先に模擬入力で出力を確認しましょう。
目次

Claude Code のステータスラインは、画面下部にモデル名や作業フォルダー、コンテキスト使用率などを表示する機能です。すぐに作るなら /statusline に表示したい内容を伝えます。実行する処理を自分で管理したい場合は、スクリプトを用意して設定ファイルの statusLine に登録します。
仕組みはシンプルです。Claude Code がセッション情報の JSON を標準入力(stdin)に渡し、コマンドが標準出力(stdout)に書いた文字を表示します。以下の自作例は、モデル名・作業場所・Git ブランチ・コンテキスト・推定コストを一行にまとめ、対象アカウントで渡される利用率も表示します。最初に模擬 JSON で確認できるので、表示されない原因をスクリプトと Claude Code の設定に分けて調べられます。公式の statusline ガイド
/statusline と手動設定、どちらを使う?
| 方法 | 選ぶ場面 | 確認すること |
|---|---|---|
/statusline | 個人用の表示をすぐ作りたい | 生成されたスクリプトと設定変更の内容 |
手動 statusLine | 表示項目や欠損時の動作を管理したい | 同じコマンドが模擬入力で一行を返すか |
| プロジェクトで共有 | チームで同じ表示を使いたい | スクリプト、実行環境、パスを全員が使えるか |
ccstatusline などのツール | テーマや複数行のレイアウトを選びたい | 導入する依存関係と、各表示項目が読むデータ |
/statusline は Claude Code 内で実行します。たとえば、次のように依頼できます。
/statusline モデル名、現在のフォルダー、Gitブランチ、コンテキスト使用率、推定コストを一行で表示してください。値がない項目は「--」にしてください。生成後はスクリプトの保存先と中身を確認します。ローカルで実行するコマンドなので、必要のない外部通信や個人情報の読み取りまで追加されていないかを見ておくと、後から管理しやすくなります。チームで共有するなら、個人の絶対パスをそのままコミットせず、共有用の設定とスクリプトをそろえます。
手動設定:JSON を読み、一行を返すスクリプトを作る

ここでは Node.js を使います。Node.js と、ブランチを表示したい場合は Git が必要です。 Claude Code をネイティブ版でインストールしていても、Node.js が別途入っているとは限りません。ターミナルで node --version が動くことを確認してください。
まず、次の全体を statusline.cjs として保存します。個人用の保存先の例は ~/.claude/statusline.cjs です。Windows ではユーザーフォルダー内の .claude/statusline.cjs に置けます。
const fs = require("node:fs");
const { spawnSync } = require("node:child_process");
const object = (value) =>
value && typeof value === "object" && !Array.isArray(value)
? value
: {};
const number = (value) =>
typeof value === "number" && Number.isFinite(value);
const text = (value) =>
typeof value === "string"
? value.replace(/[\u0000-\u001f\u007f|]/g, " ").trim()
: "";
let data;
try {
const input = fs.readFileSync(0, "utf8").replace(/^\uFEFF/, "");
data = object(JSON.parse(input.trim() || "{}"));
} catch {
console.error("statusline: 入力JSONを読めません");
process.exit(1);
}
const model = object(data.model);
const workspace = object(data.workspace);
const context = object(data.context_window);
const cost = object(data.cost);
const limits = object(data.rate_limits);
const cwd = text(workspace.current_dir) || text(data.cwd);
const folder = cwd.split(/[\\/]/).filter(Boolean).pop() || "workspace?";
function gitBranch(directory) {
if (!directory) return "--";
const run = (args) => spawnSync("git", ["-C", directory, ...args], {
encoding: "utf8",
timeout: 200,
maxBuffer: 8192,
windowsHide: true,
});
const branch = run(["symbolic-ref", "--quiet", "--short", "HEAD"]);
if (branch.status === 0) return text(branch.stdout) || "--";
const commit = run(["rev-parse", "--verify", "--short", "HEAD"]);
return commit.status === 0
? `detached:${text(commit.stdout)}`
: "--";
}
function usage(window) {
const value = object(window);
const now = Date.now() / 1000;
if (!number(value.used_percentage) || value.used_percentage < 0 ||
!number(value.resets_at) || value.resets_at <= now) return "--";
return `${Math.round(value.used_percentage)}%`;
}
const ctx = number(context.used_percentage) && context.used_percentage >= 0
? `${Math.round(context.used_percentage)}%` : "--";
const estimate = number(cost.total_cost_usd) && cost.total_cost_usd >= 0
? `USD ${cost.total_cost_usd.toFixed(2)} est` : "USD -- est";
const line = [
text(model.display_name) || text(model.id) || "model?",
folder,
`git:${gitBranch(cwd)}`,
`ctx:${ctx}`,
estimate,
`5h:${usage(limits.five_hour)}`,
`7d:${usage(limits.seven_day)}`,
];
process.stdout.write(line.join(" | ") + "\n");この例の -- は「有効な値を取得できない」という意味です。数値の 0 は 0% や USD 0.00 est のまま表示し、null と区別します。利用率のリセット日時を過ぎた値も -- にします。
Git の通常のブランチ名は、入力 JSON にあると仮定せず、渡された作業ディレクトリを git -C で読み取ります。現在のスキーマに汎用的な git.branch はありません。このスクリプトはブランチ名、または detached HEAD の短いコミット ID を表示します。未コミットの新規リポジトリでもブランチ名は取得できます。Git がない、ディレクトリが存在しない、リポジトリ外、タイムアウトなどの場合は git:-- に戻ります。変更ファイルの有無は調べません。
模擬 JSON で出力を確認する
次を mock.json として、スクリプトとは別の作業用フォルダーに保存します。値は動作確認用で、実際の利用量や請求額ではありません。resets_at は将来の日時を表す UNIX 秒です。
{
"model": {"display_name": "Claude Sonnet"},
"workspace": {"current_dir": "/example/demo"},
"context_window": {"used_percentage": 42},
"cost": {"total_cost_usd": 0.18},
"rate_limits": {
"five_hour": {"used_percentage": 30, "resets_at": 4102444800},
"seven_day": null
}
}macOS/Linux では、保存したフォルダーから実行します。
node "$HOME/.claude/statusline.cjs" < mock.jsonWindows の PowerShell では、同じファイルを UTF-8 で読み込んで渡します。
Get-Content -Raw -Encoding UTF8 .\mock.json | node "$HOME/.claude/statusline.cjs"/example/demo が Git リポジトリではない場合、期待する出力は次の一行です。
Claude Sonnet | demo | git:-- | ctx:42% | USD 0.18 est | 5h:30% | 7d:--mock.json の current_dir を手元のリポジトリの絶対パスに変えると、Git の表示も確認できます。Windows の JSON 内では C:/work/demo のように / を使うと、バックスラッシュのエスケープを避けられます。
さらに used_percentage を null と 0 に変えて、ctx:-- と ctx:0% が分かれることを確認してください。{} だけでも例外を出さずに一行を返します。壊れた JSON は診断を stderr に出して終了するので、成功した出力と混ざりません。本稿のスクリプトは模擬入力で出力と欠損時の処理を確認しています。この確認は Windows 上の Claude Code の描画や、実アカウントの利用量を確認したものではありません。
statusLine にコマンドを登録する
個人設定は ~/.claude/settings.json です。既存の JSON のほかの項目を残し、次の statusLine を追加または変更します。以下は設定の断片なので、ファイル全体を置き換えないでください。
{
"statusLine": {
"type": "command",
"command": "node \"/Users/you/.claude/statusline.cjs\""
}
}/Users/you/... は自分の保存先へ置き換えます。Linux なら /home/you/... などになります。この形では Node.js がファイルを読むため、スクリプト自身に実行権限を付ける chmod +x は不要です。ファイルを直接実行する方式を選んだ場合は、適切な shebang と実行権限が必要になります。
設定を保存し、次の更新時に一行が出れば、Claude Code との接続まで確認できています。statusLine.command の変更は即座に実行されますが、スクリプトの中身だけを変更した場合は次の更新契機を待ちます。初回の応答前はコンテキストや利用率が -- でも異常とは限りません。設定と更新の仕様
Windows:実行するシェルとパスをそろえる
現在の公式仕様では、Windows は Git Bash があればそれを使い、なければ PowerShell を使います。「Windows は常に cmd」「PowerShell では実行できない」という前提で設定を直す必要はありません。公式の Windows 設定例
上の Node.js スクリプトを使うなら、設定はたとえば次の形にできます。Node.js の実際のインストール先とユーザー名に合わせてください。
{
"statusLine": {
"type": "command",
"command": "\"C:/Program Files/nodejs/node.exe\" \"C:/Users/you/.claude/statusline.cjs\""
}
}パスは / 区切りにし、空白のあるパスは引用符で囲みます。ターミナルで node が動いても、Claude Code が起動する環境の PATH が同じとは限りません。まず絶対パスでインタープリターを指定すると、切り分けやすくなります。PowerShell スクリプトを自作する場合は、公式にも powershell -NoProfile -File で明示的に起動する例があります。
日本語だけが文字化けする場合は、ファイルを UTF-8 で保存し、まず同じコマンドに同じ mock.json を渡して確認します。ここで正しくても、実際のターミナル表示は別途確認が必要です。最初は色や特殊な記号を足さずに、一行の文字列を表示させると原因を絞れます。
フィールドの読み方:コンテキスト、利用率、コストは別の値
次の主要フィールドは、2026年10月7日に確認した公式 JSON スキーマに基づきます。フィールドが存在しない状態も考慮して読み取ります。
| 表示したい内容 | 読み取る項目 | 意味・注意点 |
|---|---|---|
| モデル名 | model.display_name、代替に model.id | model は文字列ではなくオブジェクト |
| 現在の作業場所 | workspace.current_dir、cwd | 起動時の場所を示す workspace.project_dir とは異なる場合がある |
| コンテキスト使用率 | context_window.used_percentage | 最新の API 応答時点。旧例の percentage は使わない |
| セッションの推定コスト | cost.total_cost_usd | クライアント側の価格情報に基づく見積もり |
| 5時間・7日間の利用率 | rate_limits.five_hour.used_percentage、rate_limits.seven_day.used_percentage | 消費済みの割合。対応アカウントで渡される |
| 利用率のリセット日時 | 各期間の resets_at | UNIX 秒。JavaScript の日時へ変換するなら 1,000 を掛ける |
コンテキスト使用率は、週間の消費率ではありません
context_window は最新の API 応答に対応する現在のコンテキストを表します。入力トークン数には input_tokens、cache_creation_input_tokens、cache_read_input_tokens を足した値が使われ、used_percentage の計算に出力トークンは含まれません。セッション全体の累計や、契約プランの利用枠を表す値ではありません。
/context はまだ送信していない新しいメッセージの推定分も加えるため、ステータスラインより大きい値になることがあります。また、最初の API 応答前や /compact の直後から次の応答まで、current_usage や割合が null になる場合があります。ここで -- が出るなら、ゼロに書き換えるより、次の応答後に値が入るかを確認します。コンテキストの計算と欠損時の仕様
Pro/Max の利用率を表示できる条件
rate_limits は claude.ai の Pro/Max 契約、または支出制限のある Claude apps gateway で、最初の API 応答後に提供されます。5時間、7日間、支出制限の各項目はそれぞれ欠けることがあり、リセット日時を過ぎた期間の項目は削除されます。used_percentage は使った割合なので、30% は「残り30%」ではありません。
項目がないことは、利用量ゼロ、無制限、API キーの異常のどれも意味しません。現在のコンテキストを仮のトークン上限で割って、プランの消費率に換算する方法も使いません。利用率が渡される条件
gateway の spend_limit は別の支出制限で、割合が100%を超えることもあります。割合は v2.1.251 以降の機能です。金額や期間の項目を利用するには、クライアントと gateway の両方で v2.1.284 以降が必要です。金額は任意で、割合より遅れて更新される場合もあります。上の最小スクリプトでは、5時間と7日間の項目だけを表示しています。
コスト表示を請求額として扱わない
cost.total_cost_usd はセッションの推定値です。請求書の金額や、どの認証情報の所有者へ課金されたかを証明するものではありません。v2.1.211 以降では /clear による新規セッションでゼロから始まり、それ以前の版では引き継がれていました。
所要時間を追加するなら、cost.total_duration_ms と cost.total_api_duration_ms の単位にも注意します。前者は再開を含む稼働時間で、セッション停止中の時間は除きます。後者は API 待機時間です。いずれもミリ秒なので、秒で出すなら 1,000 で割ります。コストと時間のフィールド
設定が上書きされるときはスコープを確認する
個人用はユーザー設定、プロジェクトでの個人差はローカル設定、チームで共有する内容は共有プロジェクト設定に置きます。通常のファイル名は次のとおりです。
| 設定 | 主な保存先 | 用途 |
|---|---|---|
| ユーザー設定 | ~/.claude/settings.json | このマシン上の個人用既定値 |
| プロジェクトのローカル設定 | .claude/settings.local.json | 個人のパスや実行環境に合わせる |
| 共有プロジェクト設定 | .claude/settings.json | チームで共有するコマンド |
| 管理設定 | 組織が配布する設定 | 管理者が決める動作や制限 |
同じキーの優先順位は、管理設定 → --settings → プロジェクトのローカル設定 → 共有プロジェクト設定 → ユーザー設定です。上位に指定がないキーには下位の値が使われます。/status の Setting sources で読み込まれたファイルを確認できますが、各キーがどのファイルから採用されたかを個別に示す一覧ではありません。設定のスコープと優先順位
Git/worktree ではローカル設定の場所がメインのチェックアウト側になる場合があります。共有設定は主作業ディレクトリから読み込まれ、v2.1.246 以降の /cd では移動先の設定も読み直します。見つけた .claude ファイルをすべて同じ場所の設定と扱わず、実際に読み込まれたファイルを確かめます。
チームで共有するなら、スクリプトもリポジトリ内に置き、Node.js の必要性、実行時のパス、読んでいるデータをそろえます。ユーザー名入りの絶対パスや秘密情報を共有設定へ含めないようにします。無効にするときは statusLine の項目だけを削除するか、/statusline に解除を依頼し、ほかの設定を残します。
古い表示を直す:イベント更新とタイマーの違い
通常は起動・再開、アシスタントのメッセージ、/compact の完了などで更新されます。変更は300msでまとめられ、新しい更新が来ると実行中のスクリプトはキャンセルされます。長い処理を毎回走らせると、完了前に次の更新が来ることがあります。更新タイミング
時計や外部の状態など、Claude Code が待機中でも変わる項目を表示する場合は refreshInterval を秒単位で追加できます。最小値は1秒です。たとえば5秒ごとにスクリプトを再実行する設定は次の形です。
{
"statusLine": {
"type": "command",
"command": "node \"/Users/you/.claude/statusline.cjs\"",
"refreshInterval": 5
}
}タイマーで再実行しても、最新の API 応答から来たコンテキストの数値まで新しくなるわけではありません。スクリプトだけが再実行されないのか、入力値自体が更新されていないのかを分けます。上の例はキャッシュを作らず、Git の読み取りにもタイムアウトを付けています。重い処理を追加する場合は、まずそれを外して差を見ると切り分けやすくなります。
表示の余白を追加する padding は任意で、既定値は 0 です。Vim の状態表示を自作の行へまとめたい場合は、hideVimModeIndicator で組み込みのインジケーターを隠せます。どちらも statusLine の中に置く表示用の設定です。
出力の幅を調整するなら、Claude Code が渡す COLUMNS や LINES を利用できます。出力は TTY に直結していないため、tput cols などでターミナル幅を取得する前提は避けます。複数行、ANSI 色、OSC 8 のリンクも対応していますが、端末の機能によります。たとえば macOS の Terminal.app は OSC 8 リンクをクリックできません。狭い画面や通知で行が切れる場合は、不要な項目を減らします。
表示されない・空白になるときの確認順

まず、設定に書いたものと同じコマンドへ mock.json を渡します。macOS/Linux で stdout と stderr を分けるなら、次のように確認できます。
node "$HOME/.claude/statusline.cjs" < mock.json > statusline.out 2> statusline.err
echo $?
cat statusline.out
cat statusline.err正常なら終了コードは 0、statusline.out に一行、statusline.err は空です。ここで失敗するなら、Claude Code の表示設定より先にパス、Node.js、JSON、スクリプトを直します。
| 症状 | 次に確認すること | 判断の目安 |
|---|---|---|
| コマンドが起動しない | インタープリターとファイルを絶対パスで指定 | ファイルがない、PATH が異なる、引用符が不足している可能性 |
| 空白になる | stdout、stderr、終了コードを分けて確認 | stdout が空、例外、非ゼロ終了ならスクリプト側を修正 |
ctx:-- だけが出る | 最初の応答後の状態、フィールド名 | used_percentage の欠損と、行自体が出ない症状は別 |
git:-- になる | JSON の作業場所で git -C を実行 | リポジトリ外、Git 未導入、パス不一致、タイムアウトを区別 |
| 外では動くが Claude Code では出ない | 読み込まれた設定と実行制限 | 別スコープの上書きや管理設定を確認 |
| 変更したスクリプトが反映されない | 次の更新契機、コマンドの参照先 | 別ファイルを編集していないか。待機中の値ならタイマーを検討 |
| 色や記号だけが崩れる | 文字だけの出力に戻す | 端末・フォントの問題とスクリプトの失敗を分ける |
Git の切り分けには、対象ディレクトリで git -C <絶対パス> rev-parse --is-inside-work-tree と git -C <絶対パス> symbolic-ref --quiet --short HEAD を使えます。前者が成功し後者が失敗するなら、detached HEAD かを rev-parse --short HEAD で確認します。まだコミットのないリポジトリでは、短いコミット ID がないことは正常です。
外では動くのに表示されない:管理設定の制限を確認
管理設定の disableAllHooks=true、または信頼されていない作業領域では、カスタム statusLine は実行されません。一方、allowManagedHooksOnly、有効な非管理設定の disableAllHooks=true、--safe-mode は管理設定由来のものに限定します。この場合、管理者が配布した statusLine は動いても、個人・プロジェクト・プラグインの設定は警告なしで省略されることがあります。実行制限の正確な条件
管理プラグインの hook が許可されていることだけでは、そのプラグインの statusline まで許可されたことにはなりません。statusLine 自体の設定元が重要です。組織の制限に該当するなら、設定元と模擬実行の結果を管理者へ伝えます。表示のために管理ルールを解除したり、設定ファイル全体を削除したりする必要はありません。
不正な JSON や既知の無効な設定値は、起動時の表示や claude doctor で確認できる場合があります。「エラーはすべて黙って無視される」と考えず、出ている診断を確かめます。また、ヘルプや権限確認の画面で一時的に行が見えないことは、スクリプトの失敗とは限りません。
テーマを選びたいなら ccstatusline
配色や Powerline、複数行、ウィジェットを対話形式で選びたい場合は、ccstatusline の READMEが候補になります。Node.js/npm がある環境の起動例は次のとおりです。
npx -y ccstatusline@latestこれはパッケージを取得して実行する操作です。初期画面の Pinned global install を選ぶと、選んだ版をグローバルにインストールし、固定版のコマンドを設定します。導入後の ccstatusline は設定画面を開くコマンドです。ツール側の設定先は ~/.config/ccstatusline/settings.json で、Claude Code の statusLine とは別です。
ただし、すべての項目が stdin の JSON だけを読むわけではありません。利用量ウィジェットは認証情報や Keychain を参照し、Anthropic の利用量 API へ直接通信する場合があります。履歴・キャッシュを読む項目や、ネットワークを使うサービス状況の表示もあります。表示項目を選ぶときに、その依存関係も確認してください。基本の項目で十分なら、上の小さいスクリプトの方が処理内容を把握しやすくなります。
よくある質問
statusline、/statusline、statusLine の違いは?
statusline は機能の呼び名、/statusline は Claude Code 内のコマンド、statusLine は設定 JSON のキーです。設定ファイルでは大文字の L を含む statusLine を使います。
ステータスラインは追加の API トークンを使いますか?
JSON を整形するだけの自作コマンドは、モデルへ追加リクエストを送りません。本稿の例もネットワークを使いません。ただし、外部ツールの利用量・サービス状況などのウィジェットは別途通信する場合があります。標準の入出力仕様、ccstatusline の表示項目
コンテキストが -- や null でも正常ですか?
最初の API 応答前や /compact の直後は正常な場合があります。次の応答後も続くなら、スクリプトが context_window.used_percentage を読んでいるか確認してください。欠損値をゼロ扱いすると、未取得なのに余裕があるように見えてしまいます。欠損値の条件
Pro/Max なのに5時間・7日間の利用率が出ないのはなぜ?
対象契約でも、最初の API 応答前や期限切れの期間では項目がない場合があります。各期間は独立して欠けるため、片方だけ出ることもあります。コンテキストのトークン数から契約の利用率を推算せず、提供された rate_limits を読みます。利用率のフィールドと条件
表示を元に戻すには?
有効な設定ファイルの statusLine だけを削除するか、/statusline に解除を依頼します。上位スコープに同じキーがあるとそちらが有効になるので、/status で読み込まれた設定も確認してください。statusLine 設定





