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

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

Claude Code statuslineとは何か

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

statuslineはフッターバッジの上に独立した行として描画され、バッジを置き換えるわけではありません。ただしカスタムstatuslineを設定すると、esc to interruptや? for shortcutsといったフッターのキーボードヒントの大半は表示されなくなります。ヘルプメニューや権限プロンプトが開いている間も、statuslineは一時的に隠れます。

これとは別にfooterLinksRegexesという設定もあります。会話中に出てきたPR番号やissue番号を、独自のリンクバッジとしてフッターに追加する機能です。スクリプトを書かずにIDをリンク化したいだけならfooterLinksRegexesで足り、セッションデータから自分で行を組み立てたいならstatusLineを使います。書き方と制限はfooterLinksRegexesの設定解説にあります。

自分でスクリプトを書く代わりに、/statuslineコマンドで自然言語の指示からスクリプトを自動生成することもできます。「モデル名とGitブランチとコンテキスト使用率を表示して」のように伝えれば、雛形のシェルスクリプトが~/.claude/配下に作られます。statuslineが常時表示の1行であるのに対し、バージョン・モデル・接続状況をその場でまとめて確認したいときは/statusコマンドを使います。

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

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

設定はsettings.json(グローバル~/.claude/settings.jsonまたはプロジェクトの.claude/settings.json)のstatusLineオブジェクトに書きます。必須なのはtypeとcommandの2つだけです。hooks・MCP・permissionsを含むsettings.jsonの全体像は、Claude Code設定ガイドで確認できます。

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

commandはシェル経由で実行されるので、スクリプトファイルを作らずjqを使ったインラインコマンドを直接書くこともできます。

スクリプトが再実行される契機

スクリプトは、セッション開始時に1回実行されたあと、次のような契機で再実行されます。

更新は300msでデバウンスされ、短時間に連続した変化は1回の実行にまとまります。実行中のスクリプトがある状態で新しいトリガーが来ると、実行中のほうが中断され、新しいトリガーで実行し直されます。

メインセッションがアイドルの間はイベント駆動のトリガーが静かになります。コーディネーターがバックグラウンドのサブエージェントを待っている間に、そのサブエージェントがgit状態を変える場面が代表例です。時刻のように時間の経過だけで値が変わる表示も同じで、refreshIntervalを設定しないと古いまま残ります。

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

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

statuslineを無効にしたいときは、/statuslineコマンドに削除を指示するか、settings.jsonのstatusLineフィールドそのものを削除します。

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

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

基本情報

session_nameは、my-app-3fのような既定の表示名では埋まりません。名前もAI生成のタイトルも無いセッションでは、フィールド自体が現れません。

コンテキストとコスト

used_percentageの計算式は入力トークンのみが対象です。input_tokens + cache_creation_input_tokens + cache_read_input_tokensの合計から算出され、output_tokensは含みません。current_usageから自分で割合を出すときも、同じ入力のみの式にそろえるとused_percentageと一致します。コンテキストとは別に、キャッシュの効き具合そのものを追うフィールドとしてprompt_cacheがあります。詳細はstatuslineでprompt_cacheを表示するにまとめています。

レート制限・PR・その他

effort.levelはlow/medium/high/xhigh/maxのいずれかを返し、セッション中に/effortで変えた値も反映されます。effortパラメータに対応していないモデルでは、このフィールド自体が出力されません。Ultracodeは/effortの独立したトグルになっており(v2.1.284)、その有効・無効を示すフィールドは公式のJSON一覧にありません。

rate_limitsが現れるのは、Claude.aiのPro/Maxサブスクリプションユーザーと、支出上限を設定したゲートウェイ経由の利用者に限られます。しかも最初のAPIレスポンスのあとです。five_hour・seven_day・spend_limitの各ウィンドウは個別に欠けることがあり、resets_atを過ぎたウィンドウはClaude Code側で取り除かれます。

PRは、GitLabリモートのリポジトリではマージリクエストの情報で埋まります(v2.1.234以降)。この場合pr.numberはマージリクエスト番号で、pr.kindがmrになります。

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

worktree.*は--worktreeでセッションを起動したときだけ出る系統で、git worktree addで作った通常のworktreeでは値が入りません。通常のworktreeではworkspace.git_worktreeを使います。5フィールドの詳細はstatuslineのworktreeフィールドにあります。並列セッションを組む運用はClaude Code Worktree実践ガイドが扱っています。

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

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

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

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

Gitブランチを足すと、作業対象の切り替えミスに気づきやすくなります。git branch --show-currentはdetached HEADだと空文字を返します。${branch:-no-git}と書くと、Gitリポジトリ内でも「no-git」と出てしまいます。リポジトリかどうかを先に判定して分けておくと、この誤表示を避けられます。

#!/usr/bin/env bash
input=$(cat)
model=$(echo "$input" | jq -r '.model.display_name')
cwd=$(echo "$input" | jq -r '.workspace.current_dir')
if git -C "$cwd" rev-parse --git-dir >/dev/null 2>&1; then
  branch=$(git -C "$cwd" branch --show-current)
  branch=${branch:-"detached@$(git -C "$cwd" rev-parse --short HEAD)"}
else
  branch="no-git"
fi
echo "🤖 $model | 📁 $(basename "$cwd") | 🌿 $branch"

試しにdetached HEADにしたリポジトリで流すと、ブランチ名が空の場合だけ表示が分かれます。

HEAD detached のとき(${branch:-no-git} だけの書き方) → 🌿 no-git
HEAD detached のとき(上のスクリプト)          → 🌿 detached@ed39b8f
通常のブランチ上(どちらも)                    → 🌿 demo
Gitリポジトリの外(どちらも)                   → 🌿 no-git

