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の価格詳細も参考になる。

実用的な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カスタマイズの実装ステップ早見表とまとめ

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

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は、機械学習・深層学習（CNN）を用いた2D画像認識・異常検知ソリューションです。ソファーなど形状が不定な対象の正常・異常判定を得意としており、GANによるデータ拡張も活用しています。Claude CodeなどのAIツールを組み合わせた開発効率化にも社内で取り組んでいます。詳細はDeepAI製品ページをご覧ください。

参考文献

• 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公式）
  {“@context”:”https://schema.org”,”@type”:”BlogPosting”,”headline”:”Claude Code statuslineステータスラインのカスタマイズと使い方を徹底解説”,”description”:”Claude Code statuslineのカスタマイズ方法を公式ドキュメントに基づき徹底解説。/statuslineコマンドによる自動生成、settings.jsonの手動設定、JSONフィールドの活用、実用スクリプト例、多行表示、セキュリティ注意点まで網羅。”,”datePublished”:”2026-06-07T09:36:21″,”dateModified”:”2026-06-07T09:36:21″,”author”:{“@type”:”Person”,”name”:”河合 継”,”jobTitle”:”代表取締役”,”worksFor”:{“@type”:”Organization”,”name”:”クリスタルメソッド株式会社”}},”publisher”:{“@type”:”Organization”,”name”:”クリスタルメソッド株式会社”,”url”:”https://crystal-method.com/”},”mainEntityOfPage”:{“@type”:”WebPage”,”@id”:”https://crystal-method.com/blog/claude-code-statusline/”}}
  
  このフィールドは空白のままにしてください

  AIブログ購読

  　
  クリスタルメソッドがお届けする
  AIブログの更新通知を受け取る

  受信ボックスか迷惑メールフォルダを確認して購読手続きを完了してください。