Claude Code statuslineステータスラインのカスタマイズと使い方を徹底解説

Claude Code の /statusline コマンドは、ターミナル下部に常駐する情報バー（ステータスライン）を設定するためのスラッシュコマンドだ。モデル名・コンテキスト残量・セッションコスト・Git ブランチといった開発中に何度も確認したい情報を一目で把握できるようにする。設定はチャット内で自然言語を入力するだけで完結し、生成されたスクリプトと設定値は ~/.claude/settings.json に自動保存される。本記事では、仕組みの理解から実用スクリプトの実装、運用上の注意点まで順を追って解説する。

Claude Code statuslineとは何か：仕組みと設計思想

ステータスラインの核心は、任意のシェルスクリプトを実行し、その標準出力をそのまま表示するという設計にある。Claude Code はセッション情報を JSON 形式で標準入力（stdin）に送り込み、スクリプト側がそれを受け取って整形・出力するパイプライン構造になっている。スクリプトが出力する内容はすべて表示できるため、コンテキストウィンドウの使用率・セッションコスト・Git ブランチ状態・システム指標など、開発者が必要な情報を自由に組み合わせられる。

この機能が特に有用な場面は以下のとおりだ。

• 作業中にコンテキストウィンドウの使用量を監視したいとき
• セッションのコストをリアルタイムでトラッキングしたいとき
• 複数セッションを並行して動かし、セッションを区別する必要があるとき
• Git ブランチと状態を常時表示して誤操作を防ぎたいとき

この設計が持つ技術的トレードオフも把握しておきたい。スクリプトはUI の更新ごとに実行されるため、処理の重いコマンド（リモート API コール、大量のファイル I/O など）を仕込むとターミナルのレスポンスが劣化する。ローカル情報の参照と軽量な計算に留めることが実装上の大前提だ。

Claude Code の基本的なインストール手順や初期設定については、Claude Codeのインストール手順およびClaude Code入門ガイドを参照されたい。

Claude Code statuslineのカスタマイズ設定：2つのアプローチ

ステータスラインを有効化する方法には、/statusline コマンドによる自動生成と、settings.json への手動記述の2通りがある。目的に応じて使い分けるとよい。

/statuslineコマンドによる自動生成

最も手軽な方法は、Claude Code のチャットで /statusline スラッシュコマンドを使うことだ。引数なしで実行するとシェルのプロンプト情報をもとに自動設定してくれる。やりたいことを自然言語で続けて記述すれば、それに合ったスクリプトを生成してくれる。

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

このように入力すると、Claude Code が ~/.claude/ 配下にスクリプトファイルを生成し、~/.claude/settings.json の statusLine フィールドを自動で更新する。生成されたスクリプトの中身は確認・編集できるため、自動生成をたたき台にして手作業で調整するワークフローが効率的だ。スラッシュコマンドの全体像についてはClaude Codeスラッシュコマンド一覧と使い方も合わせて参照してほしい。

settings.jsonへの手動設定

細かい制御が必要な場面では、ユーザー設定ファイル（~/.claude/settings.json）またはプロジェクト設定に直接 statusLine フィールドを追加する。設定形式は以下のとおりだ。

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

type に "command" を指定し、command にスクリプトファイルへのパスを記述する。プロジェクト固有の表示が必要な場合は、プロジェクトルートの .claude/settings.json に同じ形式で書けばよい。ユーザー設定よりプロジェクト設定が優先されるため、チーム開発でプロジェクト設定をリポジトリに含める際は、スクリプトのパスがメンバー全員の環境で有効かどうかを事前に確認する必要がある。

statuslineが受け取るJSONフィールド：使い方の核心

スクリプトが活用できるデータは、Claude Code が stdin へパイプする JSON オブジェクトに含まれる。主要フィールドを以下の表に整理する。

表1：statuslineスクリプトが受け取るJSONフィールド一覧

