本文へ移動
Tech

Claude Code status line 設計ガイド - context・cost・branch を常時見える化する

nidoneko · · 14 min read
Claude CodeAI開発効率化安全運用
📟

Claude Code を長時間使っていると、困るのは「status line をおしゃれにしたい」ことではありません。今どの repo / branch にいるのか、context window がどれくらい膨らんでいるのか、cost がどれくらい増えているのか、PR が draft のままなのか、permission mode が意図どおりか。こういう状態を毎回 /status や git status で確認していると、確認自体が抜けます。

私も複数 worktree で Claude Code を回すとき、作業ディレクトリと branch の取り違え、context が太ったまま別タスクへ進む、PR を開いた後に review state を見落とす、という小さな事故の入口を何度も見ています。ログや Hooks で後から検知する前に、作業中ずっと見える場所へ出した方が早いです。

この記事では、Claude Code の status line を運用 UI として設計する方法を整理します。実行前後に処理を強制する話は Claude Code Hooks の使い方 実践ガイド、組織配布や permissions.deny は Claude Code managed settings 設計ガイド、Claude Code 全体の導入順は Claude Code の使い方 実践ガイド に分けています。Codex 側の受け入れ確認まで含めるなら Codex レビュー完了ゲート設計ガイド も近い役割です。

先に結論: status line は「常時見るべき状態」だけに絞る

Claude Code の公式 docs では、status line は下部に表示されるカスタムバーで、設定した shell script に JSON session data を stdin で渡し、その出力を表示する仕組みとして説明されています。表示候補には model、current directory、context window、cost、git status、PR などがあります。

だから何でも載せられます。ただし、何でも載せると読まなくなります。

私なら、最初の status line は次の5項目に絞ります。

表示するもの理由見落としたときの事故
repo / branch作業場所を取り違えないmain 直作業、別 worktree commit
context used %compact / clear の判断に使う古い文脈を引きずる、cost 増
session cost長時間 run の暴走を早く見る月末まで気付かない
PR number / review statepublish 後の待ち状態を見るdraft / changes requested 放置
permission / effort危険操作や重い推論の状態を見るbypass や high effort の戻し忘れ

逆に、天気、予定、未読メール、外部 dashboard は最初は入れません。Claude Code の status line は開発作業の計器盤です。集中を切らさないための表示であって、情報を集める場所ではありません。

/statusline と手動設定の使い分け

Claude Code では /statusline に自然文で指示すると、script 作成と settings 更新まで自動で進められます。まず試すだけならこれで十分です。

/statusline show current folder, git branch, context percentage, session cost, and PR review state

一方で、チームで再利用するなら手動設定に寄せた方が安定します。公式 docs では ~/.claude/settings.json か project settings に statusLine を置き、type: "command" と script path を指定する形が示されています。

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

refreshInterval も使えます。status line は assistant message、/compact、permission mode 変更、vim mode 変更などの event で再実行されますが、main session が idle のまま background subagent や git 状態が変わる場合は、固定間隔の再実行を足す価値があります。

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "refreshInterval": 15
  }
}

時計だけを動かしたいなら 1 秒更新でもできますが、私はおすすめしません。status line command は local 実行で API token は消費しないとはいえ、重い gh や外部 API を毎秒叩く設計にすると terminal が重くなり、別の障害になります。

最小 status line script

まずは依存を jq と git だけにします。Claude Code は status line script に JSON を渡します。現在の docs では workspace.current_dir、workspace.git_worktree、context_window.used_percentage、cost.total_cost_usd、pr.number、pr.review_state などを使えます。

#!/usr/bin/env bash
set -euo pipefail

input="$(cat)"

dir="$(jq -r '.workspace.current_dir // .cwd // ""' <<<"$input")"
folder="${dir##*/}"
branch="$(git -C "$dir" branch --show-current 2>/dev/null || true)"
worktree="$(jq -r '.workspace.git_worktree // empty' <<<"$input")"
context="$(jq -r '.context_window.used_percentage // 0 | floor' <<<"$input")"
cost="$(jq -r '.cost.total_cost_usd // 0' <<<"$input")"
pr="$(jq -r 'if .pr.number then "#" + (.pr.number|tostring) else "" end' <<<"$input")"
review="$(jq -r '.pr.review_state // ""' <<<"$input")"

printf "%s" "$folder"

if [ -n "$branch" ]; then
  printf " | %s" "$branch"
fi

if [ -n "$worktree" ]; then
  printf " | wt:%s" "$worktree"
fi

printf " | ctx:%s%% | $%.4f" "$context" "$cost"

if [ -n "$pr" ]; then
  printf " | %s %s" "$pr" "$review"
fi

printf "\n"

この段階では色も装飾も要りません。最初に必要なのは、毎回見る値が1行で読めることです。

context と cost は同じ画面で見る

Claude Code の costs docs では、token cost は context size に比例し、/usage や status line で使用量を継続確認できると説明されています。ここはかなり重要です。

/usage は「確認しに行く」操作です。status line は「常に見えている」状態です。長い調査、巨大 log、複数 file read、subagent の繰り返しを使うなら、context used % と cost を同じ行に出します。

私なら、次のような閾値で運用します。

context used判断
0-40%そのまま進める
40-65%次の大きな file read の前に要約する
65-80%/compact か session 分割を検討
80% 以上別 task を混ぜない。handoff summary を作る

ここでやってはいけないのは、context が太った理由を status line だけで判断しようとすることです。原因を見るときは /context や transcript、tool log を見ます。status line は原因分析ではなく、早期警告に使います。

