Claude Codeのステータスライン設定｜/statuslineの使い方

Claude Codeのステータスラインは、ユーザー設定の~/.claude/settings.jsonに「statusLine」を書き、「type」を「command」、「command」に表示用スクリプトのパス（またはインラインのシェルコマンド）を指定すると表示されます。入力欄で「/statusline」に続けて見たい内容を書けば、スクリプトの生成と設定の更新までClaude Codeが行います。どちらも設定を保存すると自動で読み直され、画面下部にすぐ表示されます。

この記事では、最小の設定例を先に示し、続けて/statuslineの使い方、スクリプトに渡されるJSONの項目、更新されるタイミング、表示されないときの確認点を整理します。一次情報として参照したのはClaude Code公式ドキュメントのステータスラインのページで、本文中の設定キー名や項目名はそのページにある表記だけを使っています。

この記事の例は、公式ページの例に沿って組み立てた「仮の例」です。自分の環境で試す前に、スクリプトの中身を確認してから使ってください。バージョンによって項目が追加されることがあるため、最終的な仕様は公式ページで確かめるのが安全です。

どこに何を書けば表示されるか｜最小の設定例

ステータスラインは、settings.jsonの「statusLine」に「type」と「command」を書くだけで表示され、「command」には、スクリプトのパスか、標準入力のJSONを読むインラインのシェルコマンドを指定します。

書く場所は、ユーザー設定の~/.claude/settings.json（~はホームディレクトリ）か、公式の設定ページが説明するプロジェクト設定です。スクリプトファイルを作らずに試したいなら、公式ページにあるjqを使った次のインラインの例が最小です。モデル名とコンテキストの使用率だけを出します。

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

保存すると、画面下部に「[モデル名] 使用率% context」の形の1行が出ます。jqはJSONを扱うコマンドラインツールで、環境によっては別途インストールが必要です。表示が出ないときは、後半の「表示されない・おかしいときの確認点」の表で、実行権限、標準出力、ワークスペースの信頼の順に確認してください。

「何を表示するか」を言葉で伝えて任せたい場合は、次の節のとおり、入力欄に「/statusline」と見たい内容を書く方法が使えます。スクリプトを自分で書き、項目を足していく場合は、「スクリプトを自作する手順」の節に、公式ページの手順に沿った3段階があります。

ステータスラインとは何か｜できることと前提

ステータスラインは、Claude Codeの画面下部に出るカスタマイズ可能な帯で、設定したシェルスクリプトにセッションのJSONを渡し、スクリプトが出力した文字列をそのまま表示する仕組みです。

公式ページの説明は、ステータスラインが、設定したシェルスクリプトを実行するカスタマイズ可能なバーで、標準入力でセッションデータのJSONを受け取り、スクリプトが標準出力へ出した内容を表示する、というものです。つまり、表示内容を決めるのはClaude Codeではなく、あなたが用意するスクリプトです。モデル名、作業ディレクトリ、コンテキストの使用率、gitのブランチ名など、スクリプトで取り出せるものなら何でも並べられます。

公式ページが挙げている使いどころは、次の4つです。コンテキストウィンドウの使用状況を作業しながら見たいとき、セッションのコストを追いたいとき、複数のセッションを行き来するので区別したいとき、gitのブランチと状態を常に見えるようにしたいときです。長い作業の途中で「あとどれくらい余裕があるか」が分かるだけでも、会話を区切るタイミングを判断しやすくなります。

ステータスラインは、組み込みのフッターバッジの上にある独立した1行として描画され、既存のバッジを置き換えるものではありません。ただし、カスタムのステータスラインを設定すると、フッターのキーボードヒントの多くは表示されなくなります。公式ページは、その例として「esc to interrupt」「? for shortcuts」「hold space to speak」を挙げています。ヒントが消えたように見えても故障ではなく、仕様どおりの動きです。

もう1点、ステータスラインはローカルで動き、APIトークンを消費しません。公式ページにも、ローカルで実行されAPIトークンを消費しないという注記があります。一方で、ヘルプメニューや権限確認のプロンプトなど、特定のUI操作の間は一時的に非表示になります。表示が消える場面があっても、それだけで設定が壊れたとは限りません。

Claude Code全体の基本操作を先に押さえたい場合は、Claude Code 使い方 ｜インストール・5つの機能を初心者向けに解説・2026年の最新情報が入口になります。この記事は、その先にある表示まわりのカスタマイズだけに絞っています。

/statuslineコマンドで設定する手順

/statuslineは、表示したい内容を自然な言葉で伝えると、Claude Codeが~/.claude/にスクリプトを生成し、settings.jsonも自動で更新してくれるコマンドです。