フィールド名	型	内容	主な用途
model	string	使用中のモデル名	モデル切替の視認確認
contextWindow.used	number	使用済みトークン数	コンテキスト使用率の計算
contextWindow.total	number	コンテキストウィンドウの上限トークン数	残量把握・プログレスバー表示
session.cost	number	セッション累積コスト（USD）	コスト監視・予算管理
session.duration	number	セッション経過時間（秒）	作業時間の把握
git.branch	string	現在の Git ブランチ名	誤ブランチでの操作防止
git.status	string	Git の作業ツリー状態	未コミット変更の確認
cwd	string	カレントワーキングディレクトリ	複数セッションの識別

スクリプトでのデータ取り出しには jq を使うのが定番だ。// 演算子で null の場合のデフォルト値を設定する null 安全な書き方を習慣にするとよい。コンテキスト使用率を計算するだけなら以下の形で済む。

#!/bin/bash
INPUT=$(cat)
USED=$(echo "$INPUT" | jq '.contextWindow.used // 0')
TOTAL=$(echo "$INPUT" | jq '.contextWindow.total // 1')
PERCENT=$(echo "scale=1; $USED * 100 / $TOTAL" | bc)
echo "Context: ${PERCENT}%"

セッションコストのリアルタイム把握は、長時間エージェント実行の予算管理に直結するため、最初に実装する価値が高い。コスト面の詳細についてはClaude Codeの料金体系やClaude Code APIの価格詳細も参考になる。

利用可能な全JSONフィールド一覧（公式ドキュメント準拠）

statuslineスクリプトがstdin経由で受け取れるJSONフィールドは、上記で紹介した主要項目だけではありません。Anthropic公式ドキュメント（code.claude.com/docs/ja/statusline）で定義されている全フィールドを、カテゴリ別に整理すると次のとおりです。

カテゴリ	フィールド	内容
基本情報	model.id / model.display_name	現在のモデル識別子と表示名
	cwd / workspace.current_dir	現在の作業ディレクトリ（両者は同じ値）
	workspace.project_dir / workspace.repo.*	起動時のディレクトリ、および origin リモートから解析したリポジトリ情報（host/owner/name）
コスト・時間	cost.total_cost_usd	セッションの推定コスト（クライアント側計算。実請求額と異なる場合あり）
	cost.total_duration_ms / cost.total_api_duration_ms	総経過時間とAPI応答待ち時間
コンテキストウィンドウ	context_window.used_percentage / remaining_percentage	事前計算済みの使用率・残量率
	context_window.context_window_size	最大コンテキストサイズ（既定200,000、拡張コンテキストモデルは1,000,000）
レート制限	rate_limits.five_hour.used_percentage / seven_day.used_percentage	Pro/Maxサブスクライバーのみ、最初のAPI応答後に出現
その他	session_id / version / vim.mode / agent.name / pr.number / worktree.name など	vimモード表示中・PR検出時・worktreeセッション中のみ出現するオプション項目

注意（git情報の取得方法について）：gitブランチ名やステージング状況は、上記のJSON入力そのものには含まれません。stdinで渡されるのは workspace.repo.host/owner/name（originリモートの識別情報）までで、現在のブランチ名や変更ファイル数を表示するには、スクリプト内で git branch --show-current や git diff --numstat などのgitコマンドを別途実行して取得する必要があります。本記事の「実用的なstatuslineスクリプト例」で示したgit連携スクリプトも、この方式でgit情報を取得しています。

Windows環境でのstatusline設定（PowerShell / Git Bash）

Windowsでは、Claude CodeはstatuslineコマンドをGit Bash経由で実行し、Git Bashが無い場合はPowerShellにフォールバックします。PowerShellスクリプトを使う場合は、settings.jsonから powershell 経由で呼び出します。

実行環境	設定例
PowerShell	"command": "powershell -NoProfile -File C:/Users/username/.claude/statusline.ps1"
Git Bash（インストール済みの場合）	"command": "~/.claude/statusline.sh"（macOS/Linuxと同じBashスクリプトがそのまま動く）

PowerShellスクリプト側では、stdinのJSONを ConvertFrom-Json で受け取り、$input_json.model.display_name のようにドット記法でフィールドへアクセスする点がBash（jqでのパース）と異なります。

よくある不具合と対処（トラブルシューティング）

