Customize your status line

概要

Claude Code の下部に表示されるカスタマイズ可能なバー。設定したシェルスクリプトを実行し、stdin で JSON のセッションデータを受け取り、スクリプトが出力した内容を表示する。

仕様

設定

• /statusline コマンドに自然言語で指示すると、~/.claude/ にスクリプトを生成し設定を自動更新する
• 手動設定は user settings（~/.claude/settings.json）または project settings に statusLine フィールドを追加する。type を "command" にし、command にスクリプトパスまたはインラインのシェルコマンドを指定する
• command はシェルで実行されるため、スクリプトファイルの代わりにインラインコマンドも使える

• 無効化するには /statusline に削除を依頼する（/statusline delete など）か、settings から statusLine フィールドを消す
• ステータスラインは組み込みのフッターバッジの上に独自の行として描画され、フッターを置き換えない。カスタムステータスライン設定時、フッターのキーボードヒント（esc to interrupt、? for shortcuts、hold space to speak）の多くは表示されなくなる

動作

スクリプトはセッション開始時（resume を含む）に 1 回実行され、その後は次のときに再実行される。

• 新しいアシスタントメッセージが届いたとき

• /compact が完了したとき

• permission mode が変わったとき

• vim mode が切り替わったとき

• refreshInterval のタイマーが経過したとき（設定した場合）

• 更新は 300ms でデバウンスされ、急な変化はまとめられて変化が止まった後に 1 回実行される

• スクリプト実行中に新しい更新がトリガーされると、実行中のスクリプトはキャンセルされる

• スクリプトを編集した場合、次の更新トリガーで再実行されたときに反映される

• v2.1.216 より前は、セッションの resume でコマンドが短時間に 2 回実行されていた

出力:

• 複数行: echo / print ごとに別の行として表示される

• 色: \033[32m のような ANSI escape code（ターミナルの対応が必要）

• リンク: OSC 8 escape sequence でクリック可能にする（macOS は Cmd+click、Windows/Linux は Ctrl+click）。iTerm2 / Kitty / WezTerm など対応ターミナルが必要

• Claude Code はスクリプト出力を捕捉するため、tput cols や言語レベルの幅検出はスクリプト内からターミナルサイズを読めない。代わりに COLUMNS と LINES 環境変数を読む。Claude Code はスクリプト実行前にこれらを現在のターミナル寸法に設定する。v2.1.153 以降が必要

• ステータスラインはローカルで動き、API トークンを消費しない。オートコンプリート候補、ヘルプメニュー、permission prompt など一部の UI 操作中は一時的に隠れる

stdin で渡される JSON フィールド

欠けうるフィールド: session_name、prompt_id、workspace.git_worktree、workspace.repo、effort、vim、agent、pr、worktree、rate_limits（rate_limits は Claude.ai サブスクライバー（Pro/Max）で、セッション最初の API 応答後にのみ現れる。five_hour と seven_day は独立して欠けうる）。

null になりうるフィールド: context_window.current_usage（セッション最初の API 呼び出し前と、/compact 後から次の API 呼び出しまで）、context_window.used_percentage と remaining_percentage（セッション初期）。

context_window フィールドの詳細

• total_input_tokens は input_tokens + cache_creation_input_tokens + cache_read_input_tokens の合計。total_output_tokens は直近応答の output token。どちらも最初の API 応答前は 0
• current_usage は同じトークン数をカテゴリ別に分けたもの。input_tokens / output_tokens / cache_creation_input_tokens / cache_read_input_tokens を持つ
• used_percentage は input のみから計算される（input_tokens + cache_creation_input_tokens + cache_read_input_tokens）。output_tokens は含まない

subagentStatusLine

• agent パネルに表示される各 subagent 行の本文をカスタムで描画する。既定の name · description · token count を置き換える
• コマンドはリフレッシュのたびに 1 回実行され、表示中の全 subagent 行を 1 つの JSON オブジェクトとして stdin で受け取る
• 入力には base hook fields、使用可能な行幅の columns フィールド、tasks 配列が含まれる。各 task は id、name、type、status、description、label、startTime、model、effort、contextWindowSize、tokenCount、tokenSamples、cwd を持つ
• model は task が動く解決済みモデル ID。contextWindowSize はそのモデルのコンテキストウィンドウ（トークン）で、メインの context_window.context_window_size と同じ方法で計算される。どちらも v2.1.205 以降が必要で、モデルが未解決の task では省略される
• effort はその subagent に設定された reasoning effort（定義の frontmatter か個別の呼び出し）。値は effort level 文字列（low / medium / high / xhigh / max）か数値のトークン予算。設定値をそのまま報告するため、モデルがその水準に対応していない場合、実際に適用される effort とは異なりうる。v2.1.214 以降が必要で、セッションの effort を継承する場合は存在しない
• 上書きしたい行ごとに {"id": "<task id>", "content": "<row body>"} の形式で stdout に 1 行ずつ JSON を書く。content は ANSI 色と OSC 8 ハイパーリンクを含めそのまま描画される。task の id を省くとその行は既定描画のまま、空の content を出すと非表示になる
• statusLine と同じ trust と disableAllHooks のゲートが適用される。Plugin は settings.json で既定の subagentStatusLine を配布できる

Windows

• Git Bash がインストールされていれば Git Bash 経由、無ければ PowerShell 経由でコマンドを実行する
• Git Bash は引用符無しのバックスラッシュをエスケープ文字として扱うため、C:\Users\username\script.mjs のような Windows 形式パスは区切りが失われてエラー表示なく失敗する。command 文字列のパスはスラッシュで書く。~ も Windows のホームディレクトリに展開される
• PowerShell スクリプトを使うには powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1 のように呼び出す

設定

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2
  }
}

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'"
  }
}