公式ページの手順は単純です。Claude Codeの入力欄に「/statusline」に続けて、見たい内容を書きます。公式ページの例は「/statusline show model name and context percentage with a progress bar」で、モデル名とコンテキストの割合をプログレスバー付きで表示する指示です。公式の例は英語の文です。日本語で書く場合は、意図どおりに生成されないときに、公式の例に近い短い英語へ直して試すと切り分けられます。

実行すると、Claude Codeが~/.claude/の下にスクリプトファイルを作り、設定ファイルへ「statusLine」を書き込みます。途中でファイル編集の許可を求められた場合は、内容を確認して承認します。権限の考え方に不安がある場合は、Claude Codeの権限設定（permissions）の使い方で、許可・確認・拒否の振り分けを先に確認しておくと落ち着いて判断できます。

仮の例として、次の3つの頼み方を並べます。どれも公式の例の言い回しに倣った書き方で、効果の保証ではなく、試してみる出発点です。

• /statusline show model name and context percentage with a progress bar
• /statusline show the git branch and the current folder name
• /statusline show session cost and elapsed time on a second line

生成されたスクリプトは、そのまま信じ込まずに一度開いて読むことをおすすめします。どんなコマンドを実行し、どのJSON項目を読んでいるかを確認すれば、後で項目を足したり減らしたりするときに迷いません。この記事の後半で、スクリプトの中身を自作する手順を扱うので、読み比べると理解が早まります。

無効化も同じコマンドでできます。公式ページでは、/statuslineを実行して、ステータスラインを削除またはクリアするよう頼む方法が案内されています。例として「/statusline delete」「/statusline clear」「/statusline remove it」が挙げられています。手動で消したい場合は、settings.jsonの「statusLine」フィールドを削除します。

settings.jsonへ手動で設定する方法

手動設定は、ユーザー設定の~/.claude/settings.jsonかプロジェクト設定に「statusLine」を追加し、「type」を「command」にして、「command」にスクリプトのパスまたはインラインのシェルコマンドを書く形です。

設定ファイルの置き場所は、ユーザー設定なら~/.claude/settings.json、プロジェクト単位なら公式の設定ページが説明するプロジェクト設定です。個人の好みで全プロジェクトに効かせたいなら前者、チームで共通の表示にしたいなら後者という使い分けになります。下は、公式ページの形に沿った仮の設定例です。

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

「command」はシェルで実行されるため、前の節のように、スクリプトファイルを作らずインラインのコマンドを書くこともできます。

設定できる任意のフィールドは、公式ページ上で次のように説明されています。

キー	役割（公式ページの記述に沿った要約）	省略したとき
type	「command」を指定する。シェルコマンドを実行するという意味	手動設定では「command」を書く
command	スクリプトのパス、またはインラインのシェルコマンド	手動設定では「command」にスクリプトのパスかインラインコマンドを書く
padding	ステータスラインの内容に足す横方向の余白（文字数）。画面端からの絶対距離ではなく相対的なインデント	0
refreshInterval	イベント駆動の更新に加えて、N秒ごとにコマンドを再実行する。最小値は1	未設定ならイベントでのみ実行
hideVimModeIndicator	プロンプト下の組み込みの「– INSERT –」表示を消す。スクリプト側でvim.modeを表示するときに使う	組み込み表示が出る

設定を保存すると、Claude Codeは設定を自動で読み直し、すぐにスクリプトを実行します。公式ページにも、保存するとClaude Codeが設定を自動で読み直し、すぐにスクリプトを実行するという説明があります。再起動を挟まずに結果を確認できるので、表示を調整するときは、保存して画面を見るという往復を気軽に繰り返せます。

Windowsでの書き方には別の注意点があるため、後ろの節でまとめます。

スクリプトを自作する手順（モデル・ディレクトリ・使用率）

自作の流れは、標準入力のJSONを読むスクリプトを作り、実行権限を付け、settings.jsonで指定する3段階で、公式ページはモデル名・作業ディレクトリ・コンテキスト使用率を出す例で説明しています。

公式の手順に沿って、仮の例として最小のスクリプトを作ります。ここで使うjqは、コマンドラインでJSONを扱うツールで、環境によっては別途インストールが必要になる場合があります。公式ページも、インストールが必要な場合があると断っています。

手順1は、~/.claude/statusline.shとして次の内容を保存することです。

#!/bin/bash
# Read JSON data that Claude Code sends to stdin
input=$(cat)

# Extract fields using jq
MODEL=$(echo "$input" | jq -r '.model.display_name')
DIR=$(echo "$input" | jq -r '.workspace.current_dir')
# The "// 0" provides a fallback if the field is null
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# Output the status line - ${DIR##*/} extracts just the folder name
echo "[$MODEL] ${DIR##*/} | ${PCT}% context"

