Claude Code Statusline 設定：経路、フィールド、スクリプト、修正手順

Claude Code statusline はローカルコマンドです。Claude Code が現在のセッション JSON を stdin に渡し、あなたのコマンドが stdout に出した文字列が画面下部の statusline になります。個人用に素早く始めるなら /statusline、内容をレビューして制御したいなら手動 statusLine、チームで共有するなら全員に安全なコマンドだと確認してから project settings に置きます。

順序は、見た目ではなく、経路、コマンド契約、設定スコープ、表示フィールドです。statusline は model、directory、git branch、context 使用率、cost estimate、条件によって rate limit 情報を表示できます。ただし、どのフィールドも欠ける可能性があるため、スクリプトは null と未定義を前提に作ります。

statusline の実行契約を先に押さえる

statusline はターミナルテーマでも追加の API 呼び出しでもありません。Claude Code の UI がローカルコマンドを起動し、stdin に JSON を入れ、stdout を読み取り、その文字列を下部の行として表示します。つまり、先に理解すべきなのは配色ではなく、どのコマンドがどこで実行されるかです。

この仕組みには三つの意味があります。第一に、コマンドはローカルで実行されます。git を呼び出したり、作業ディレクトリを読んだり、home 配下のスクリプトを実行したりできます。個人用には便利ですが、project settings で共有する場合は信頼境界になります。

第二に、スクリプトは防御的であるべきです。JSON には model、workspace、git、cost、context、session、version、output style、vim、agent、worktree、rate limit などが入る場合がありますが、すべての環境で同じとは限りません。よい statusline は ctx:? や git:- のように落ち着いて fallback します。

第三に、stdout がそのまま読者の見る画面です。デバッグログは stderr に逃がし、表示行は短く、安定し、速くします。長いダッシュボードを作るより、日常で一瞬で読める一行が有用です。

最初の個人版は /statusline で作る

まず Claude Code 内で次を実行します。

text
/statusline

依頼文は短く具体的にします。

text
Show model, current directory, git branch, context percentage, and estimated cost. Keep it one line and handle missing fields.

Claude Code はスクリプトを生成して設定できます。動いたら必ずファイルを開いて内容を読みます。これは見た目の設定ではなく、ローカルコマンドの承認です。絶対パス、ネットワークアクセス、private endpoint、重い git status が含まれていたら、そのまま共有しません。

/statusline は試行錯誤に向いています。どのフィールドが自分に役立つか、どの表示が長すぎるかを確認する段階です。チーム標準にする段階では、手動 statusLine に戻り、パス、fallback、速度、信頼を明示します。

制御が必要なら手動 statusLine

手動設定では settings に command object を書きます。

json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline/statusline.js",
    "refreshInterval": 5
  }
}

重要なのは type と command です。refreshInterval は必須ではありません。時計のような値や外部キャッシュ状態を定期更新したい場合だけ使います。通常は Claude Code のイベント更新で足ります。むやみに短くすると、遅いスクリプトの問題が見えにくくなります。

個人用なら ~/.claude/ 配下で十分です。チーム用なら repo 内の .claude/statusline/ に置けますが、通常のコードと同じように review します。個人の home path、secret、特定マシンだけの依存を共有設定に入れてはいけません。

mock JSON で先に実行確認する

次の Node.js 例は stdin を読み、JSON を安全に解釈し、stdout に一行だけ出します。

js
#!/usr/bin/env node

let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  input += chunk;
});

process.stdin.on("end", () => {
  let data = {};
  try {
    data = input.trim() ? JSON.parse(input) : {};
  } catch (error) {
    console.error(`statusline JSON parse failed: ${error.message}`);
  }

  const model = data.model?.display_name || data.model?.id || "model?";
  const cwd = data.workspace?.current_dir || data.cwd || "";
  const dir = cwd ? cwd.split("/").filter(Boolean).pop() : "workspace?";
  const branch = data.git?.branch ? `git:${data.git.branch}` : "git:-";
  const context =
    typeof data.context_window?.percentage === "number"
      ? `ctx:${Math.round(data.context_window.percentage)}%`
      : "ctx:?";
  const cost =
    typeof data.cost?.total_cost_usd === "number"
      ? `$${data.cost.total_cost_usd.toFixed(2)} est`
      : "$? est";

  process.stdout.write(`${model} | ${dir} | ${branch} | ${context} | ${cost}`);
});