{
  "subagentStatusLine": {
    "type": "command",
    "command": "~/.claude/subagent-statusline.sh"
  }
}

#!/bin/bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
echo "[$MODEL] 📁 ${DIR##*/} | ${PCT}% context"

制約・注意点

• スクリプトは実行可能にする（chmod +x）
• 出力は stdout に書く（stderr ではない）
• ステータスラインのコマンドは、現在のディレクトリの workspace trust ダイアログを承認している場合のみ実行される。未承認だとステータスラインは空のままで、claude --debug に Status line command skipped: workspace trust not accepted が記録される
• settings で disableAllHooks が true のとき、ステータスラインも無効になる
• 非ゼロ終了コードや出力なしのスクリプトはステータスラインを空にする
• 遅いスクリプトは完了までステータスラインの更新をブロックする
• ステータスバーの幅は限られており、長い出力は切り詰められたり折り返されたりする
• スクリプトは頻繁に実行されるため、git status のような遅いコマンドはラグを生む。キャッシュする場合、キャッシュファイル名にはセッション中一定で他セッションと衝突しない session_id を使う（$$ / os.getpid() / process.pid は毎回変わりキャッシュが機能しない）
• コンテキスト率は計算タイミングの違いにより /context の出力と異なりうる
• OSC 8 リンクは対応ターミナル（iTerm2 / Kitty / WezTerm）が必要。Terminal.app は非対応。検出に失敗する場合は FORCE_HYPERLINK 環境変数で上書きする。SSH と tmux は設定によって OSC シーケンスを取り除くことがある
• エスケープシーケンスが \e]8;; のようにリテラル表示される場合は echo -e ではなく printf '%b' を使う
• 複雑なエスケープシーケンスは他の UI 更新と重なると出力が乱れることがある。複数行 + エスケープコードは単一行のプレーンテキストより描画上の問題が起きやすい
• MCP サーバーエラーや自動更新などのシステム通知は同じ行の右側に表示される。verbose モードを有効にするとトークンカウンタもこの領域に加わる。狭いターミナルではステータスライン出力が切り詰められうる

関連

• facts/claude-code/settings.md
• facts/claude-code/commands.md
• facts/claude-code/sub-agents.md
• facts/claude-code/hooks.md
• facts/claude-code/context-window.md
• facts/claude-code/costs.md
• facts/claude-code/interactive-mode.md
• facts/claude-code/plugins.md