コンテキスト使用率とコストを加えた実務構成です。context_window.used_percentageは、セッション序盤で最初のAPIレスポンスが完了する前はnullになり得ます。/compactの直後も、次のAPIレスポンスが返るまではcontext_window.current_usageが再びnullに戻ります。// 0のフォールバックを外した場合と付けた場合で、同じnull入りのJSONを流した結果は次のとおりです。

#!/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"

レート制限が近いときだけ警告を出す例も、実運用で効きます。rate_limitsは環境によってフィールドごと存在しないので、// 0で埋めると「0%」と表示してしまいます。APIキー課金のように存在しない環境でも、制限が0%だと読めてしまう表示です。// emptyで空のまま受け、空なら何も出さない書き方が安全です。

#!/usr/bin/env bash
input=$(cat)
five_hour=$(echo "$input" | jq -r '.rate_limits.five_hour.used_percentage // empty')
[ -z "$five_hour" ] && exit 0
if (( $(echo "$five_hour > 80" | bc -l) )); then
  echo "⚠️ 5h制限 ${five_hour}%"
else
  echo "5h制限 ${five_hour}%"
fi

rate_limitsが無いJSONでは何も出さずに終了コード0で終わり、used_percentageが85.2のJSONでは⚠️ 5h制限 85.2%が出ることを確かめています。// 0で埋める書き方にすると、rate_limitsが無いJSONでも5h制限 0%と表示されます。

いずれの構成でも、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対応に依存し、対応していない環境では文字化けします。Claudeにスクリプトを書かせるとアイコンの文字自体が落ちることもあり、その切り分けはClaude CodeでNerd Fontのアイコンが消える原因にまとめています。

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

複数行の出力もできますが、v2.1.141より前のバージョンでは、いずれかの行が端末幅を超えると行が欠落したり崩れたりする不具合がありました。ANSIカラーやOSC 8リンクを含む複数行は、1行のプレーンテキストより描画が崩れやすい点にも注意が要ります。表示が乱れたときは、まずプレーンテキストに単純化して切り分けます。

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

#!/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

サンプルJSONを流して出力をcat -vで見ると、次の並びになりました。URLと表示テキストをシーケンスが挟む形が確認できます。

^[]8;;https://github.com/anthropics/claude-code/pull/1234^[\PR #1234^[]8;;^[\

リンクとして描画されるかは、ターミナル側の対応で決まります。具体的な対処は後述の「よくあるつまずき」で扱います。

キャッシュ設計 — 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環境で問題が起きます。エラーの前にファイルシステムのレポートが標準出力に出てしまい、そのままコマンド置換に取り込まれて後続の算術評価を壊すためです。

macOSではstat -cがillegal optionで失敗し、2つ目のstat -f %mにフォールバックします。同じsession_idのJSONを続けて流すと、1回目はgitを実行し、直後の2回目はキャッシュを読み、6秒待った3回目はgitを再実行しました。5秒程度のキャッシュを挟むだけで、Git情報のような重い処理でも体感の遅延はほぼ消えます。キャッシュファイルをセッションより長く残したくない場合は、セッション終了時に削除する処理を別途仕込みます。

subagentStatusLineとstatusLineの違い

subagentStatusLineはstatusLineとは対象・入力・出力の3点が異なる設定です。statusLineがメインセッションの1行(または複数行)を組み立てるのに対し、subagentStatusLineはプロンプト下のエージェントパネルに並ぶサブエージェントごとの行を差し替えます。既定ではname · description · token countという行が並んでおり、subagentStatusLineを設定するとこの行のフォーマットを自分で組み立てられるようになります。

実務上の一番の違いは「部分的な上書き」です。subagentStatusLineは全タスクを毎回書き換える必要がなく、強調したい行だけidを指定してJSON Lineを返し、それ以外は省略して既定表示に任せる、という運用ができます。有効・無効の判定はstatusLineと同じく、ワークスペーストラスト・disableAllHooks・allowManagedHooksOnlyのゲートを共有します。

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以降に追加されたフィールドです。effortはlow〜maxの文字列のほか、数値のトークン予算が入ることもあり、設定された値がそのまま報告されます。

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

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

自作スクリプトかccstatuslineか

公式ドキュメントは、コミュニティ製のプロジェクトを2つ紹介しています。ccstatusline(GitHub: sirmalloc/ccstatusline)とstarship-claude(GitHub: martinemde/starship-claude)です。どちらもテーマや追加機能を備えた構成済みのstatuslineで、自分でスクリプトを書かずに導入できる選択肢です。

判断の軸は、表示したい項目が既製の構成に収まるかどうかです。すでにstarshipプロンプトを使っている環境なら、名前のとおりstarship-claudeが候補になります。特定のフィールドの組み合わせや、本稿のレシピのような条件分岐つきの警告を細かく制御したい場合は、自作スクリプトのほうが小回りが利きます。

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

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

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

よくあるつまずき

何も表示されないときの原因は1つに絞れません。次の順に確認すると、手元で切り分けやすくなります。

上の順で見つからない症状は、次の表で切り分けます。

起動や認証まわりの不具合は、Claude Codeでよくあるエラー10選に対処法があります。

まとめ

statuslineの設定自体はtypeとcommandの2行で始められます。設計の本題はその先で、stdinのJSONから何を選んで表示するかです。レシピで見たとおり、nullのフォールバックと「存在しないフィールドを0で埋めない」書き分けが、statuslineが消える事故と誤表示の両方を防ぎます。