Claude Codeのステータスラインをカスタマイズする

ステータスラインは、Claude Code の画面下部に常時表示されるカスタマイズ可能なバーです。任意のシェルスクリプトを実行し、その標準出力をそのまま表示します。コンテキストウィンドウの使用率、セッションのコスト、Git のブランチ状態などを常に目に入る場所へ置けます。これは Anthropic 公式の Claude Code に実在する機能です。

ステータスラインとは

ステータスラインは、あなたが設定した任意のシェルスクリプトを実行し、その出力を Claude Code 下部に表示する仕組みです。組み込みのフッターバッジを置き換えるものではなく、その上に独立した行として描画されます。

公式ドキュメントでは、次のような場面で役立つと説明されています。

作業しながらコンテキストウィンドウの使用量を把握したいとき
セッションのコストを追いたいとき
複数セッションを行き来していて、どれがどれか区別したいとき
Git のブランチと状態を常に見えるようにしたいとき

なお、会話中に現れた ID をフッターのバッジとしてクリック可能にしたいだけなら、スクリプトを書かずに設定の footerLinksRegexes を使う方法もあります。

設定する

設定方法は2通りあります。/statusline コマンドに自然言語で指示して Claude Code に生成させるか、自分でスクリプトを書いて設定ファイルに登録するかです。

/statusline は表示したい内容を言葉で受け取り、~/.claude/ にスクリプトを作成して設定まで自動で更新します。

/statusline show model name and context percentage with a progress bar

セットアップ中にファイル編集の許可を求められた場合は承認してください。

手動で設定する場合は、ユーザー設定（~/.claude/settings.json）またはプロジェクト設定に statusLine を追加します。type を "command" にし、command にスクリプトのパスかインラインのシェルコマンドを指定します。

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

command はシェルで実行されるため、スクリプトファイルの代わりにインラインのコマンドを書くこともできます。次の例は jq で JSON を解析し、モデル名とコンテキスト使用率を表示します。

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

任意の項目として次の3つがあります。

padding: ステータスライン内容の左右の余白を文字数で足します。既定は 0 です。インターフェース標準の余白に加算されるため、端末の端からの絶対距離ではなく相対的なインデントを制御します。
refreshInterval: イベント駆動の更新に加えて、N 秒ごとにコマンドを再実行します。最小値は 1 です。時計のような時刻依存の表示や、メインセッションが待機中にバックグラウンドのサブエージェントが Git の状態を変える場合に指定します。指定しなければイベント時のみ実行されます。
hideVimModeIndicator: プロンプト下に出る組み込みの -- INSERT -- 表示を抑制します。スクリプト側で vim.mode を描画しているときに true にすると、二重表示を防げます。

やめたいときは /statusline delete のように削除を依頼するか、settings.json から statusLine を手で消します。

仕組み

Claude Code はスクリプトを実行し、セッションの JSON データを標準入力へ流し込みます。スクリプトはそれを読んで必要な項目を取り出し、標準出力へ文字列を出します。Claude Code は出力された内容をそのまま表示します。

実行されるタイミングは、セッション開始時（再開時を含む）に一度と、その後は次の場合です。

アシスタントの新しいメッセージが届いたとき
/compact が完了したとき
権限モードが変わったとき
Vim モードが切り替わったとき
refreshInterval を設定している場合、そのタイマーが経過したとき

更新は 300 ミリ秒でデバウンスされ、短時間に連続した変化はまとめられて1回だけ実行されます。実行中に次の更新契機が来た場合、走っているスクリプトはキャンセルされます。スクリプトを書き換えた場合、その内容は次の更新契機で反映されます。

出力については、echo や print ごとに1行として表示されます。色は \033[32m のような ANSI エスケープコードで指定できます（端末側の対応が必要です）。OSC 8 エスケープシーケンスを使えばクリック可能なリンクにできますが、iTerm2・Kitty・WezTerm のようにハイパーリンクに対応した端末が必要です。

端末幅にあわせて出力を調整したい場合、Claude Code はスクリプトの出力を横取りしていて端末に直結していないため、スクリプト内から tput cols では端末サイズを取得できません。代わりに、Claude Code が実行前に設定する環境変数 COLUMNS と LINES を読んでください。

ステータスラインはローカルで動作し、API トークンを消費しません。補完候補・ヘルプメニュー・権限プロンプトなど一部の UI 操作中は一時的に非表示になります。

渡されるデータ

標準入力に渡される JSON には、たとえば次のような項目が含まれます。

model.id / model.display_name: 現在のモデルの識別子と表示名
cwd / workspace.current_dir: 現在の作業ディレクトリ。両者は同じ値で、workspace.project_dir との一貫性から workspace.current_dir の使用が推奨されています
workspace.project_dir: プロジェクトのディレクトリ
context_window.used_percentage: コンテキストウィンドウの使用率
vim.mode: Vim モードの状態

値が入っていない場合に備え、jq の // 0 のような既定値を書いておくと表示が壊れません。項目の完全な一覧は公式ドキュメントの Available data を確認してください。

実装例

公式ドキュメントの手順に沿って、モデル名・作業ディレクトリ・コンテキスト使用率を表示する最小構成を作ります。まず ~/.claude/statusline.sh を用意します。ここでは JSON を解析するために jq を使います（未導入なら別途インストールが必要です）。

#!/bin/bash
# Claude Code が標準入力へ送る JSON を読む
input=$(cat)

# jq で項目を取り出す
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# "// 0" は値が null のときの既定値
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# ${DIR##*/} でフォルダ名だけを取り出して出力する
echo "[$MODEL] ${DIR##*/} | ${PCT}% context"

次に実行権限を付けます。

chmod +x ~/.claude/statusline.sh

最後に ~/.claude/settings.json へ登録します。

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

このスクリプトは Bash なので macOS と Linux で動きます。Windows では PowerShell や Git Bash 向けの書き方が公式ドキュメントの Windows configuration に掲載されています。公式にはこのほか、色付きの Git 状態表示、コストと経過時間の追跡、複数行表示、クリック可能なリンク、レート制限の使用状況、重い処理のキャッシュといった例も載っています。

注意点

スクリプトはセッション開始時とイベント発生時にしか走りません。時刻表示など時間で変わるものを出すなら refreshInterval を設定してください。
外部コマンドの呼び出しが重いと、更新のたびに待たされます。公式の Cache expensive operations の例のように結果をキャッシュする作りにしてください。
端末幅は tput cols では取れません。COLUMNS と LINES を読みます。
色やクリック可能なリンクは端末側の対応が前提です。対応していない端末ではエスケープシーケンスがそのまま文字として出ることがあります。
スクリプト側で vim.mode を表示するなら hideVimModeIndicator を true にして、組み込み表示との重複を避けます。

Claude Codeのステータスラインをカスタマイズする

ステータスラインとは

設定する

仕組み

渡されるデータ

実装例

注意点

関連チュートリアル