Claude Code statuslineの設定と表示項目の選び方

Claude Code statuslineは、ターミナル下部に自作スクリプトの出力を常時表示する機能です。settings.jsonのstatusLineフィールドにコマンドを1つ登録するだけで、モデル名やGitブランチ、コンテキスト残量、セッションコストなどをリアルタイムで確認できるようになります。本稿では設定の基本構文から、stdinで受け取れるJSONフィールドの選び方、最小構成から実務構成までの実装レシピ、表示されないときのつまずき対処までを扱います。

Claude Code statuslineとは何か

statuslineは、任意のシェルスクリプトを実行し、その標準出力をそのままターミナル下部の1行(または複数行)に描画する仕組みです。スクリプトは標準入力(stdin)でセッション情報を含むJSONを受け取り、標準出力(stdout)に書いた内容がそのまま画面に表示されます。既定ではstatusLineは未設定で、下部には組み込みのフッターバッジだけが並びます(vim編集モードを有効にしている場合はプロンプト下に-- INSERT --も表示されます)。statuslineはClaude Codeが備える数あるカスタマイズ機能の1つで、CLIの全体像はClaude Code(クロードコード)の全体像にまとめています。

これとは別にfooterLinksRegexesという設定もあります。会話中に出てきたPR番号やissue番号を、独自のリンクバッジとしてフッターに追加する機能です。組み込みのフッターバッジとは別レイヤーの機能で、footerLinksRegexesはIDのリンクを足す側、statusLineは行そのものを組み立てる側という役割分担になります。どちらか一方がもう一方を置き換えるわけではありません。スクリプトを書かずにIDをリンク化したいだけならfooterLinksRegexesで足り、セッションデータから自分で行を組み立てたいならstatusLineを使います。

自分でスクリプトを書く代わりに、/statuslineコマンドで自然言語の指示からスクリプトを自動生成することもできます。「モデル名とGitブランチとコンテキスト使用率を表示して」のように伝えれば、雛形のシェルスクリプトが~/.claude/配下に作られます。

statuslineスクリプトはローカルで実行され、APIトークンを消費しません。1秒ごとに再実行するような設定にしても、Claudeの利用料金には影響しません。

statusLineの前提知識 — settings.jsonでの設定

設定はsettings.json(グローバル~/.claude/settings.jsonまたはプロジェクトの.claude/settings.json)のstatusLineオブジェクトに書きます。必須なのはtypeとcommandの2つだけです。

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

スクリプトの実行タイミングはイベント駆動です。セッション開始時(resumeを含む)、新しいアシスタントメッセージが届いたとき、/compact完了時、権限モードの変更時、vimモードの切り替え時が既定のトリガーです。refreshIntervalを設定していれば、タイマー満了時も加わります。更新は300msでデバウンスされます。実行中のスクリプトがある状態で新しいトリガーが来ると、実行中のスクリプトのほうが中断され、新しいトリガーで実行し直されます。

refreshIntervalを設定する主な場面は2つです。時刻のように時間の経過だけで値が変わる表示をするとき、そしてメインセッションがアイドル中にバックグラウンドのサブエージェントがgit状態を変えるときです。イベント駆動のトリガーはメインセッションがアイドルの間は発火しないため、この2つのケースではrefreshIntervalがないと表示が更新されないまま古くなります。

スクリプトを保存したら、まず手動でパイプ経由の実行を試すと動作確認が早く済みます。

chmod +x ~/.claude/statusline.sh
echo '{"model":{"display_name":"Sonnet 5"}}' | ~/.claude/statusline.sh

statuslineを無効にしたいときは、/statuslineコマンドに削除を指示するか、settings.jsonのstatusLineフィールドそのものを削除します。どちらの方法でも、次にClaude Codeとやり取りした時点で組み込みのフッターバッジだけの表示に戻ります。

表示する情報を選ぶ — stdin JSONフィールドの早見表

stdinに渡されるJSONには、セッションに関する情報がまとまって入っています。何を表示するかは公式に決められておらず、用途に応じて選ぶ設計の余地です。よく使われる系統ごとに分けて紹介します。

基本情報

コンテキストとコスト

used_percentageの計算式は入力トークンのみが対象です。input_tokens + cache_creation_input_tokens + cache_read_input_tokensの合計から算出され、output_tokensは含みません。出力トークンの影響を過大評価しないよう、この前提を押さえておくと数値の解釈がぶれません。

レート制限・PR・その他

effort.levelはlow/medium/high/xhigh/maxのいずれかを返します。ultracodeは独立したレベルではなく、xhighとして報告されます。effortパラメータに対応していないモデルでは、このフィールド自体が出力されません。

rate_limitsはClaude.aiのPro/Maxサブスクリプションユーザーに対して、最初のAPIレスポンス後に現れるフィールドです。APIキー課金の環境では出現しないことがある点に注意します。

