Claude Code ステータスラインの設定方法

問題: Claude Code のターミナルには、画面に表示されない有用な情報が多くある。カスタムステータスラインを使えば、モデル名、Gitブランチ、実行中のセッションコスト、コンテキストの使用状況をチャット画面の直下に表示できる。

これは Claude Code における PS1 のようなものだ。Oh-my-zsh や Starship でシェルプロンプトをカスタマイズしたことがあれば、考え方はまったく同じだ。作業中に現状を把握し続けるための、1行のライブ情報表示だ。

ステータスラインに表示できる情報

ステータスラインは Claude Code インターフェースの下部に表示され、会話が変わるたびに更新される。スクリプトが出力したものがそのまま表示される。現在のモデル、アクティブなGitブランチ、セッションのコスト累計、コンテキストウィンドウの使用率などだ。

実際に設定した例を示す:

[Opus] my-project | main | $0.42 | Context: 37%

1行だ。モデル、プロジェクトフォルダ、Gitブランチ、セッションコストの累計、コンテキストウィンドウの使用率がすべて表示される。各フィールドは自動的に更新される。

/statusline を使った素早いセットアップ

CLI には /statusline コマンドが組み込まれている。Claude Code 内で入力するだけでスクリプトが生成される。

/statusline

デフォルトの動作では、ターミナルプロンプトを反映したステータスラインスクリプトが生成される。特定のリクエストを渡すこともできる:

/statusline show the model name in orange

/statusline display git branch and session cost

/statusline show context window percentage with color coding

以上だ。Claude Code がスクリプトを書き、設定を自動で組み込み、ステータスラインが表示される。細かく制御したい場合は、次の手動設定の方法を参照してほしい。

settings.json による手動設定

手動で設定するには、プロジェクトの .claude/settings.json（すべてのプロジェクトで使いたい場合はグローバルの ~/.claude/settings.json）に statusLine エントリを追加する:

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

知っておくべき3つのフィールド:

type: スクリプトベースのステータスラインには常に "command" を指定する
command: ステータスライン出力を生成するスクリプトへのパス
padding: ステータスライン上の空行数（通常は0）

このエントリを追加したら、スクリプトファイルを作成して実行権限を付与する:

touch ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.sh

chmod +x の手順は重要だ。ステータスラインが表示されない場合、実行権限の欠如がほぼ原因だ。

ステータスラインエンジンの仕組み

スクリプトのデバッグやカスタマイズを行う際、仕組みを理解しておくと役立つ:

更新トリガー: 会話のメッセージが変わるたびにステータスラインが更新される
スロットル: パフォーマンス問題を避けるため、最大300msに1回の更新
出力の扱い: スクリプトのstdoutの最初の行だけがステータスラインのテキストになる
カラー: スタイリング用にANSIカラーコードを完全サポート
入力: Claude Code はセッションデータを含むJSONオブジェクトをstdinからスクリプトにパイプする

最後の点が鍵だ。スクリプトはstdinに現在のモデル、ワークスペースのパス、セッションコスト、コンテキストウィンドウの統計などを含む構造化されたJSONペイロードを受け取る。それを解析してフォーマットし、stdoutに1行出力するだけだ。

スクリプトが受け取るJSONの入力

ステータスラインが更新されるたびに、スクリプトはstdinでこのJSON構造を受け取る:

{
  "hook_event_name": "Status",
  "session_id": "abc123...",
  "cwd": "/current/working/directory",
  "model": {
    "id": "claude-opus-4-1",
    "display_name": "Opus"
  },
  "workspace": {
    "current_dir": "/current/working/directory",
    "project_dir": "/original/project/directory"
  },
  "version": "1.0.80",
  "cost": {
    "total_cost_usd": 0.01234,
    "total_duration_ms": 45000,
    "total_api_duration_ms": 2300,
    "total_lines_added": 156,
    "total_lines_removed": 23
  },
  "context_window": {
    "total_input_tokens": 15234,
    "total_output_tokens": 4521,
    "context_window_size": 200000,
    "used_percentage": 42.5,
    "remaining_percentage": 57.5,
    "current_usage": {
      "input_tokens": 8500,
      "output_tokens": 1200,
      "cache_creation_input_tokens": 5000,
      "cache_read_input_tokens": 2000
    }
  }
}