手順2は、実行権限の付与です。

chmod +x ~/.claude/statusline.sh

手順3は、settings.jsonに「statusLine」を足すことです。

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

この3つが済むと、画面下部に「モデル名、フォルダ名、使用率」が並ぶはずです。スクリプトの中では、標準入力を丸ごと変数に取り込み、jqで項目ごとに取り出し、最後にechoで1行出しています。「// 0」は、項目がnullのときに0を使うための書き方です。セッションの序盤は項目がnullになることがあるため、この保険は外さないほうが安全です。

作ったスクリプトは、Claude Codeに接続せずに手元で試せます。公式ページの「Tips」には、モックのJSONをパイプで渡して動作を確かめる方法が載っています。仮の例として、次のように書きます。

echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh

この確認をしておくと、「表示されない」ときの原因が、スクリプト側にあるのか、設定側にあるのかを切り分けられます。スクリプトは、PythonやNode.jsで書いても構いません。公式ページの例にはBash、Python、Node.jsの3種類が並び、PythonとNode.jsはJSONの解析機能が標準で使えるため、jqが不要です。

スクリプトに渡されるJSONの項目

スクリプトには、モデル、作業ディレクトリ、コスト、コンテキストウィンドウ、レート制限などのセッション情報が、標準入力のJSONとして渡されます。

公式ページの「Available data」には、多くの項目が表で整理されています。ここでは、日常のステータスラインでよく使いそうなものを選んで、公式の説明に沿って整理します。項目の全体は公式ページで確認してください。

項目	内容（公式ページの記述に沿った要約）
model.id / model.display_name	現在のモデルの識別子と表示名
workspace.current_dir	現在の作業ディレクトリ。cwdと同じ値だが、workspace.project_dirとの一貫性からこちらが推奨されている
workspace.project_dir	Claude Codeを起動したディレクトリ。セッション中に作業ディレクトリが変わると、cwdと異なる場合がある
workspace.git_worktree	linked worktree内にいるときのworktree名。メインの作業ツリーでは存在しない
cost.total_cost_usd	セッションのコストの見積り（米ドル）。クライアント側で計算され、実際の請求と異なる場合がある。/clearで新しいセッションを始めると合計がリセットされる（v2.1.211以降）
cost.total_duration_ms	セッションが動いていた総時間（ミリ秒）
cost.total_lines_added / total_lines_removed	変更されたコードの行数
context_window.used_percentage	コンテキストウィンドウの使用率（計算済み）
context_window.remaining_percentage	コンテキストウィンドウの残り率（計算済み）
context_window.context_window_size	コンテキストウィンドウの最大トークン数。既定は200000、拡張コンテキストのモデルは1000000
effort.level	推論の努力レベル。low、medium、high、xhigh、maxのいずれか。モデルが対応していないと存在しない
rate_limits.five_hour / seven_day	5時間・7日のレート制限の消費率（0から100）とリセット時刻（Unixエポック秒）
session_id / session_name	セッションの識別子と、–nameや/renameで付けた名前など
vim.mode	vimモード有効時のモード（NORMAL、INSERT、VISUAL、VISUAL LINE）
output_style.name	現在の出力スタイル名
version	Claude Codeのバージョン
fast_mode / thinking.enabled	fast modeが有効か、拡張思考が有効か
pr.number / pr.url / pr.review_state	現在のブランチに開いているプルリクエストの番号・URL・レビュー状態。見つかったときだけ存在する
prompt_cache.warm / hit_ratio	プロンプトキャッシュが有効期間内か、キャッシュ読み取りの割合（0から1）。最初のAPI応答の後に現れ、Claude Code v2.1.251以降が必要

使うときの注意点が3つあります。1つ目は、存在しない可能性がある項目の扱いです。公式ページは、session_name、workspace.git_worktree、effort、vim、agent、pr、worktree、rate_limits、prompt_cacheなどが、条件を満たすときだけJSONに現れると説明しています。存在しない項目をjqで読んでも落ちないよう、「// empty」や「// 0」のような既定値を付けるのが基本です。

2つ目は、nullになる項目です。context_window.used_percentageとremaining_percentageは、セッションの序盤でnullになることがあり、current_usageは最初のAPI呼び出しの前と、/compactの後の次のAPI呼び出しまでnullです。画面に「–」や空欄が出たら、まずこの点を疑います。