現行のstdin JSONに含まれていないフィールドもあります。権限モード(permission_mode)、モデルごとのレート制限、残クレジット残高はいずれも含まれておらず、statuslineでそのまま表示することはできません。これらを常時表示したい場合は、別の手段で自分で取得する必要があります。

実装レシピ — 最小構成から実務構成まで

段階的に組み立てる例です。いずれもjqでJSONをパースする前提で書いています。

最小構成はモデル名だけを表示します。

#!/usr/bin/env bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
echo "🤖 $model"

Gitブランチを足すと、作業対象の切り替えミスに気づきやすくなります。

#!/usr/bin/env bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
cwd=$(echo "$input" | jq -r '.workspace.current_dir')
branch=$(git -C "$cwd" branch --show-current 2>/dev/null)
echo "🤖 $model | 📁 $(basename "$cwd") | 🌿 ${branch:-no-git}"

コンテキスト使用率とコストを加えた実務構成です。context_window.used_percentageやcost.total_cost_usdは、セッション序盤で初回のAPIレスポンスが完了する前はnullになり得ます。/compactを実行した直後も、次のAPIレスポンスが返るまでの間はcontext_window.current_usageが再びnullに戻ります。// 0でフォールバックしないとprintfがエラー終了し、statusline自体が空白になります。

#!/usr/bin/env bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
ctx=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
printf "🤖 %s | 📊 %.0f%% | 💰 \$%.2f\n" "$model" "$ctx" "$cost"

レート制限が近いときだけ警告を出す例も、実運用で効きます。

#!/usr/bin/env bash
input=$(cat)
five_hour=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // 0')
if (( $(echo "$five_hour > 80" | bc -l) )); then
  echo "⚠️ レート制限 ${five_hour}%"
else
  echo "レート制限 ${five_hour}%"
fi

いずれの構成でも、echoの代わりに条件分岐を挟むだけでフィールドの取捨選択ができます。表示項目を増やしすぎると1行に収まらなくなるため、優先度の低いフィールドから外していくとバランスが取れます。

見た目を整える — 色・アイコン・複数行

statuslineと同じ行の右側は、MCPサーバーエラーや自動更新のシステム通知、そしてverboseモードを有効にしたときのトークンカウンタとも共有されています。狭い端末ではこれらの分だけstatuslineに使える幅が減り、出力が途中で切り詰められることがあります。表示項目を絞る調整は、この共有領域も見込んで行うと安心です。

ANSIエスケープシーケンスで色を付けると視認性が上がります。

#!/usr/bin/env bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
GREEN='\033[32m'
RESET='\033[0m'
echo -e "${GREEN}🤖 ${model}${RESET}"

絵文字の代わりにNerd Fontのアイコンフォントを使う構成も一般的です。ただし表示はターミナル側のNerd Font対応に依存し、対応していない環境では文字化けします。

出力幅を意識するなら、COLUMNSとLINESの環境変数(v2.1.153以降)が使えます。Claude Codeはスクリプトの出力をキャプチャして描画する方式のため、スクリプト内からtput colsでターミナル幅を直接取得することはできません。かわりにこの2つの環境変数を読みます。

複数行の出力もできますが、v2.1.141より前のバージョンでは、いずれかの行が端末幅を超えると行が欠落したり崩れたりする不具合がありました。長い行を出す構成にするなら、最新版で動作確認しておくと安心です。

OSC 8というエスケープシーケンスを使うと、statuslineの文字列をクリック可能なリンクにできます。書式は\e]8;;URL\e\\表示テキスト\e]8;;\e\\で、PR番号やコミットハッシュをそのままリンクとして埋め込めます。

#!/usr/bin/env bash
input=$(cat)
pr_url=$(echo "$input" | jq -r '.pr.url // empty')
pr_number=$(echo "$input" | jq -r '.pr.number // empty')
if [[ -n "$pr_url" ]]; then
  printf '\e]8;;%s\e\\PR #%s\e]8;;\e\\\n' "$pr_url" "$pr_number"
fi

対応はターミナル依存で、自動検出に失敗したり無効化されたりする場合があります。具体的な対処は後述の「よくあるつまずき」で扱います。

キャッシュ設計 — session_idを使う理由

git statusのような重い処理を毎回実行すると、更新のたびに体感速度が落ちます。公式ドキュメントは、キャッシュのキーにプロセスIDではなくsession_idを使うことを勧めています。プロセスIDは実行のたびに値が変わるため、キャッシュのキーに使うとキャッシュそのものが効かなくなってしまいます。session_idはセッションの生存期間中は安定していて、セッションごとに一意なので、キャッシュキーとして機能します。

#!/usr/bin/env bash
input=$(cat)
session_id=$(echo "$input" | jq -r '.session_id')
cache_file="/tmp/claude-statusline-${session_id}.cache"
 
if [[ -f "$cache_file" ]] && [[ $(($(date +%s) - $(stat -c %Y "$cache_file" 2>/dev/null || stat -f %m "$cache_file" 2>/dev/null || echo 0))) -lt 5 ]]; then
  cat "$cache_file"