実用的なステータスラインで実際に使うフィールド:

model.display_name: "Opus" や "Sonnet" などの短いモデル名
workspace.current_dir: 現在の作業ディレクトリ
cost.total_cost_usd: セッションの累計コスト（ドル）
cost.total_lines_added / total_lines_removed: コード変更量の追跡
context_window.used_percentage: 事前計算済みのコンテキスト使用率（0〜100）
context_window.context_window_size: コンテキストウィンドウの総容量

コピーして使えるステータスラインスクリプト

以下は複数の言語での完全な実行可能スクリプトだ。環境に合ったものを使ってほしい。

シンプルなBashステータスライン

最小限の実用的なステータスライン。モデル名と現在のディレクトリを表示する:

#!/bin/bash
input=$(cat)
 
MODEL=$(echo "$input" | jq -r '.model.display_name')
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
 
echo "[$MODEL] ${CURRENT_DIR##*/}"

出力例: [Opus] my-project

このスクリプトはJSONの解析に jq を使用している。jq がインストールされていない場合は、macOSなら brew install jq、Ubuntuなら sudo apt install jq を実行してほしい。

Gitに対応したBashステータスライン

ブランチ情報が追加される。複数のフィーチャーブランチを切り替えながら作業するときに便利だ:

#!/bin/bash
input=$(cat)
 
MODEL=$(echo "$input" | jq -r '.model.display_name')
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
 
GIT_BRANCH=""
if git rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    if [ -n "$BRANCH" ]; then
        GIT_BRANCH=" | $BRANCH"
    fi
fi
 
echo "[$MODEL] ${CURRENT_DIR##*/}$GIT_BRANCH"

出力例: [Opus] my-project | feature/auth

フル機能のBashステータスライン

モデル、Gitブランチ、セッションコスト、コンテキスト使用率をすべて1行に表示する:

#!/bin/bash
input=$(cat)
 
MODEL=$(echo "$input" | jq -r '.model.display_name')
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
PERCENT_USED=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
 
# Git branch
GIT_BRANCH=""
if git rev-parse --git-dir > /dev/null 2>&1; then
    BRANCH=$(git branch --show-current 2>/dev/null)
    if [ -n "$BRANCH" ]; then
        GIT_BRANCH=" | $BRANCH"
    fi
fi
 
# Format cost to 2 decimal places
COST_FMT=$(printf '%.2f' "$COST")
 
# Round context percentage
PERCENT_INT=$(printf '%.0f' "$PERCENT_USED")
 
echo "[$MODEL] ${CURRENT_DIR##*/}$GIT_BRANCH | \$${COST_FMT} | Ctx: ${PERCENT_INT}%"

出力例: [Opus] my-project | main | $0.42 | Ctx: 37%

ANSIカラー付きBashステータスライン

カラーコーディングにより、一目で状態が把握できる:

#!/bin/bash
input=$(cat)
 
MODEL=$(echo "$input" | jq -r '.model.display_name')
CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
PERCENT_USED=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
 
# ANSI colors
ORANGE='\033[38;5;208m'
GREEN='\033[32m'
YELLOW='\033[33m'
RED='\033[31m'
CYAN='\033[36m'
RESET='\033[0m'
 
# Color context percentage based on usage
PERCENT_INT=$(printf '%.0f' "$PERCENT_USED")
if [ "$PERCENT_INT" -lt 50 ]; then
    CTX_COLOR=$GREEN
elif [ "$PERCENT_INT" -lt 80 ]; then
    CTX_COLOR=$YELLOW
else
    CTX_COLOR=$RED
fi
 
COST_FMT=$(printf '%.2f' "$COST")
 
echo -e "${ORANGE}[$MODEL]${RESET} ${CURRENT_DIR##*/} ${CYAN}\$${COST_FMT}${RESET} ${CTX_COLOR}Ctx:${PERCENT_INT}%${RESET}"