3つ目は、コストの数値の読み方です。cost.total_cost_usdは、クライアント側で計算した見積りで、公式ページは実際の請求額と違うことがあると明記しています。請求の根拠にはしないでください。使用量とコストを実際に確認する流れは、Claude Codeの使用量とコストの確認方法｜/usageの見方と削減策にまとまっています。

コンテキストの使用率について、補足が1つあります。used_percentageは、input_tokens、cache_creation_input_tokens、cache_read_input_tokensの合計だけから計算され、output_tokensは含まれません。自分でcurrent_usageから割合を出す場合も、同じ入力のみの式にしないと、used_percentageと数字が合わなくなります。また、ステータスラインは直近のAPI応答の値を表示するのに対し、/contextは応答後に追加されたメッセージの見積りも足すため、/contextのほうが高く出ることがあります。

セッション名を表示に使いたい場合は、Claude Codeのセッション管理｜–resumeで会話を再開する方法で、名前の付け方と再開の流れを合わせて確認すると、ステータスラインのsession_nameが何を指すのか理解しやすくなります。

更新されるタイミングとrefreshInterval

スクリプトはセッション開始時に1回動き、その後は新しいアシスタントメッセージ、/compactの完了、権限モードやvimモードの切替などのイベントで再実行され、更新は300msでまとめられます。

公式ページの「When it updates」には、再実行されるきっかけが列挙されています。セッション開始時（再開を含む）に1回動いたあと、次の場合に再実行されます。

きっかけ	補足
新しいアシスタントメッセージが届いたとき	メッセージのたびに再実行される
/compactが終わったとき	コンテキスト関連の表示が変わる
権限モードが変わったとき	モード表示を載せるスクリプト向け
vimモードが切り替わったとき	vim.modeを使う場合に関係する
settingsのstatusLineのcommandを変えたとき	デバウンスを飛ばし、新しいコマンドをすぐ実行する
refreshIntervalのタイマーが経過したとき	設定している場合のみ
最後に受け取ったデータ内のレート制限ウィンドウがresets_atに達したとき	リセット時刻に合わせた更新
温まっているプロンプトキャッシュがexpires_atに達したとき	最後に受け取ったデータ内の値が基準

更新は300msでデバウンスされます。短時間に変化が続いても、変化が止まってから1回だけスクリプトが走ります。ただし、statusLineのcommand自体を変えたときはデバウンスを飛ばして即実行されます。また、前の実行がまだ終わっていないうちに次の更新が起きると、実行中のスクリプトはキャンセルされます。スクリプトを編集した場合の変更は、次の更新のきっかけで再実行されたときに画面へ反映されます。

注意したいのは、メインのセッションが待機中のとき、イベント駆動のきっかけが静かになることです。公式ページは、コーディネーターがバックグラウンドのサブエージェントを待っている間などを例に挙げています。時計のような時間で変わる表示や、外部の情報を取り込む表示を、待機中も更新したい場合に使うのがrefreshIntervalです。

仮の例として、10秒ごとに再実行する設定は次のようになります。

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

refreshIntervalを短くするほど、スクリプトが実行される回数は増えます。gitコマンドのように重い処理を含むスクリプトで短い間隔にすると、動作が重くなるおそれがあります。時間表示やバックグラウンド処理の状態を見たいときだけ設定し、不要なら未設定のままにするのが無難です。

サブエージェントを多用する運用では、Claude Codeのサブエージェント使い方｜設定ファイルの書き方と使い所を読むと、待機中に何が動いているのかをイメージしやすくなります。

表示例1｜コンテキスト使用率のプログレスバー

コンテキスト使用率を10マスのバーで見せる表示は、used_percentageを読み、塗りつぶしの文字と空の文字を並べるだけで作れます。

公式ページの「Context window usage」の例に沿った仮の例です。モデル名と10文字のバーを出し、塗りつぶしのブロックが使用量を表します。Bash版は次のとおりです。

#!/bin/bash
# Read all of stdin into a variable
input=$(cat)

# Extract fields with jq, "// 0" provides fallback for null
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

# Build progress bar: printf -v creates a run of spaces, then
# ${var// /▓} replaces each space with a block character
BAR_WIDTH=10
FILLED=$((PCT * BAR_WIDTH / 100))
EMPTY=$((BAR_WIDTH - FILLED))
BAR=""
[ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /▓}"
[ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /░}"

echo "[$MODEL] $BAR $PCT%"

jqを入れたくない場合は、Python版が使えます。公式の例では、json.loadで標準入力をそのまま読み込み、文字列の掛け算でバーを作っています。

#!/usr/bin/env python3
import json, sys

# json.load reads and parses stdin in one step
data = json.load(sys.stdin)
model = data['model']['display_name']
# "or 0" handles null values
pct = int(data.get('context_window', {}).get('used_percentage', 0) or 0)