保存して実行権限を付け、Claude Code なしで確認します。

bash
chmod +x ~/.claude/statusline/statusline.js
printf '%s' '{"model":{"display_name":"Claude Sonnet"},"workspace":{"current_dir":"/Users/me/project"},"git":{"branch":"main"},"context_window":{"percentage":42},"cost":{"total_cost_usd":0.18}}' | ~/.claude/statusline/statusline.js

期待する結果は一行です。外部で動かないコマンドを Claude Code に登録しても安全にはなりません。先に mock JSON で直し、stdout と stderr の役割を分けます。

表示フィールドは仕事から選ぶ

statusline は視線移動を減らすためのものです。今どの project にいるか、どの model か、git は汚れているか、context はどれくらいか、cost estimate は大きくなっていないか。この程度を一瞬で判断できれば十分です。

読みやすい一行は、identity、location、state、risk の四つ程度です。

text
Sonnet | api-docs | main* | ctx:42% | $0.18 est

main* は変更ありの合図にできます。context と cost はリスク指標です。不要なら削り、表示幅を守ります。

設定スコープを間違えない

Claude Code settings には複数のスコープがあります。statusline は、コマンドが安全に実行できるスコープに置きます。

チームで使うならこうします。

json
{
  "statusLine": {
    "type": "command",
    "command": "./.claude/statusline/statusline.js"
  }
}

このスクリプトは review 済みで、secret なし、private endpoint なし、速く、fallback あり、簡単に無効化できる必要があります。

更新は軽く保つ

statusline は何度も呼ばれます。毎回ネットワークを叩いたり、巨大な git status を走らせたりすると、Claude Code の操作感が悪くなります。

実務では三つだけ守れば十分です。Claude Code から来た JSON フィールドを優先する。高価な処理は cache する。refreshInterval は定期更新が本当に必要な場合だけ使う。

直接測定します。

bash
time printf '{}' | ~/.claude/statusline/statusline.js

ここで遅いなら、Claude Code の設定ではなくスクリプトの問題です。行を短くし、外部アクセスを消し、Git チェックを軽くします。

Windows と terminal 表示

Windows で壊れるときは、多くの場合 JSON ではなく shell/path です。Git Bash、PowerShell、WSL、Node で quote、path、改行が変わります。Claude Code が実際に起動するのと同じ command を確認します。

最初は plain text にします。ANSI color、powerline glyph、OSC 8 link は最後に追加します。macOS で動いて Windows だけ壊れる場合は、interpreter path、executable path、line endings、cwd を順に確認します。

third-party formatter を使う条件

formatter はテーマや ready-made layout が必要なときに役立ちます。ただし事実の所有者ではなく、単なるローカルコマンドです。

何を実行しているか説明できない formatter は使わず、小さい自作スクリプトのままにします。

空白、skipped、古い表示の直し方

disableAllHooks も排障面に入ります。むやみに切り替えると、期待していた hook-like 動作まで止まる可能性があります。

関連 Claude Code ガイド

• CLI から始めるなら Claude Code install。
• credential と route は Claude Code API configuration。
• API key と subscription の違いは Claude Code API key vs subscription billing。
• 状態表示が安定したら Claude Code memory。
• workflow を再利用するなら Claude Code best skills。

よくある質問

statusline と statusLine は同じですか？

同じ書き方ではありません。statusline は一般語、/statusline は slash command、statusLine は settings の JSON key です。

statusline は API token を使いますか？

statusline command 自体はローカル実行で、追加の model request ではありません。Claude Code が渡したデータを表示するだけです。

rate limits は表示できますか？

入力 JSON にある場合だけ表示できます。rate_limits がないときも正常に動くようにします。

project に script を commit してよいですか？

全員に安全な場合だけです。secret なし、path-safe、高速、fallback あり、review 済み、簡単に無効化できる必要があります。

undefined が出るのはなぜですか？

スクリプトが存在しないフィールドを前提にしています。欠損 mock JSON を流し、fallback を追加します。

最初の一行は何を出すべきですか？

model、directory basename、git branch、context percentage、cost estimate が十分です。色や formatter は安定後に追加します。