# Claude Code Statusline 設定：経路、フィールド、スクリプト、修正手順

> Claude Code statusline の安全な設定経路を選び、mock JSON でスクリプトを確認してから context、cost、git フィールドを追加し、空白や古い表示を直します。

- URL: https://blog.laozhang.ai/ja/posts/claude-code-statusline
- Published: 2026-05-19
- Updated: 2026-05-19
- Author: AI Free API Team (https://blog.laozhang.ai/ja/about)
- Category: Claude Code
- Tags: Claude Code, Statusline, 開発者ツール, CLI, Anthropic

---
Claude Code statusline はローカルコマンドです。Claude Code が現在のセッション JSON を stdin に渡し、あなたのコマンドが stdout に出した文字列が画面下部の statusline になります。個人用に素早く始めるなら `/statusline`、内容をレビューして制御したいなら手動 `statusLine`、チームで共有するなら全員に安全なコマンドだと確認してから project settings に置きます。

![Claude Code statusline の設定経路ボード](https://blog.laozhang.ai/posts/ja/claude-code-statusline/img/cover-codex.webp)

順序は、見た目ではなく、経路、コマンド契約、設定スコープ、表示フィールドです。statusline は model、directory、git branch、context 使用率、cost estimate、条件によって rate limit 情報を表示できます。ただし、どのフィールドも欠ける可能性があるため、スクリプトは null と未定義を前提に作ります。

| 経路 | 使う場面 | 最初の確認 |
| --- | --- | --- |
| `/statusline` | 個人用の初版をすぐ作りたい | 行が表示され、生成スクリプトを読める |
| 手動 `statusLine` | レビュー可能なスクリプトと fallback が必要 | Claude Code 外で mock JSON テストが通る |
| Project settings | 同じ非 secret の動作を repo で共有したい | 全員が同じコマンドパスを安全に実行できる |
| Third-party formatter | テーマや複雑なレイアウトが依存追加に見合う | ソース、install scope、ローカル実行境界を説明できる |

## statusline の実行契約を先に押さえる

statusline はターミナルテーマでも追加の API 呼び出しでもありません。Claude Code の UI がローカルコマンドを起動し、stdin に JSON を入れ、stdout を読み取り、その文字列を下部の行として表示します。つまり、先に理解すべきなのは配色ではなく、どのコマンドがどこで実行されるかです。

この仕組みには三つの意味があります。第一に、コマンドはローカルで実行されます。`git` を呼び出したり、作業ディレクトリを読んだり、home 配下のスクリプトを実行したりできます。個人用には便利ですが、project settings で共有する場合は信頼境界になります。

第二に、スクリプトは防御的であるべきです。JSON には model、workspace、git、cost、context、session、version、output style、vim、agent、worktree、rate limit などが入る場合がありますが、すべての環境で同じとは限りません。よい statusline は `ctx:?` や `git:-` のように落ち着いて fallback します。

第三に、stdout がそのまま読者の見る画面です。デバッグログは stderr に逃がし、表示行は短く、安定し、速くします。長いダッシュボードを作るより、日常で一瞬で読める一行が有用です。

## 最初の個人版は `/statusline` で作る

まず Claude Code 内で次を実行します。

```text
/statusline
```

依頼文は短く具体的にします。

```text
Show model, current directory, git branch, context percentage, and estimated cost. Keep it one line and handle missing fields.
```

Claude Code はスクリプトを生成して設定できます。動いたら必ずファイルを開いて内容を読みます。これは見た目の設定ではなく、ローカルコマンドの承認です。絶対パス、ネットワークアクセス、private endpoint、重い `git status` が含まれていたら、そのまま共有しません。

`/statusline` は試行錯誤に向いています。どのフィールドが自分に役立つか、どの表示が長すぎるかを確認する段階です。チーム標準にする段階では、手動 `statusLine` に戻り、パス、fallback、速度、信頼を明示します。

## 制御が必要なら手動 `statusLine`

手動設定では settings に command object を書きます。

```json
{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline/statusline.js",
    "refreshInterval": 5
  }
}
```

重要なのは `type` と `command` です。`refreshInterval` は必須ではありません。時計のような値や外部キャッシュ状態を定期更新したい場合だけ使います。通常は Claude Code のイベント更新で足ります。むやみに短くすると、遅いスクリプトの問題が見えにくくなります。

個人用なら `~/.claude/` 配下で十分です。チーム用なら repo 内の `.claude/statusline/` に置けますが、通常のコードと同じように review します。個人の home path、secret、特定マシンだけの依存を共有設定に入れてはいけません。

## mock JSON で先に実行確認する

![Claude Code statusline のデータフロー](https://blog.laozhang.ai/posts/ja/claude-code-statusline/img/explainer-1-codex.webp)

次の Node.js 例は stdin を読み、JSON を安全に解釈し、stdout に一行だけ出します。

```js
#!/usr/bin/env node

let input = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  input += chunk;
});

process.stdin.on("end", () => {
  let data = {};
  try {
    data = input.trim() ? JSON.parse(input) : {};
  } catch (error) {
    console.error(`statusline JSON parse failed: ${error.message}`);
  }

  const model = data.model?.display_name || data.model?.id || "model?";
  const cwd = data.workspace?.current_dir || data.cwd || "";
  const dir = cwd ? cwd.split("/").filter(Boolean).pop() : "workspace?";
  const branch = data.git?.branch ? `git:${data.git.branch}` : "git:-";
  const context =
    typeof data.context_window?.percentage === "number"
      ? `ctx:${Math.round(data.context_window.percentage)}%`
      : "ctx:?";
  const cost =
    typeof data.cost?.total_cost_usd === "number"
      ? `$${data.cost.total_cost_usd.toFixed(2)} est`
      : "$? est";

  process.stdout.write(`${model} | ${dir} | ${branch} | ${context} | ${cost}`);
});
```

保存して実行権限を付け、Claude Code なしで確認します。

```bash
chmod +x ~/.claude/statusline/statusline.js
printf '%s' '{"model":{"display_name":"Claude Sonnet"},"workspace":{"current_dir":"/Users/me/project"},"git":{"branch":"main"},"context_window":{"percentage":42},"cost":{"total_cost_usd":0.18}}' | ~/.claude/statusline/statusline.js
```

期待する結果は一行です。外部で動かないコマンドを Claude Code に登録しても安全にはなりません。先に mock JSON で直し、stdout と stderr の役割を分けます。

## 表示フィールドは仕事から選ぶ

![Claude Code statusline のフィールド矩陣](https://blog.laozhang.ai/posts/ja/claude-code-statusline/img/explainer-2-codex.webp)

statusline は視線移動を減らすためのものです。今どの project にいるか、どの model か、git は汚れているか、context はどれくらいか、cost estimate は大きくなっていないか。この程度を一瞬で判断できれば十分です。

| フィールド | 表示の候補 | 注意点 |
| --- | --- | --- |
| Model | 短い model 名 | 長い名前は行を圧迫する |
| Workspace | basename または workspace 名 | 絶対パスは避ける |
| Git | branch、dirty state | 大きい repo では cache |
| Context window | percentage や残量 | 欠損に備える |
| Cost | session estimate | 請求額そのものではない |
| Rate limits | remaining/reset がある場合 | 全員にあるとは限らない |
| Session/version | debug 用の状態 | 普段はノイズになる |
| Agent/worktree/vim | mode に依存する情報 | 必要な人だけ表示 |

読みやすい一行は、identity、location、state、risk の四つ程度です。

```text
Sonnet | api-docs | main* | ctx:42% | $0.18 est
```

`main*` は変更ありの合図にできます。context と cost はリスク指標です。不要なら削り、表示幅を守ります。

## 設定スコープを間違えない

Claude Code settings には複数のスコープがあります。statusline は、コマンドが安全に実行できるスコープに置きます。

| スコープ | 向いているもの | リスク |
| --- | --- | --- |
| User settings | 個人の既定 statusline | 他人の machine では path がない |
| Local project settings | machine 固有の上書き | チームが再現しにくい |
| Shared project settings | non-secret の共有動作 | secret や個人 path を入れない |
| Managed settings | 組織ポリシー | 個人表示には重い |
| Session/CLI override | 一時テスト | 永続的な契約には弱い |

チームで使うならこうします。

```json
{
  "statusLine": {
    "type": "command",
    "command": "./.claude/statusline/statusline.js"
  }
}
```

このスクリプトは review 済みで、secret なし、private endpoint なし、速く、fallback あり、簡単に無効化できる必要があります。

## 更新は軽く保つ

statusline は何度も呼ばれます。毎回ネットワークを叩いたり、巨大な `git status` を走らせたりすると、Claude Code の操作感が悪くなります。

実務では三つだけ守れば十分です。Claude Code から来た JSON フィールドを優先する。高価な処理は cache する。`refreshInterval` は定期更新が本当に必要な場合だけ使う。

直接測定します。

```bash
time printf '{}' | ~/.claude/statusline/statusline.js
```

ここで遅いなら、Claude Code の設定ではなくスクリプトの問題です。行を短くし、外部アクセスを消し、Git チェックを軽くします。

## Windows と terminal 表示

Windows で壊れるときは、多くの場合 JSON ではなく shell/path です。Git Bash、PowerShell、WSL、Node で quote、path、改行が変わります。Claude Code が実際に起動するのと同じ command を確認します。

最初は plain text にします。ANSI color、powerline glyph、OSC 8 link は最後に追加します。macOS で動いて Windows だけ壊れる場合は、interpreter path、executable path、line endings、cwd を順に確認します。

## third-party formatter を使う条件

formatter はテーマや ready-made layout が必要なときに役立ちます。ただし事実の所有者ではなく、単なるローカルコマンドです。

| チェック | 理由 |
| --- | --- |
| maintainer と source が許容できる | ローカルで実行される |
| install scope が明確 | global install は複数 project に効く |
| official stdin JSON を読む | private endpoint は壊れやすい |
| missing field に強い | すべての account が同じではない |
| 速い | 何度も実行される |
| すぐ無効化できる | 排障時に戻せる |

何を実行しているか説明できない formatter は使わず、小さい自作スクリプトのままにします。

## 空白、skipped、古い表示の直し方

![Claude Code statusline のトラブルシュート順](https://blog.laozhang.ai/posts/ja/claude-code-statusline/img/explainer-3-codex.webp)

| 症状 | すぐ確認すること | 修正 |
| --- | --- | --- |
| 行が出ない | command を直接実行 | path、interpreter、権限 |
| 外では動く | mock JSON を流す | trust prompt や scope |
| 空白 | stdout/stderr を確認 | 最終行を stdout に出す |
| `undefined` | 欠損 JSON で実行 | optional chaining と fallback |
| 古い | 遅い処理を消す | cache または bounded refresh |
| skipped | debug を見る | trust、hooks、command failure |
| Windows だけ失敗 | 同じ shell/path で実行 | 明示的な interpreter |
| 色や link が崩れる | plain text に戻す | terminal 機能は最後 |

`disableAllHooks` も排障面に入ります。むやみに切り替えると、期待していた hook-like 動作まで止まる可能性があります。

## 関連 Claude Code ガイド

- CLI から始めるなら [Claude Code install](https://blog.laozhang.ai/ja/posts/claude-code-install)。
- credential と route は [Claude Code API configuration](https://blog.laozhang.ai/ja/posts/claude-code-api-configuration)。
- API key と subscription の違いは [Claude Code API key vs subscription billing](https://blog.laozhang.ai/ja/posts/claude-code-api-key-vs-subscription-billing)。
- 状態表示が安定したら [Claude Code memory](https://blog.laozhang.ai/ja/posts/claude-code-memory)。
- workflow を再利用するなら [Claude Code best skills](https://blog.laozhang.ai/ja/posts/claude-code-best-skills)。

## よくある質問

### `statusline` と `statusLine` は同じですか？

同じ書き方ではありません。`statusline` は一般語、`/statusline` は slash command、`statusLine` は settings の JSON key です。

### statusline は API token を使いますか？

statusline command 自体はローカル実行で、追加の model request ではありません。Claude Code が渡したデータを表示するだけです。

### rate limits は表示できますか？

入力 JSON にある場合だけ表示できます。`rate_limits` がないときも正常に動くようにします。

### project に script を commit してよいですか？

全員に安全な場合だけです。secret なし、path-safe、高速、fallback あり、review 済み、簡単に無効化できる必要があります。

### `undefined` が出るのはなぜですか？

スクリプトが存在しないフィールドを前提にしています。欠損 mock JSON を流し、fallback を追加します。

### 最初の一行は何を出すべきですか？

model、directory basename、git branch、context percentage、cost estimate が十分です。色や formatter は安定後に追加します。