# String multiplication builds the bar
filled = pct * 10 // 100
bar = '▓' * filled + '░' * (10 - filled)

print(f"[{model}] {bar} {pct}%")

このバーは、あくまで入力側のトークンから計算した使用率の目安です。前の節で触れたとおり、used_percentageには出力トークンが含まれません。バーがまだ余裕を示していても、会話が長くなってきたと感じたら、要約や新しいセッションへの切り替えを検討します。

使い方の仮の例を1つ挙げます。長いリファクタリングの途中でバーが7割を超えてきたら、そこで作業を一区切りにして、次の作業は別のセッションで始める、というルールを自分で決めておきます。数字の基準は、公式が定めたものではなく、あくまで運用上の自分ルールです。複数の作業を並行して分けたい場合は、Claude Codeのworktree使い方｜並列作業を分ける手順の考え方が参考になります。

表示例2｜gitの状態・色・複数行・リンク

色はANSIエスケープコード、複数行はechoやprintの数、クリックできるリンクはOSC 8エスケープシーケンスで表現できます。

公式ページの「What your script can output」によると、出力できる要素は3種類です。複数行は、echoやprintの文ごとに1行ずつ表示されます。色は、緑の「\033[32m」のようなANSIエスケープコードで付けられ、ターミナルが対応している必要があります。リンクはOSC 8エスケープシーケンスで作れ、macOSではCmdクリック、WindowsとLinuxではCtrlクリックで開きます。リンクを使うには、iTerm2、Kitty、WezTermのようにハイパーリンクに対応した端末が必要です。

公式ページの複数行の例は、色のしきい値（70%未満は緑、70から89%は黄、90%以上は赤）、プログレスバー、gitのブランチ名を組み合わせています。ここでは、その骨組みだけを仮の例として示します。

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

CYAN='\033[36m'; GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; RESET='\033[0m'

# Pick bar color based on context usage
if [ "$PCT" -ge 90 ]; then BAR_COLOR="$RED"
elif [ "$PCT" -ge 70 ]; then BAR_COLOR="$YELLOW"
else BAR_COLOR="$GREEN"; fi

FILLED=$((PCT / 10)); EMPTY=$((10 - FILLED))
printf -v FILL "%${FILLED}s"; printf -v PAD "%${EMPTY}s"
BAR="${FILL// /█}${PAD// /░}"

BRANCH=""
git rev-parse --git-dir > /dev/null 2>&1 && BRANCH=" | $(git branch --show-current 2>/dev/null)"

echo -e "${CYAN}[$MODEL]${RESET} ${DIR##*/}$BRANCH"
echo -e "${BAR_COLOR}${BAR}${RESET} ${PCT}%"

1行目にモデルとフォルダとブランチ、2行目にバーと使用率を出す構成です。1行目は「今どこで何を使っているか」、2行目は「あとどれくらい余裕があるか」と役割を分けると、一目で読み取れます。

色やリンクのエスケープシーケンスを多用すると、他のUI更新と重なって表示が乱れることがあります。公式ページのトラブルシューティングにも、複雑なエスケープシーケンスがときどき文字化けの原因になること、複数行にエスケープコードを入れた構成は、1行のプレーンテキストより崩れやすいことが書かれています。表示が崩れたら、まず色や記号を外して、プレーンテキストに戻して試します。

リンクの文字が出るのにクリックできない場合は、端末がハイパーリンク対応と判定されていない可能性があります。公式ページは、Claude Codeを起動する前に環境変数FORCE_HYPERLINKで判定を上書きする方法を示しています。仮の例は次のとおりです。

FORCE_HYPERLINK=1 claude

Terminal.appは、クリックできるリンクに対応していません。SSHやtmux経由では、設定によってOSCシーケンスが取り除かれることがあります。エスケープシーケンスが「\e]8;;」のような文字としてそのまま見える場合は、echo -eの代わりにprintf ‘%b’を使うと扱いが安定する、と公式ページに書かれています。

出力の見た目そのものを整えたい場合は、ステータスラインとは別に、回答の文体を切り替える機能もあります。Claude Codeの出力スタイルの使い方｜切替方法とカスタム作成を読むと、ステータスラインのoutput_style.nameが表示する値の意味も整理できます。

重い処理はキャッシュして使う

ステータスラインのスクリプトはセッション中に頻繁に実行されるため、git statusのような重いコマンドは一時ファイルにキャッシュし、一定秒数ごとにだけ更新するのが公式の推奨する形です。

