創刊準備号 · 2026年秋English · RSS
AgentKoji

Claude Codeのstatusline設定

statuslineの更新は300msの間隔でまとめられ、1回だけ動きます。設定の書き方、渡されるJSON、スクリプトの例が分かります。

要点（TL;DR）

  • statusline は、自分で書いたスクリプトの出力を画面の下に表示する仕組みです。セッションの情報が JSON で stdin に渡されます。
  • 入口は /statusline コマンドか、settings.json の statusLine（type、command、padding、refreshInterval）です。
  • 最初の API の応答までは null のフィールドがあるので、jq では // 0 のように既定値を付けます。cost.total_cost_usd は手元の推定値です。

statusline は、Claude Code の画面の下に、自分で書いたスクリプトの出力を表示する仕組みです。Claude Code がセッションの情報を JSON にしてスクリプトの stdin に渡し、スクリプトが stdout に出したものがそのまま表示されます。この記事では、設定の入口、スクリプトに渡される JSON、最小のスクリプト、応用、うまく出ないときの確かめ方を順に説明します。編集部の検証環境（macOS、Claude Code 2.1.305、jq 1.7.1、2026年10月21日）で、スクリプトにダミーの JSON を流して出力を確かめました。Claude Code のセッションの中で表示されるところは見ていません（未実行）。

設定の入口

入口は2つあります。

1つは /statusline コマンドです。表示したい内容を文章で渡すと、Claude Code が ~/.claude/ にスクリプトを作り、設定も書き換えます。消したいときは /statusline delete のように頼みます。

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

もう1つは、settings.json に statusLine を自分で書く方法です。ユーザーの設定（~/.claude/settings.json）かプロジェクトの設定に置きます。

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 2,
    "refreshInterval": 5
  }
}
キー意味
type"command" を指定する
commandスクリプトのパスか、その場で書くシェルのコマンド
padding左右に足す空白の文字数。既定は 0
refreshIntervalイベントとは別に、N 秒ごとに再実行する。最小は 1。省くとイベントのときだけ動く

出典：https://code.claude.com/docs/en/statusline 、2026-10-21確認

設定ファイルの置き場所と優先順位はpermissions設定の早見表にまとめています。

スクリプトに渡される JSON

主なフィールドです。ほかにもありますが、よく使うものだけに絞りました。

フィールド中身
model.id、model.display_name今のモデルの ID と表示名
workspace.current_dir今の作業ディレクトリ。cwd も同じ値
workspace.project_dirClaude Code を起動したディレクトリ
cost.total_cost_usdセッションの推定コスト（ドル）。手元で定価から計算した値で、請求額とは違うことがある
cost.total_duration_msセッションの経過時間（ミリ秒）
cost.total_lines_added、cost.total_lines_removed足した行数、消した行数
context_window.used_percentageコンテキストの使用率。入力のトークンだけから計算する
context_window.context_window_sizeコンテキストの上限のトークン数
rate_limits.five_hour.used_percentage5時間の利用枠の使用率
rate_limits.seven_day.used_percentage7日の利用枠の使用率
session_id、versionセッション ID と Claude Code のバージョン

最初の API の応答が返るまでは、値が null のフィールドがあります。jq なら // 0 のように既定値を付けます。rate_limits は、claude.ai の Pro・Max の契約者か、spend limit を設定する Claude apps gateway の利用時にだけ、セッションの最初の API 応答のあとに入ります。窓ごとに無いこともあるので、jq では // empty で、無いときは何も出さないようにします。

出典：https://code.claude.com/docs/en/statusline 、2026-10-21確認

いつ更新されるか

スクリプトは、セッションの開始時（再開も含む）に1回動きます。そのあとは、次のときに動き直します。

更新は 300ms の間隔でまとめられ、変化が止まってから1回だけ動きます。command を変えたときだけは、このまとめを待たずにすぐ動きます。スクリプトの実行中に次の更新が来ると、実行中のものは取り消されます。statusline は手元で動くもので、API のトークンは使いません。

出典：https://code.claude.com/docs/en/statusline 、2026-10-21確認

最小のスクリプト

「モデル名｜ディレクトリ名｜git のブランチ｜コンテキスト使用率」を出す例です。

#!/bin/bash
# ~/.claude/statusline.sh: model | directory | git branch | context
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')
BRANCH=$(git -C "$DIR" branch --show-current 2>/dev/null)
echo "[$MODEL] ${DIR##*/} | ${BRANCH:-no git} | ctx ${PCT}%"

chmod +x ~/.claude/statusline.sh で実行権限を付けます。/tmp/todo-app に git init したダミーのリポジトリを作り、ブランチ feature/due-dates に切り替えてから、そこを指す JSON を流した結果です。

$ echo '{"model":{"display_name":"Sonnet"},"workspace":{"current_dir":"/tmp/todo-app"},"context_window":{"used_percentage":23}}' | ~/.claude/statusline.sh
[Sonnet] todo-app | feature/due-dates | ctx 23%

used_percentage を null にすると ctx 0%、git のリポジトリでない /tmp では no git と出ました。どれも終了コードは 0 です。10回続けて実行すると、3回測ってどれも合計 0.246 秒でした。current_dir に ~/projects/todo-app のような ~ で始まる文字列を入れると、git -C ではチルダが展開されず、no git になりました。

応用

重い処理は入れません。 公式は、git status や git diff が大きいリポジトリでは遅いと書き、git の結果を一時ファイルに5秒だけ残す例を載せています。キャッシュのファイル名はセッションごとに分け、session_id を使います。プロセスの ID はスクリプトを呼ぶたびに変わるので使えません。

出典：https://code.claude.com/docs/en/statusline 、2026-10-21確認

output styles とは別物

output styles は、Claude の役割、口調、応答の形をセッション全体で変える指示のまとまりです。Claude の答え方を変えるもので、画面の下の表示とは関係ありません。statusline の JSON には、今の出力スタイルの名前が output_style.name として入っているので、表示することはできます。

出典：https://code.claude.com/docs/en/output-styles 、https://code.claude.com/docs/en/statusline 、2026-10-21確認

うまく出ないとき

症状確かめること
何も出ない実行権限（chmod +x）、stdout に出しているか（stderr ではないか）、手で実行して出力があるか
空になる終了コードが 0 以外、または出力が空だと表示されない
フォルダーを開いたら出ないワークスペースの信頼の確認に同意するまで、statusline は動かない
値が -- や空最初の応答の前は null がある。// 0 で既定値を付ける
ほかの原因を探すclaude --debug で、スクリプトの stderr がログに残る

出典：https://code.claude.com/docs/en/statusline 、2026-10-21確認

編集部の検証環境では、実行権限を外したスクリプトは Permission denied で終了コード 126 でした。PATH から jq を外すと、jq: command not found が stderr に出たうえで、[] | no git | ctx % と崩れた行が終了コード 0 で出ました。jq が無い環境では、エラーにならずに表示が崩れます。スクリプトの書き方で起きる問題は、hook と同じ原因のことが多いので、hooksが動かないときの確認も参考になります。

まとめ