症状	主な原因と対処
ステータスラインが表示されない	スクリプトに実行権限があるか（chmod +x）、stdoutに出力しstderrに出していないか、disableAllHooks が有効になっていないかを確認する
-- や空値が表示される	最初のAPI応答が完了する前は該当フィールドが null になる。スクリプト側で // 0 等のフォールバックを入れる
コンテキスト割合が想定と違う	used_percentage は入力トークンのみから算出され、/context コマンドの表示とは計算タイミングが異なるため一致しないことがある
OSC8リンクがクリックできない	ターミナルがOSC8ハイパーリンクに対応している必要がある（iTerm2/Kitty/WezTermは対応、Terminal.appは非対応）。Windows Terminal等では起動前に FORCE_HYPERLINK=1 を設定する

設定直後に反映されない場合は、Claude Codeとの次のやり取りが発生するまで変更が表示されない仕様のため、一度メッセージを送ってから確認するとよいでしょう。

実用的なstatuslineスクリプト例と運用上のトレードオフ

実際の開発で役立つパターンを示す。コミュニティでの実装知見（Zenn – Claude Codeのstatuslineをカスタマイズする、レートリミット・コンテキスト使用率をリアルタイム表示する方法）も踏まえて構成している。

パターン1：Gitブランチ＋コンテキストプログレスバー（多行表示）

多行表示は、スクリプトが複数行を出力するだけで実現する。改行を含む出力をそのまま echo すれば、ステータスラインが2行以上になる。以下は1行目にモデル名・ディレクトリ・ブランチ、2行目にプログレスバーとコストを表示する構成だ。

#!/bin/bash
set -euo pipefail
INPUT=$(cat)
MODEL=$(echo "$INPUT" | jq -r '.model // "unknown"')
BRANCH=$(echo "$INPUT" | jq -r '.git.branch // "no-git"')
CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
USED=$(echo "$INPUT" | jq '.contextWindow.used // 0')
TOTAL=$(echo "$INPUT" | jq '.contextWindow.total // 1')
COST=$(echo "$INPUT" | jq '.session.cost // 0')

# 1行目：モデル名・ディレクトリ・ブランチ
echo "${MODEL} | ${CWD##*/} | branch: ${BRANCH}"

# 2行目：コンテキストプログレスバー＋コスト
PERCENT=$(echo "scale=0; $USED * 100 / $TOTAL" | bc)
BAR_FILL=$(echo "scale=0; $PERCENT / 5" | bc)
BAR_EMPTY=$((20 - BAR_FILL))
BAR="["
for i in $(seq 1 "$BAR_FILL"); do BAR="${BAR}#"; done
for i in $(seq 1 "$BAR_EMPTY"); do BAR="${BAR}-"; done
BAR="${BAR}]"
printf "%s %d%% | cost: \$%.4f\n" "$BAR" "$PERCENT" "$COST"

スクリプトの実行権限を付与してから settings.json に登録する。

chmod +x ~/.claude/scripts/my_statusline.sh

パターン2：コンテキスト使用率80%超過時の警告表示

コンテキスト使用率が閾値を超えたら警告を出す実装は、長時間の自律エージェント実行中に特に有効だ。/compact コマンドを打つ適切なタイミングを逃さないための実用的なパターンである（参考：レートリミット・コンテキスト使用率をリアルタイム表示する方法）。

#!/bin/bash
set -euo pipefail
INPUT=$(cat)
USED=$(echo "$INPUT" | jq '.contextWindow.used // 0')
TOTAL=$(echo "$INPUT" | jq '.contextWindow.total // 1')
PERCENT=$(echo "scale=0; $USED * 100 / $TOTAL" | bc)

if [ "$PERCENT" -ge 80 ]; then
  echo "[WARN] Context ${PERCENT}% -- consider /compact"
else
  echo "Context: ${PERCENT}%"
fi

パターン3：ccstatuslineを使った即席セットアップ

コミュニティが開発したツール ccstatusline を使えば、プリセットから選択してステータスラインを設定できる（参考：Classmethod – Claude Codeのステータスラインカスタマイズツール）。スクリプトをゼロから書かずに動作を確認したい場面に向いている。ただしサードパーティツールであるため、自動生成されたスクリプトの内容は必ず目視確認し、意図しないコマンドが混入していないかをチェックする習慣を持つべきだ。