公式ページの「Cache expensive operations」は、スクリプトが活発なセッション中に頻繁に実行され、git statusやgit diffは大きなリポジトリで遅くなりうる、と説明しています。そこで、git情報を一時ファイルに保存し、5秒ごとにだけ更新する例が示されています。

キャッシュ用ファイル名の決め方には、守るべき条件があります。ファイル名は、同じセッション内の呼び出しでは変わらず、セッション間では重ならない必要があります。そうでないと、別々のリポジトリで動く複数のセッションが、お互いのキャッシュを読んでしまいます。公式ページは、プロセスIDのように呼び出しごとに変わる識別子は使えないと述べ、例ではJSONのsession_idをファイル名に使っています。仮の例として骨組みを示します。

SESSION_ID=$(echo "$input" | jq -r '.session_id')

CACHE_FILE="/tmp/statusline-git-cache-$SESSION_ID"
CACHE_MAX_AGE=5  # seconds

この後に、キャッシュファイルが存在しないか、更新から5秒を超えているときだけgitコマンドを走らせ、結果をファイルに書く処理を続けます。それ以外のときはファイルから読むだけなので、表示は軽く保てます。

前の実行が終わる前に次の更新が来ると、実行中のスクリプトはキャンセルされます。遅いスクリプトは、更新が間に合わず表示が古いままになる原因にもなります。公式ページのトラブルシューティングにも、遅いスクリプトは完了するまで更新を止めるため、古い出力を避けるには速さを保つこと、と書かれています。

キャッシュの秒数は、表示の新鮮さと負荷のバランスで決めます。ブランチ名はめったに変わらないので数秒空いても困りませんが、変更ファイル数をリアルタイムで見たいなら短くします。一方で、refreshIntervalを短くしてキャッシュも短くすると、負荷が重なります。どちらか一方を詰めるつもりで調整してください。

フックやコマンドの実行をまとめて自動化したい場合は、Claude Codeのフック（hooks）の使い方｜設定の書き方とイベント一覧が役に立ちます。ステータスラインのコマンドも、ワークスペースの信頼について、settingsファイルのフックと同じルールで扱われます。

表示されない・おかしいときの確認点

表示されないときは、実行権限、標準出力への出力、手動実行での確認、ワークスペースの信頼、管理設定の順に切り分けるのが近道です。

公式ページの「Troubleshooting」を、症状別に整理すると次のようになります。

症状	確認すること（公式ページの記述に沿って）
ステータスラインが出ない	スクリプトの実行権限（chmod +x）、出力が標準出力であること（標準エラーではない）、手動実行で出力が出るか
出ない（Windows）	Git Bashがある環境で、commandのパスのバックスラッシュがエスケープとして消費されている可能性。スラッシュで書く
出ない（管理設定）	管理設定でdisableAllHooksがtrueになっていないか。組織がallowManagedHooksOnlyを設定していると、自分のステータスラインは警告なしに消え、管理設定のstatusLineだけが使える
「–」や空欄になる	最初のAPI応答の前は項目がnullになりうる。jqの「// 0」のような既定値を使う。複数回メッセージを送っても空なら再起動を試す
使用率が想定と違う	used_percentageを使う。/contextは追加メッセージの見積りも足すため、高く出ることがある
ブランクになる・止まる	終了コードが0以外、または出力がないとブランクになる。遅いスクリプトは更新を止める
ワークスペースの信頼	信頼を受け入れるまでブランクのまま。claude –debugに「Status line command skipped: workspace trust not accepted」と出る。再起動して信頼ダイアログを承認する

切り分けの順番として、次のような流れを仮の例として提案します。最初に、スクリプトをターミナルで直接実行して、出力が出るかを見ます。次に、モックのJSONをパイプで渡して、項目の読み取りが合っているかを見ます。それでも原因が分からない場合は、claude –debugで起動します。公式ページによると、このデバッグモードは、ステータスラインが呼ばれるたびにスクリプトの標準エラー出力を記録し、セッション内の最初の呼び出しでは終了コードも記録します。

もう1つの方法は、Claudeに設定ファイルを読ませ、statusLineのコマンドをそのまま実行させて、エラーを表面化させることです。公式ページにも、この方法が書かれています。自分で調べてもよく分からないときの確認手段になります。

ステータスラインは、シェルコマンドを実行する機能なので、信頼していないフォルダでは動きません。公式ページは、フォルダの信頼ダイアログを承認すれば足りると説明しています。信頼の範囲は、親ディレクトリの信頼が子にも及ぶ場合があります。見知らぬリポジトリを開いたときにステータスラインが空なのは、安全のための挙動で、バグではありません。