コンテキスト使用率が50%未満は緑、50〜80%は黄色、80%超は赤で表示される。コンテキストウィンドウの管理が必要なタイミングを視覚的に知らせてくれる。

複雑なスクリプト向けヘルパー関数アプローチ

ステータスラインスクリプトが大きくなってきたら、ヘルパー関数を使うと可読性が上がる:

#!/bin/bash
input=$(cat)
 
# Helper functions for clean extraction
get_model()     { echo "$input" | jq -r '.model.display_name'; }
get_dir()       { echo "$input" | jq -r '.workspace.current_dir'; }
get_cost()      { echo "$input" | jq -r '.cost.total_cost_usd // 0'; }
get_context()   { echo "$input" | jq -r '.context_window.used_percentage // 0'; }
get_added()     { echo "$input" | jq -r '.cost.total_lines_added // 0'; }
get_removed()   { echo "$input" | jq -r '.cost.total_lines_removed // 0'; }
get_version()   { echo "$input" | jq -r '.version'; }
 
MODEL=$(get_model)
DIR=$(get_dir)
COST=$(printf '%.2f' "$(get_cost)")
CTX=$(printf '%.0f' "$(get_context)")
ADDED=$(get_added)
REMOVED=$(get_removed)
 
echo "[$MODEL] ${DIR##*/} | \$$COST | Ctx:${CTX}% | +$ADDED/-$REMOVED"

出力例: [Opus] my-project | $0.42 | Ctx:37% | +156/-23

末尾の +156/-23 はセッション中に追加・削除された行数を追跡する。実際にどれだけコードが変わったかをすぐに確認できる。

PythonステータスライN

Bashよりもっと好みという方向け:

#!/usr/bin/env python3
import json
import sys
import os
import subprocess
 
data = json.load(sys.stdin)
 
model = data["model"]["display_name"]
current_dir = os.path.basename(data["workspace"]["current_dir"])
cost = data.get("cost", {}).get("total_cost_usd", 0)
ctx_pct = data.get("context_window", {}).get("used_percentage", 0)
 
# Get git branch
git_branch = ""
try:
    result = subprocess.run(
        ["git", "branch", "--show-current"],
        capture_output=True, text=True, timeout=2
    )
    if result.returncode == 0 and result.stdout.strip():
        git_branch = f" | {result.stdout.strip()}"
except Exception:
    pass
 
print(f"[{model}] {current_dir}{git_branch} | ${cost:.2f} | Ctx:{ctx_pct:.0f}%")

Node.jsステータスライン

JavaScriptを使う開発者向け:

#!/usr/bin/env node
const fs = require("fs");
const path = require("path");
const { execSync } = require("child_process");
 
let input = "";
process.stdin.on("data", (chunk) => (input += chunk));
process.stdin.on("end", () => {
  const data = JSON.parse(input);
 
  const model = data.model.display_name;
  const currentDir = path.basename(data.workspace.current_dir);
  const cost = (data.cost?.total_cost_usd || 0).toFixed(2);
  const ctxPct = Math.round(data.context_window?.used_percentage || 0);
 
  // Get git branch
  let gitBranch = "";
  try {
    const branch = execSync("git branch --show-current", {
      encoding: "utf8",
      timeout: 2000,
    }).trim();
    if (branch) gitBranch = ` | ${branch}`;
  } catch (e) {}
 
  console.log(
    `[${model}] ${currentDir}${gitBranch} | $${cost} | Ctx:${ctxPct}%`,
  );
});

コンテキストウィンドウの使用率を追跡する

コンテキストウィンドウを把握することは、ステータスラインを使う最も実用的な理由のひとつだ。ウィンドウが満杯になると、Claude Code は会話を圧縮し、詳細が失われる。現在の状況を把握することで、自分のタイミングで新しいセッションを始めたり圧縮を行う判断ができる。

事前計算済みの使用率を使うシンプルなアプローチ:

#!/bin/bash
input=$(cat)
 
MODEL=$(echo "$input" | jq -r '.model.display_name')
PERCENT_USED=$(echo "$input" | jq -r '.context_window.used_percentage // 0')
 
echo "[$MODEL] Context: ${PERCENT_USED}%"