実装時のトレードオフと注意点

statusline を実装・運用する際に把握すべき制約を整理する。

スクリプトの実行コスト：statusline スクリプトは UI 更新のたびに実行される。git status のような軽量コマンドは問題ないが、ネットワーク通信やディスク I/O の重い処理を入れるとインタラクションのレスポンスに影響する。重い処理が必要なら、バックグラウンドプロセスがキャッシュファイルに書き出し、スクリプトはそのファイルを読むだけにする設計が現実的だ。

エラーハンドリング：スクリプトが異常終了した場合、ステータスラインには何も表示されないか、エラー文字列がそのまま出る。jq の // default 構文で null 安全を担保し、スクリプト先頭に set -euo pipefail を置いてデバッグしやすくすることを勧める。動作確認は echo '{}' | ~/.claude/scripts/my_statusline.sh のように空 JSON を渡す形で単体テストできる。

セキュリティ：statusline スクリプトはシェルとして実行される。JSON フィールドを展開する際、想定外の文字列によるコマンドインジェクションに注意が必要だ。jq -r の出力をシングルクォートで囲む等の基本的なエスケープを徹底し、外部から受け取った文字列を eval するような実装は避けること。

プロジェクト設定との競合：ユーザー設定とプロジェクト設定の両方に statusLine を書いた場合、プロジェクト設定が優先される。チームで共有するプロジェクト設定にスクリプトパスを含める場合は、絶対パスではなくプロジェクト内にスクリプトを配置して参照する方が可搬性は高い。

Claude Code 全体の使い方や他のワークフローについては、Claude Codeの使い方ガイドおよびClaude Codeとはも参照されたい。他ツールとの比較に関心があれば、Claude CodeとCursorの比較やClaude CodeとCodexの比較も有用だ。

statuslineを実用にするための割り切り（一次情報）

監修者・河合継はClaude Codeを3.5の時代から1年以上、実務で運用してきた。ステータスラインは凝りだすときりがないが、実用にするコツは「見たいものだけ出す」ことだ。

• 常に気にしたい情報だけに絞る。あれもこれも表示すると、かえって肝心な情報が埋もれる。自分が実際に気にしているもの（今のモデルや作業中の文脈など）に絞ると、視界がすっきりして判断が速くなった。
• スクリプトは軽く保つ。表示のたびに走るため、重い処理を挟むと操作の体感が悪くなる。最小限の情報を素早く返すのを優先するのが、結局いちばん快適だった。
• 最初から凝らず、必要になったら足す。いきなり作り込むより、まずは最小構成で運用し、欲しくなった情報を後から足していくほうが、自分に合った形に落ち着いた。

statuslineカスタマイズの実装ステップ早見表とまとめ

設定方法・スクリプト実装・運用上の注意点を一つの流れとして整理する。以下のステップで完結する。

1. スクリプトを用意する：/statusline コマンドで自動生成するか、手動で ~/.claude/scripts/ 配下に .sh ファイルを作成する。chmod +x で実行権限を付与する。
2. settings.json に登録する：~/.claude/settings.json（ユーザー全体）またはプロジェクトルートの .claude/settings.json（プロジェクト固有）に statusLine.type: "command" と statusLine.command を記述する。
3. Claude Code を起動して確認する：ターミナル下部にスクリプトの出力が表示されることを確認する。表示されない場合は echo '{}' | ~/.claude/scripts/my_statusline.sh で単体動作を確認し、エラーを切り分ける。
4. 段階的に情報を追加する：最初はコンテキスト使用率だけの1行表示から始め、運用しながらコスト・Git ブランチ等を追加していく方が問題の切り分けがしやすい。

statusline は地味な機能に見えるが、長時間のエージェント実行やマルチセッション並列作業の状況では、開発サイクルの質に直結する情報インフラとして機能する。コンテキストウィンドウの残量を常時把握することで /compact のタイミングを逃さず、Git ブランチを常時表示することで誤ったブランチでのコード生成を防ぎ、セッションコストをリアルタイム確認することでコスト超過の発見遅れを減らせる。まず /statusline コマンドに自然言語でやりたいことを伝え、生成されたスクリプトを自分の用途に合わせて育てていくアプローチが最も早い。