設定が複数の層に分かれている環境では、どの層の設定が効いているのかが分かりにくくなります。プロジェクトの方針を書く場所も含めて整理したい場合は、Claude CodeのCLAUDE.md書き方｜配置場所・読み込み順・運用手順が、設定と指示の置き場所を考える助けになります。

WindowsとサブエージェントのstatusLine設定

Windowsでは、Git Bashがあるときはそれ経由、ないときはPowerShell経由でコマンドが実行され、パスはスラッシュで書くのが公式の注意点です。サブエージェント向けにはsubagentStatusLineという別の設定があります。

Windowsについて、公式ページには次の説明があります。Claude Codeは、Git Bashがインストールされていればそれを通して、なければPowerShellを通してステータスラインのコマンドを実行します。Git Bashは引用符のないバックスラッシュをエスケープ文字として扱うため、「C:\Users\username\script.mjs」のようなパスは区切りが消え、目に見えるエラーなしに失敗します。commandの文字列では、スラッシュ区切りで書きます。「~」も使え、Windowsのホームディレクトリに展開されます。

PowerShellのスクリプトを使うなら、powershell経由で呼び出します。これは、Git Bash経由でもPowerShell経由でも動きます。仮の設定例は次のとおりです。

{
  "statusLine": {
    "type": "command",
    "command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
  }
}

スクリプト側は、標準入力のJSONをConvertFrom-Jsonで読み、cwdやmodel.display_nameを取り出して、Write-Hostで出力します。Git Bashが入っている環境なら、Bashスクリプトをそのまま指定する方法もあります。

サブエージェント向けの「subagentStatusLine」は、メインのstatusLineとは別の設定です。公式ページによると、エージェントパネルに表示される各サブエージェントの行の本文を、独自の形式に置き換えられます。既定の「名前・説明・トークン数」の行を差し替えるイメージです。設定の形は、statusLineと同じく「type」と「command」です。

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

このコマンドは、更新のたびに1回実行され、表示されている全サブエージェントの行を、1つのJSONオブジェクトとして標準入力で受け取ります。入力には、フック共通の基本フィールド、使える行幅を示すcolumns、そしてtasks配列が含まれます。各taskには、id、name、type、status、description、label、startTime、model、effort、contextWindowSize、tokenCount、tokenSamples、cwdがあります。出力は、変更したい行ごとに「{“id”: “<task id>”, “content”: “<row body>”}」の形のJSONを1行ずつ標準出力に書きます。idを省くとその行は既定の表示のままで、contentを空文字にすると行が隠れます。

subagentStatusLineにも、statusLineと同じ信頼の確認、disableAllHooks、allowManagedHooksOnlyの制約がかかります。プラグインが既定のsubagentStatusLineを同梱することはできますが、フックと違い、allowManagedHooksOnly下では、管理設定でプラグインが強制有効でも実行されません。組織の管理設定が絡む環境では、この点を管理者と確認してください。プラグイン全般の仕組みは、Claude Codeのプラグインの使い方｜インストール・自作・配布までで扱っています。

運用のコツと、使いどころの判断

ステータスラインは、見たい情報を絞り、短く、速く、失敗しても止まらないように作ると、日々の作業で邪魔にならず役立つ表示になります。

ここまでの公式ページの内容から、運用のコツを3つに絞ります。1つ目は、出力を短くすることです。公式ページの「Tips」にも、ステータスバーの幅は限られており、長い出力は切り詰められたり、不自然に折り返されたりする、と書かれています。幅に合わせたい場合は、環境変数COLUMNSとLINESを読みます。Claude Codeはスクリプトの出力を端末に直接つなぐのではなく取り込むため、tput colsのような端末幅の取得は、スクリプトの中では使えません。

2つ目は、速さです。セッション中に頻繁に走るので、重いコマンドはキャッシュします。遅いスクリプトは更新を止め、実行中のものは新しい更新でキャンセルされます。3つ目は、失敗しても落ちない書き方です。終了コードが0以外、または出力がなければ、ステータスラインはブランクになります。項目がnullのときの既定値を用意し、エラーが出ても何かしらの文字列を返す設計にしておくと、表示が空になる場面を減らせます。

仮の例として、目的別の組み合わせを表にします。数値のしきい値や項目の選び方は、公式の指定ではなく、運用の一例です。

目的	使う項目の例	更新の考え方
長い作業の余裕を見たい	context_window.used_percentage、model.display_name	イベント駆動のままで足りる
複数セッションを区別したい	session_name、workspace.current_dir、workspace.git_worktree	イベント駆動のままで足りる
利用枠の消費を気にしたい	rate_limits.five_hour.used_percentage、rate_limits.seven_day.used_percentage	リセット時刻でも更新される
時計や外部情報を出したい	スクリプト内で取得する値	refreshIntervalを設定し、重い処理はキャッシュする