branch / worktree / PR を必ず出す

Claude Code は複数 worktree、background session、PR review と相性がよい一方で、作業場所を間違えると被害が大きいです。

私は status line に最低でも次を出します。

HP | agent/claude-code-statusline-guide-20260727 | ctx:24% | $0.0182 | #253 draft

これだけで、次の確認がかなり減ります。

  • main にいるのか、作業 branch にいるのか
  • repo-local worktree なのか、root checkout なのか
  • PR が開いているのか
  • draft / changes requested / approved のどこで止まっているのか

特に automation や blog publish のような作業では、branch 表示は飾りではありません。git branch --show-current を毎回打つ代わりではなく、打つべきタイミングを逃さないための常時表示です。

permission mode と effort は「戻し忘れ」を防ぐ

status line の available data には effort.level があります。Hooks の docs でも、hook 側に渡る effort は status line の effort field と対応すると説明されています。permission mode については hooks payload に permission_mode があり、default、plan、acceptEdits、auto、dontAsk、bypassPermissions のような値を扱えます。

status line の JSON に常に permission mode がある前提にはしません。ここは Claude Code の version や event によって差が出やすい領域です。必要なら Hooks 側で permission mode を小さな cache file に書き、status line がそれを読む設計にします。

mode_file="${HOME}/.claude/current-permission-mode"
if [ -f "$mode_file" ]; then
  mode="$(cat "$mode_file")"
  printf " | perm:%s" "$mode"
fi

やりたいのは完璧な telemetry ではありません。bypassPermissions や強い effort のまま別作業へ移る事故を減らすことです。

Hooks と status line を混ぜない

status line を作り始めると、つい「危険 branch なら止める」「context が80%を超えたら block する」まで入れたくなります。私は分けます。

役割置き場所
状態を見せるstatus line
操作を止めるPreToolUse hook
終了前に検証するStop hook
組織で禁止するmanaged settings
作業後に説明するaudit log / PR body

status line script は表示用です。ここで複雑な判定や外部 write を始めると、prompt のたびに不安定な処理が走ります。危険操作の遮断は Hooks に、組織配布の制約は managed settings に寄せる方が保守しやすいです。

チーム配布するときの判断基準

個人なら ~/.claude/statusline.sh で十分です。チームで配るなら、project setting に直接重い script を置くより、repo 内に雛形を置いて各自が opt-in する形が扱いやすいです。

docs/claude/statusline.sh
docs/claude/statusline.md

私なら、チーム標準は次のようにします。

  1. repo / branch / context / cost だけを標準表示にする
  2. gh や社内 API を使う segment は opt-in にする
  3. script が失敗しても空行で終わらせ、Claude Code 本体を邪魔しない
  4. secret や token を status line に表示しない
  5. managed settings で status line を固定する場合は、個人の外部連携 segment を入れない

status line は毎回目に入ります。だからこそ、個人情報や外部サービスの値を安易に出すべきではありません。画面共有、録画、スクリーンショットの対象にもなります。

失敗パターン

1. 便利情報を詰め込みすぎる

branch、context、cost、PR、permission だけで十分なことが多いです。天気や予定まで入れると、開発作業の状態が埋もれます。

2. status line command で重い外部 API を叩く

refreshInterval と外部 API を組み合わせると、知らないうちに polling tool になります。必要なら cache を挟みます。

3. 色だけで危険度を表現する

色は便利ですが、terminal やアクセシビリティ設定で見え方が変わります。ctx:82%、perm:bypass のように文字でも読める形にします。

4. permission の強制を status line に入れる

表示 script は止める場所ではありません。止めるなら PreToolUse hook、組織禁止なら managed settings です。

5. project ごとの違いを全部 user settings に入れる

全 repo 共通の status line に project 固有の path や command を入れると壊れます。共通部分は user settings、repo 固有部分は project docs や opt-in script に分けます。

導入順

最初から完成版を作らない方がよいです。

  1. /statusline で model / folder / context だけ作る
  2. script file 化して git branch と cost を足す
  3. PR number / review state を足す
  4. context 60% / 80% の表示だけ強める
  5. 必要なら Hooks で permission mode cache を作る
  6. チーム配布するなら docs に雛形と禁止事項を書く

この順なら、status line は「見た目のカスタム」ではなく、Claude Code の安全運用を支える小さな dashboard になります。

参考資料

WRITTEN BY nidoneko

Full-stack engineer with 8+ years of experience in TypeScript, React, Node.js, and cloud-native development across healthcare, finance, HR, and IoT domains.

View Profile →
// Related articles View All
🧩
Claude Code

Claude Code Skills 設計ガイド - CLAUDE.mdとslash commandから切り出す

·18 min read

Claude Code Skillsを作る前に、CLAUDE.md、slash command、subagent、plugin、cloud sessionと何を分けるべきかを整理します。

Read More →
🧭
Codex

Codex model selection 設計ガイド - Sol / Terra / Luna と reasoning effort を作業別に選ぶ

·13 min read

CodexでSol / Terra / Luna、reasoning effort、Max / Ultraをどう選ぶかを、調査、実装、レビュー、自動化の作業lane別に整理します。

Read More →
🏢
Claude Code

Claude Code 組織導入ルール設計ガイド - 初日・30日・90日で何を決めるか

·14 min read

Claude Code を組織導入するときに、アカウント、設定、権限、MCP、監査、レビューを初日・30日・90日に分けて整えるための運用ルール設計ガイドです。

Read More →