生のトークン数から手動計算する高度なアプローチ:

#!/bin/bash
input=$(cat)
 
MODEL=$(echo "$input" | jq -r '.model.display_name')
CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size')
USAGE=$(echo "$input" | jq '.context_window.current_usage')
 
if [ "$USAGE" != "null" ]; then
    CURRENT_TOKENS=$(echo "$USAGE" | jq '.input_tokens + .cache_creation_input_tokens + .cache_read_input_tokens')
    PERCENT_USED=$((CURRENT_TOKENS * 100 / CONTEXT_SIZE))
    echo "[$MODEL] Context: ${PERCENT_USED}% (${CURRENT_TOKENS}/${CONTEXT_SIZE} tokens)"
else
    echo "[$MODEL] Context: 0%"
fi

高度なバージョンは使用率に加えて生のトークン数も表示する。残りのトークン予算を正確に知りたいとき、特に異なるコンテキストサイズのモデルを選択する際に役立つ。

セッションコストを追跡する

cost.total_cost_usd はリアルタイムで更新される。ステータスラインに表示することで、ダッシュボードを確認しなくても支出状況が常に見える:

#!/bin/bash
input=$(cat)
 
MODEL=$(echo "$input" | jq -r '.model.display_name')
COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
COST_FMT=$(printf '%.2f' "$COST")
 
echo "[$MODEL] Session: \$${COST_FMT}"

予算を管理したい方や機能ごとのコストを追跡したい方には、この可視性がすぐに役立つ。モデル選択戦略と組み合わせることで、タスクの難易度が Opus レベルを下回った時点で素早くモデルを切り替えられる。

トラブルシューティング

ステータスラインがまったく表示されない

スクリプトファイルの実行権限がないことがほぼ原因だ。次のコマンドで修正する:

chmod +x ~/.claude/statusline.sh

スクリプトは動いているが出力が空

スクリプトが stdout ではなく stderr に書き込んでいる可能性がある。ステータスラインに届くのは stdout の最初の行だけだ。まず echo "test" を追加して出力を確認し、そこから改善していくとよい。

スクリプトを手動でテスト

Claude Code を起動せずにモックJSONをスクリプトに直接パイプしてテストできる:

echo '{"model":{"display_name":"Test"},"workspace":{"current_dir":"/test"},"cost":{"total_cost_usd":0.5},"context_window":{"used_percentage":25}}' | ~/.claude/statusline.sh

期待する行が出力されれば、スクリプトは問題なし。何も出力されない場合は、解析処理に問題がある。

jq が見つからない

パッケージマネージャーからインストールする:

# macOS
brew install jq
 
# Ubuntu/Debian
sudo apt install jq
 
# Windows (via scoop)
scoop install jq

ステータスラインのアイデア集

基本的な動作ができたら、さらに発展させるためのアイデアをいくつか紹介する:

変更行数トラッカー: +追加/-削除 を表示してセッションの生産性を把握する
セッション経過時間: total_duration_ms から経過時間を算出する
モデルIDの表示: 異なるモデル設定をテスト中は完全なモデル識別子を表示する
プロジェクトと現在のディレクトリ: Claude Code がサブディレクトリに移動した際に両方を表示する
コスト/分: total_cost_usd を total_duration_ms で割って実際のコスト消費速度を確認する
コンテキストウィンドウバー: 使用率の数字を [========--] のようなビジュアルバーに置き換える
条件付き警告: コンテキストが80%を超えたりコストがしきい値を超えたりした際に色を切り替える

ステータスラインには任意のスクリプトを指定できる。Bash、Python、Node.js、書けるものなら何でも画面に表示できる。

次のステップ

ステータスラインが動き始めたら、次に試したいこと:

コンテキストを積極的に管理する: コンテキストバッファ管理戦略と合わせてコンテキスト使用率を活用する
ターミナル環境をセットアップする: 完全な Claude Code ワークスペースのためのターミナル制御技術を学ぶ
プロジェクト設定を固める: すべてのセッションが正しいコンテキストで始まるよう設定の基本を確認する

Claude Code ステータスラインの設定方法

On this page