利用枠の消費を出す場合は、rate_limitsがclaude.aiのProとMaxの購読者、またはspend limitを設定したClaude appsゲートウェイ経由の場合に限って存在し、最初のAPI応答の後にだけ現れる点に注意します。5時間と7日のウィンドウは、それぞれ独立して欠けることがあります。公式の例でも、存在しないときのため「// empty」を使っています。

非対話で使う場面とステータスラインの関係も整理しておくと、混乱しません。ステータスラインは、対話画面の下部に出る表示です。スクリプトやCI向けの非対話実行を使う場合は、画面表示を前提にしないほうが安全です。非対話実行の考え方は、Claude Codeのヘッドレスモードとは｜-pで非対話実行する使い方が参考になります。

最後に、既存の設定を壊さないための進め方です。まず/statuslineで試し、生成された内容を読み、気に入らなければ「/statusline delete」で消す。残したい場合は、スクリプトの中身を自分で読めるようにしておく。この流れなら、元に戻す手間を最小に抑えながら、少しずつ自分向けに育てられます。

よくある質問（FAQ）

Q1. ステータスラインの設定はどこに書きますか。

ユーザー設定の~/.claude/settings.json、またはプロジェクト設定の「statusLine」フィールドに書きます。typeを「command」にし、commandにスクリプトのパスかインラインのシェルコマンドを指定します。/statuslineコマンドを使えば、スクリプトの生成と設定の更新を自動で行ってくれます。

Q2. /statuslineでは日本語で頼めますか。

公式ページには、自然言語の指示を受け付けると書かれており、例は英語の文です。日本語で頼む場合も、意図どおりに生成されないときは、公式の例に近い短い英語に言い換えて試すと切り分けやすくなります。

Q3. スクリプトを編集したのに表示が変わりません。

スクリプトの編集は、次の更新のきっかけでスクリプトが再実行されたときに反映されます。すぐ確認したい場合は、新しいメッセージを送るか、settingsのcommandを書き換えて保存します。commandの変更はデバウンスを飛ばしてすぐ実行されると、公式ページに書かれています。

Q4. 画面に「–」や空欄が出るのはなぜですか。

最初のAPI応答が完了する前は、使用率などの項目がnullになることがあるためです。jqの「// 0」のような既定値を付けて対処します。複数回メッセージを送っても空のままなら、Claude Codeを再起動して確認します。

Q5. ステータスラインはAPIの利用枠を消費しますか。

公式ページには、ステータスラインはローカルで動き、APIトークンを消費しないと書かれています。ただし、スクリプトの中で自分が外部のコマンドやサービスを呼ぶ場合は、そちらの負荷や条件を別に考える必要があります。

Q6. 表示されるコストは請求額と同じですか。

同じとは限りません。cost.total_cost_usdは、クライアント側で見積りとして計算される値で、公式ページも実際の請求と異なる場合があると明記しています。請求の確認には使わず、目安として扱ってください。

Q7. 時計のような時間表示は、待機中も動きますか。

イベント駆動の更新だけでは、メインのセッションが待機中に更新が止まることがあります。時間で変わる表示を保ちたいときは、refreshIntervalに秒数を設定して、一定間隔でコマンドを再実行します。最小値は1です。

Q8. Windowsで何も表示されません。

Git Bashが入っている環境では、commandのパスに含めたバックスラッシュがエスケープとして消費され、エラーが見えないまま失敗することがあります。パスはスラッシュ区切りで書き直し、PowerShellのスクリプトを使うなら、powershell経由で呼び出してください。

まとめ

Claude Codeのステータスラインは、自分のスクリプトの出力を画面下部に出す機能で、設定は/statuslineコマンドか、settings.jsonの「statusLine」で行います。スクリプトにはモデル、作業ディレクトリ、コスト、コンテキスト使用率、レート制限などのJSONが標準入力で渡され、更新はイベントと、必要に応じてrefreshIntervalで制御されます。

始めるなら、次の順番が無理のない進め方です。まず/statuslineでモデル名と使用率のバーを表示する。生成されたスクリプトを読み、jqの使い方と項目名を理解する。必要に応じてgitの情報や複数行、色を足す。重い処理はキャッシュし、時間表示が必要なときだけrefreshIntervalを使う。表示されないときは、実行権限、標準出力、手動実行、ワークスペースの信頼の順に確認します。

この記事の設定やスクリプトは、公式ページの例に沿った仮の例です。最新の項目や挙動は、変わることがあります。実際に設定する前に、Claude Code公式ドキュメントのステータスラインのページを開いて、現在の記述を確かめてください。