- 作業中にコンテキストウィンドウの使用状況を監視したい
- セッションコストを追跡する必要がある
- 複数のセッション間で作業し、それらを区別する必要がある
- git ブランチとステータスを常に表示したい

ステータスラインを設定する
/statusline コマンド を使用して Claude Code にスクリプトを生成させるか、手動でスクリプトを作成 して設定に追加します。
/statusline コマンドを使用する
/statusline コマンドは、表示したい内容を説明する自然言語の指示を受け入れます。Claude Code は ~/.claude/ にスクリプトファイルを生成し、設定を自動的に更新します:
ステータスラインを手動で設定する
ユーザー設定(~/.claude/settings.json、~ はホームディレクトリ)または プロジェクト設定 に statusLine フィールドを追加します。type を "command" に設定し、command をスクリプトパスまたはインラインシェルコマンドに指定します。スクリプト作成の完全なチュートリアルについては、ステータスラインをステップバイステップで構築する を参照してください。
command フィールドはシェルで実行されるため、スクリプトファイルの代わりにインラインコマンドを使用することもできます。この例では jq を使用して JSON 入力を解析し、モデル名とコンテキスト割合を表示します:
padding フィールドは、ステータスラインコンテンツに追加の水平スペース(文字単位)を追加します。デフォルトは 0 です。このパディングはインターフェイスの組み込みスペースに加えて追加されるため、ターミナルエッジからの絶対距離ではなく相対的なインデントを制御します。
オプションの refreshInterval フィールドは、イベント駆動更新 に加えて、N 秒ごとにコマンドを再実行します。最小値は 1 です。ステータスラインが時計などの時間ベースのデータを表示する場合、またはメインセッションがアイドル状態の間にバックグラウンドサブエージェントが git 状態を変更する場合に設定します。イベントのみで実行する場合は設定しないままにします。
ステータスラインを無効にする
/statusline を実行し、ステータスラインを削除またはクリアするよう指示します(例:/statusline delete、/statusline clear、/statusline remove it)。settings.json から statusLine フィールドを手動で削除することもできます。
ステータスラインをステップバイステップで構築する
このチュートリアルでは、現在のモデル、作業ディレクトリ、コンテキストウィンドウ使用状況の割合を表示するステータスラインを手動で作成することで、内部で何が起こっているかを示します。/statusline を実行して、表示したい内容を説明すると、これらすべてが自動的に設定されます。
JSON を読み取り、出力を出力するスクリプトを作成する
Claude Code は stdin 経由でスクリプトに JSON データを送信します。このスクリプトは
jq(コマンドラインの JSON パーサーで、インストールが必要な場合があります)を使用して、モデル名、ディレクトリ、コンテキスト割合を抽出し、フォーマットされた行を出力します。これを ~/.claude/statusline.sh に保存します(~ はホームディレクトリ、macOS では /Users/username、Linux では /home/username など):ステータスラインの仕組み
Claude Code はスクリプトを実行し、stdin 経由で JSON セッションデータ をパイプします。スクリプトは JSON を読み取り、必要なものを抽出し、stdout にテキストを出力します。Claude Code はスクリプトが出力したものを表示します。 更新のタイミング スクリプトは新しいアシスタントメッセージの後、パーミッションモードが変更されたとき、または vim モードが切り替わったときに実行されます。更新は 300ms でデバウンスされます。つまり、急速な変更がバッチ処理され、スクリプトは物事が落ち着いたら一度実行されます。スクリプトがまだ実行中に新しい更新がトリガーされた場合、実行中の実行はキャンセルされます。スクリプトを編集した場合、Claude Code との次の相互作用がトリガーされるまで変更は表示されません。 これらのトリガーは、メインセッションがアイドル状態の場合(例えば、コーディネーターがバックグラウンドサブエージェントを待機している場合)、静かになる可能性があります。アイドル期間中に時間ベースまたは外部ソースのセグメントを最新に保つには、refreshInterval を設定して、固定タイマーでもコマンドを再実行します。
スクリプトが出力できるもの
- 複数行:各
echoまたはprintステートメントは別の行として表示されます。複数行の例 を参照してください。 - 色:
\033[32mのような ANSI エスケープコード を使用して緑色を表示します(ターミナルがサポートしている必要があります)。git ステータスの例 を参照してください。 - リンク:OSC 8 エスケープシーケンス を使用してテキストをクリック可能にします(macOS では Cmd+クリック、Windows/Linux では Ctrl+クリック)。iTerm2、Kitty、WezTerm などのハイパーリンクをサポートするターミナルが必要です。クリック可能なリンクの例 を参照してください。
ステータスラインはローカルで実行され、API トークンを消費しません。オートコンプリート提案、ヘルプメニュー、パーミッションプロンプトなど、特定の UI 相互作用中は一時的に非表示になります。
利用可能なデータ
Claude Code は以下の JSON フィールドを stdin 経由でスクリプトに送信します:| フィールド | 説明 |
|---|---|
model.id、model.display_name | 現在のモデル識別子と表示名 |
cwd、workspace.current_dir | 現在の作業ディレクトリ。両方のフィールドに同じ値が含まれます。workspace.current_dir は workspace.project_dir との一貫性のために推奨されます。 |
workspace.project_dir | Claude Code が起動されたディレクトリ。セッション中に作業ディレクトリが変更された場合、cwd と異なる場合があります |
workspace.added_dirs | /add-dir または --add-dir 経由で追加された追加ディレクトリ。追加されていない場合は空配列 |
workspace.git_worktree | 現在のディレクトリが git worktree add で作成されたリンク worktree 内にある場合の git worktree 名。メイン作業ツリーでは不在。worktree.* が --worktree セッションのみに適用されるのとは異なり、任意の git worktree に対して入力されます |
cost.total_cost_usd | USD でのセッションの推定コスト。クライアント側で計算されます。実際の請求額と異なる場合があります |
cost.total_duration_ms | セッション開始からの総経過時間(ミリ秒) |
cost.total_api_duration_ms | API レスポンスを待つのに費やされた総時間(ミリ秒) |
cost.total_lines_added、cost.total_lines_removed | 変更されたコード行 |
context_window.total_input_tokens、context_window.total_output_tokens | セッション全体の累積トークン数 |
context_window.context_window_size | トークン単位の最大コンテキストウィンドウサイズ。デフォルトは 200000、拡張コンテキストを持つモデルの場合は 1000000 |
context_window.used_percentage | 事前計算されたコンテキストウィンドウ使用割合 |
context_window.remaining_percentage | 事前計算されたコンテキストウィンドウ残り割合 |
context_window.current_usage | 最後の API 呼び出しからのトークン数。コンテキストウィンドウフィールド で説明されています |
exceeds_200k_tokens | 最新の API レスポンスからの総トークン数(入力、キャッシュ、出力トークンの組み合わせ)が 200k を超えるかどうか。これは実際のコンテキストウィンドウサイズに関係なく固定閾値です。 |
rate_limits.five_hour.used_percentage、rate_limits.seven_day.used_percentage | 5 時間または 7 日のレート制限の消費割合(0~100) |
rate_limits.five_hour.resets_at、rate_limits.seven_day.resets_at | 5 時間または 7 日のレート制限ウィンドウがリセットされる Unix エポック秒 |
session_id | 一意のセッション識別子 |
session_name | --name フラグまたは /rename で設定されたカスタムセッション名。カスタム名が設定されていない場合は不在 |
transcript_path | 会話トランスクリプトファイルへのパス |
version | Claude Code バージョン |
output_style.name | 現在の出力スタイルの名前 |
vim.mode | vim モード が有効な場合の現在の vim モード(NORMAL または INSERT) |
agent.name | --agent フラグまたはエージェント設定が設定されている場合のエージェント名 |
worktree.name | アクティブな worktree の名前。--worktree セッション中のみ存在 |
worktree.path | worktree ディレクトリへの絶対パス |
worktree.branch | worktree の git ブランチ名(例:"worktree-my-feature")。フックベースの worktree では不在 |
worktree.original_cwd | worktree に入る前に Claude がいたディレクトリ |
worktree.original_branch | worktree に入る前にチェックアウトされた git ブランチ。フックベースの worktree では不在 |
完全な JSON スキーマ
完全な JSON スキーマ
ステータスラインコマンドは stdin 経由でこの JSON 構造を受け取ります:不在の可能性があるフィールド(JSON に存在しない):
session_name:--nameまたは/renameでカスタム名が設定されている場合のみ表示workspace.git_worktree:現在のディレクトリがリンク git worktree 内にある場合のみ表示vim:vim モードが有効な場合のみ表示agent:--agentフラグまたはエージェント設定が設定されている場合のみ表示worktree:--worktreeセッション中のみ表示。存在する場合、branchとoriginal_branchもフックベースの worktree では不在の可能性がありますrate_limits:Claude.ai サブスクライバー(Pro/Max)がセッションの最初の API レスポンスの後のみ表示。各ウィンドウ(five_hour、seven_day)は独立して不在の可能性があります。jq -r '.rate_limits.five_hour.used_percentage // empty'を使用して、不在を適切に処理します。
null の可能性があるフィールド:context_window.current_usage:セッションの最初の API 呼び出しの前はnullcontext_window.used_percentage、context_window.remaining_percentage:セッションの早期段階ではnullの可能性があります
コンテキストウィンドウフィールド
context_window オブジェクトは、コンテキスト使用状況を追跡する 2 つの方法を提供します:
- 累積合計(
total_input_tokens、total_output_tokens):セッション全体のすべてのトークンの合計。総消費量の追跡に便利です - 現在の使用状況(
current_usage):最新の API 呼び出しからのトークン数。実際のコンテキスト状態を反映しているため、正確なコンテキスト割合に使用します
current_usage オブジェクトには以下が含まれます:
input_tokens:現在のコンテキストの入力トークンoutput_tokens:生成された出力トークンcache_creation_input_tokens:キャッシュに書き込まれたトークンcache_read_input_tokens:キャッシュから読み取られたトークン
used_percentage フィールドは入力トークンのみから計算されます:input_tokens + cache_creation_input_tokens + cache_read_input_tokens。output_tokens は含まれません。
current_usage から手動でコンテキスト割合を計算する場合、used_percentage と一致させるために同じ入力のみの式を使用します。
current_usage オブジェクトはセッションの最初の API 呼び出しの前は null です。
例
これらの例は一般的なステータスラインパターンを示しています。任意の例を使用するには:- スクリプトを
~/.claude/statusline.sh(または.py/.js)などのファイルに保存します - 実行可能にします:
chmod +x ~/.claude/statusline.sh - 設定 にパスを追加します
jq を使用して JSON を解析します。Python と Node.js には組み込みの JSON 解析があります。
コンテキストウィンドウの使用状況
現在のモデルとコンテキストウィンドウの使用状況を視覚的なプログレスバーで表示します。各スクリプトは stdin から JSON を読み取り、used_percentage フィールドを抽出し、塗りつぶされたブロック(▓)が使用状況を表す 10 文字のバーを構築します:

git ステータスと色
ステージングされたファイルと変更されたファイルのカラーコード化されたインジケーターを使用して git ブランチを表示します。このスクリプトはターミナルの色に ANSI エスケープコード を使用します:\033[32m は緑、\033[33m は黄、\033[0m はデフォルトにリセットします。

コストと期間の追跡
セッションの API コストと経過時間を追跡します。cost.total_cost_usd フィールドは現在のセッションのすべての API 呼び出しの推定コストを累積します。cost.total_duration_ms フィールドはセッション開始からの総経過時間を測定し、cost.total_api_duration_ms は API レスポンスを待つのに費やされた時間のみを追跡します。
各スクリプトはコストを通貨としてフォーマットし、ミリ秒を分と秒に変換します:

複数行を表示する
スクリプトは複数の行を出力して、より豊かなディスプレイを作成できます。各echo ステートメントはステータス領域に別の行を生成します。

print または echo ステートメントは別の行を作成します:
クリック可能なリンク
この例は GitHub リポジトリへのクリック可能なリンクを作成します。git リモート URL を読み取り、SSH 形式をsed で HTTPS に変換し、リポジトリ名を OSC 8 エスケープコードでラップします。Cmd(macOS)または Ctrl(Windows/Linux)を押しながらクリックして、ブラウザでリンクを開きます。

printf '%b' を使用します。これはバックスラッシュエスケープを異なるシェル間でより確実に解釈します:
レート制限の使用状況
Claude.ai サブスクリプションのレート制限使用状況をステータスラインに表示します。rate_limits オブジェクトには five_hour(5 時間のローリングウィンドウ)と seven_day(週間)ウィンドウが含まれます。各ウィンドウは used_percentage(0~100)とウィンドウがリセットされる Unix エポック秒の resets_at を提供します。
このフィールドは Claude.ai サブスクライバー(Pro/Max)がセッションの最初の API レスポンスの後のみ存在します。各スクリプトは不在のフィールドを適切に処理します:
高コストな操作をキャッシュする
ステータスラインスクリプトはアクティブなセッション中に頻繁に実行されます。git status や git diff などのコマンドは、特に大規模なリポジトリでは遅い場合があります。この例は git 情報を一時ファイルにキャッシュし、5 秒ごとにのみ更新します。
キャッシュファイル名は、セッション内のステータスラインの呼び出し間で安定している必要がありますが、異なるリポジトリの同時セッションが互いのキャッシュされた git 状態を読み取らないように、セッション間で一意である必要があります。$$、os.getpid()、process.pid のようなプロセスベースの識別子は、呼び出しのたびに変わり、キャッシュを無効にします。代わりに JSON 入力から session_id を使用します:これはセッションの有効期間中は安定しており、セッションごとに一意です。
各スクリプトは git コマンドを実行する前に、キャッシュファイルが不在であるか 5 秒より古いかを確認します:
Windows 設定
Windows では、Claude Code はステータスラインコマンドを Git Bash 経由で実行します。そのシェルから PowerShell を呼び出すことができます:サブエージェントステータスライン
subagentStatusLine 設定は、エージェントパネルに表示される各 サブエージェント のカスタム行本体をレンダリングします。デフォルトの name · description · token count 行を独自のフォーマットに置き換えるために使用します。
columns(使用可能な行幅)と tasks 配列が含まれます。各タスクには id、name、type、status、description、label、startTime、tokenCount、tokenSamples、cwd があります。
オーバーライドしたい各行に対して stdout に 1 つの JSON 行を書き込みます。形式は {"id": "<task id>", "content": "<row body>"} です。content 文字列はそのままレンダリングされます。ANSI 色と OSC 8 ハイパーリンクを含みます。タスクの id を省略して、その行のデフォルトレンダリングを保持します。空の content 文字列を出力して、その行を非表示にします。
statusLine に適用される同じトラストと disableAllHooks ゲートが subagentStatusLine に適用されます。プラグインは、settings.json でデフォルトの subagentStatusLine を配布できます。
ヒント
- モック入力でテストする:
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}' | ./statusline.sh - 出力を短く保つ:ステータスバーの幅は限られているため、長い出力は切り詰められたり、不適切にラップされたりする可能性があります
- 遅い操作をキャッシュする:スクリプトはアクティブなセッション中に頻繁に実行されるため、
git statusなどのコマンドは遅延を引き起こす可能性があります。これを処理する方法については、キャッシング例 を参照してください。
トラブルシューティング
ステータスラインが表示されない- スクリプトが実行可能であることを確認します:
chmod +x ~/.claude/statusline.sh - スクリプトが stdout に出力し、stderr に出力していないことを確認します
- スクリプトを手動で実行して、出力を生成することを確認します
disableAllHooksが設定でtrueに設定されている場合、ステータスラインも無効になります。この設定を削除するか、falseに設定して再度有効にします。claude --debugを実行して、セッションの最初のステータスラインの呼び出しからの終了コードと stderr をログに記録します- Claude にスクリプトファイルを読み取り、
statusLineコマンドを直接実行するよう依頼して、エラーを表示します
-- または空の値を表示する
- フィールドは最初の API レスポンスが完了する前は
nullの可能性があります - スクリプトで
// 0のようなフォールバックを使用して null 値を処理します - 複数のメッセージの後も値が空のままの場合は、Claude Code を再起動します
- 累積合計ではなく、正確なコンテキスト状態に
used_percentageを使用します total_input_tokensとtotal_output_tokensはセッション全体で累積され、コンテキストウィンドウサイズを超える可能性があります- コンテキスト割合は
/context出力と異なる場合があります。これは各が計算されるタイミングが異なるためです
- ターミナルが OSC 8 ハイパーリンクをサポートしていることを確認します(iTerm2、Kitty、WezTerm)
- Terminal.app はクリック可能なリンクをサポートしていません
- SSH と tmux セッションは設定に応じて OSC シーケンスをストリップする可能性があります
- エスケープシーケンスが
\e]8;;のようなリテラルテキストとして表示される場合は、echo -eの代わりにprintf '%b'を使用して、より確実なエスケープ処理を行います
- 複雑なエスケープシーケンス(ANSI 色、OSC 8 リンク)は、他の UI 更新と重複する場合、時々破損した出力を引き起こす可能性があります
- 破損したテキストが表示される場合は、スクリプトをプレーンテキスト出力に簡略化してみてください
- エスケープコード付きの複数行ステータスラインは、プレーンテキストの単一行よりもレンダリングの問題が発生しやすくなります
- ステータスラインコマンドは、現在のディレクトリのワークスペーストラストダイアログを受け入れた場合のみ実行されます。
statusLineはシェルコマンドを実行するため、フックおよび他のシェル実行設定と同じトラストの受け入れが必要です。 - トラストが受け入れられていない場合、ステータスラインの出力の代わりに
statusline skipped · restart to fixという通知が表示されます。Claude Code を再起動し、トラストプロンプトを受け入れて有効にします。
- ゼロ以外のコードで終了するか、出力を生成しないスクリプトは、ステータスラインを空白にします
- 遅いスクリプトは、完了するまでステータスラインの更新をブロックします。古い出力を避けるために、スクリプトを高速に保ちます。
- 遅いスクリプトの実行中に新しい更新がトリガーされた場合、実行中のスクリプトはキャンセルされます
- 設定する前に、モック入力を使用してスクリプトを独立してテストします
- MCP サーバーエラー、自動更新などのシステム通知は、ステータスラインと同じ行の右側に表示されます
- 詳細モードを有効にすると、この領域にトークンカウンターが追加されます
- 狭いターミナルでは、これらの通知がステータスラインの出力を切り詰める可能性があります