SEO 開発における Claude Code の活用については Claude Code SEO入門 も参考になる。実装の詳細や料金設計の検討には Claude Codeの料金体系 と Claude Code APIの価格詳細 を参照されたい。

---

弊社が開発するDeepAIは、実在の人物の容姿・表情・声を再現するバーチャルヒューマン／AIアバター製品です。ソファーなど形状が不定な対象の正常・異常判定を得意としており、GANによるデータ拡張も活用しています。Claude CodeなどのAIツールを組み合わせた開発効率化にも社内で取り組んでいます。詳細はDeepAI製品ページをご覧ください。

よくある質問

Q. statuslineスクリプトはどのような仕組みで動作しますか？
A. Claude Codeがセッション情報をJSON形式で標準入力（stdin）に送り込み、スクリプト側がそれを受け取って整形・出力するパイプライン構造です。スクリプトが出力する内容がそのままターミナル下部に表示されます。

Q. /statuslineコマンドで自動生成する方法と手動設定の違いは何ですか？
A. /statuslineコマンドは自然言語で指示するとClaude Codeが~/.claude/配下にスクリプトを自動生成し、settings.jsonのstatusLineフィールドを自動更新します。手動設定は~/.claude/settings.jsonまたはプロジェクト設定に直接statusLineフィールド（type: “command”, command: パス）を記述します。

Q. ユーザー設定とプロジェクト設定でstatusLineが両方定義されている場合、どちらが優先されますか？
A. プロジェクト設定が優先されます。チーム開発でプロジェクト設定をリポジトリに含める際は、スクリプトのパスがメンバー全員の環境で有効かどうかを事前に確認する必要があります。

Q. statuslineスクリプトで参照できる主なJSONフィールドにはどのようなものがありますか？
A. model（使用中のモデル名）、contextWindow.used／total（コンテキスト使用量・上限）、session.cost／duration（セッションコスト・経過時間）、git.branch／status（Gitブランチ・状態）、cwd（カレントディレクトリ）などがあります。

Q. gitのブランチ名やステージング状況はstdinのJSONに含まれますか？
A. 含まれません。stdinで渡されるのはworkspace.repo.host/owner/name（originリモートの識別情報）までで、現在のブランチ名や変更ファイル数を表示するには、スクリプト内でgit branch –show-currentやgit diff –numstatなどのgitコマンドを別途実行して取得する必要があります。

Q. Windows環境ではstatuslineコマンドはどのように実行されますか？
A. Claude CodeはstatuslineコマンドをGit Bash経由で実行し、Git Bashが無い場合はPowerShellにフォールバックします。PowerShellスクリプトを使う場合はsettings.jsonからpowershell経由で呼び出します。

Q. statuslineスクリプトを実装する上での実行コストの注意点は何ですか？
A. statuslineスクリプトはUI更新のたびに実行されるため、ネットワーク通信やディスクI/Oの重い処理を入れるとインタラクションのレスポンスに影響します。重い処理が必要な場合は、バックグラウンドプロセスがキャッシュファイルに書き出し、スクリプトはそのファイルを読むだけにする設計が現実的です。

Q. statuslineスクリプトのセキュリティ上の注意点は何ですか？
A. statuslineスクリプトはシェルとして実行されるため、JSONフィールドを展開する際に想定外の文字列によるコマンドインジェクションに注意が必要です。jq -rの出力をシングルクォートで囲む等の基本的なエスケープを徹底し、外部から受け取った文字列をevalするような実装は避けるべきです。

---

参考文献

• Claude Code Docs – ステータスラインをカスタマイズする（Anthropic公式）
  https://code.claude.com/docs/ja/statusline
• Claude Code Docs – Common workflows（Anthropic公式）
  https://code.claude.com/docs/en/common-workflows.md
• Claude Code Docs – Agent SDK overview（Anthropic公式）
  

  監修

  河合 継（クリスタルメソッド株式会社 代表取締役）

  AI・ディープラーニングに関する特許16件の発明者。過去、国立がん研究センターとの共同研究や、テレビ番組でのAI解説実績を持つAI研究者として、AIの研究開発を主導している。
  運営会社について ｜ 編集方針