else
  branch=$(git branch --show-current 2>/dev/null)
  echo "🌿 ${branch:-no-git}" | tee "$cache_file"
fi

statのオプションはLinux形式(-c)を先に試す点がポイントです。macOS形式(-f)を先に置くと、Linux環境で問題が起きます。エラーの前にファイルシステムのレポートが標準出力に出てしまい、そのままコマンド置換に取り込まれて後続の算術評価を壊すためです。5秒程度のキャッシュを挟むだけで、Git情報のような重い処理でも体感の遅延はほぼ消えます。キャッシュファイルをセッションより長く残したくない場合は、セッション終了時に削除する処理を別途仕込みます。

subagentStatusLineでサブエージェントパネルも設定する

statusLineとは別に、サブエージェントパネルの各行フォーマットを差し替えるsubagentStatusLineという設定もあります。入力にはhooks共通の基本フィールドに加えて、使用可能な行幅を示すcolumnsフィールドとtasks配列が含まれます。tasksの各要素には次のフィールドが含まれます。

• 識別・状態: id / name / type / status / description / label
• 実行情報: startTime / model / effort / cwd
• トークン: contextWindowSize / tokenCount / tokenSamples

tokenCountはcontextWindowSizeと組み合わせて行ごとの使用率を出す用途に使えます。modelとcontextWindowSizeはv2.1.205以降、effortはv2.1.214以降に追加されたフィールドです。

出力形式はstatusLineと異なり、{"id": "...", "content": "..."}のJSON Linesをタスクごとに返します。

#!/usr/bin/env bash
input=$(cat)
echo "$input" | jq -c '.tasks[] | {id: .id, content: "▶ \(.name) [\(.status)]"}'

複数のサブエージェントを並行で走らせる運用をしているなら、statusLineだけでなくsubagentStatusLineもあわせて設定すると、パネル全体の視認性が揃います。

自作スクリプトかccstatuslineか

公式ドキュメントは、コミュニティ製ツールとしてccstatusline(GitHub: sirmalloc/ccstatusline)とstarship-claude(GitHub: martinemde/starship-claude)を名指しで紹介しています。自作スクリプトとの使い分けの目安です。

すでにstarshipプロンプトを使っている環境ならstarship-claudeとの相性がよく、テーマ性やpowerline対応を重視するならccstatuslineが候補になります。特定のフィールドの組み合わせを細かく制御したい場合は、自作スクリプトのほうが小回りが利きます。

statuslineが強化されてきた道のり

初出のv1.0.71から現在まで、stdin JSONのフィールドは段階的に拡張されてきました。

この一覧を見ると、初期はコストやコンテキストといった基本指標の追加が中心で、v2.1系に入ってからworktree・rate_limits・PR情報のような「マルチセッション運用」を前提にしたフィールドが増えています。並行して動くセッションが増えるほど、statuslineで区別できる情報の価値は上がります。

よくあるつまずき

claude --debugはstatuslineが動かない原因の切り分けに最も役立ちます。トラブルシューティングの手順をもう少し広く確認したい場合は、Claude Codeでよくあるエラー10選にも起動・認証まわりの対処法をまとめています。

よくある質問

statuslineはAPIトークンを消費しますか

消費しません。statuslineスクリプトはローカルで実行され、Claudeへのリクエストを伴わないため、refreshIntervalを短く設定しても料金には影響しません。

padding・hideVimModeIndicatorはいつから使えますか

公式ドキュメントに導入バージョンの記載はありません。現行バージョンではどちらも利用できます。

/statuslineコマンドとは何が違いますか

/statuslineは自然言語の指示からスクリプトを自動生成するコマンドです。生成後は通常のstatusLine.commandと同じようにsettings.jsonに登録され、手書きのスクリプトと扱いは変わりません。

worktreeを使っているとstatuslineはどう変わりますか

2系統に分かれます。git worktree addで作った作業ツリーに入って通常起動した場合はworkspace.git_worktreeが使えます。一方worktree.name/worktree.branchは--worktreeフラグでセッションを起動したときだけ出現するフィールドで、通常のworktreeでは値が入りません。並列セッションを組む運用についてはClaude Code Worktree実践ガイドでも扱っています。

settings.jsonの他のフィールドとの関係は

statusLineはsettings.jsonが持つ設定項目の1つです。hooks・MCP・permissionsなど他のフィールドとあわせた全体像はClaude Code設定ガイドで確認できます。

まとめ

statuslineの設定自体はtypeとcommandの2行で始められます。設計の本題はその先で、stdinのJSONから何を選んで表示するかです。基本情報だけの最小構成から始め、コンテキスト使用率やレート制限のように運用で効く指標を足していく進め方が現実的です。重い処理を挟むならキャッシュを、複数セッションを並行させるならworktreeやsubagentStatusLineの活用を検討する価値があります。表示されないときは、ワークスペーストラストの承認状態・disableAllHooksの設定・スクリプトの実行権限・出力先の4点を順に確認すると、原因を切り分けやすくなります。