# cc-tmux — Claude Code の busy/idle と セッション名を tmux タブへ

Claude Code の hooks を使って、busy/idle 状態を **tmux タブ名の色（赤）＋左側スピナー**で表示し（US1）、
tmux タブ名を **Claude セッション名に連動**させる（US3）シェル統合。常駐デーモンなし・イベント駆動。

参照: `specs/001-busy-tab-color/`（spec / plan / contracts。開発ワークスペースのみ、公開リポジトリには未同梱）。

## できること

- **US1**: busy のときタブ名が赤くなり、左にブレイルのスピナーが回る（実効 ~1fps）。idle で既定色＋スピナー消滅。
  コンパクション（`/compact`）中も busy 維持（ちらつき防止）。
- **US3**: 起動時にタブ名をセッション名（最初のプロンプト要約 or cwd ベース名）へ。
  既に名前が付いている（`claude -n` / `/rename` / 手動）ウィンドウは**上書きしない**。`/rename` 追従はベストエフォート。
- tmux の外で起動した場合は何もしない（副作用なし）。

## 前提

- macOS、**tmux ≥ 3.2**、**jq**、Claude Code CLI。
- 確認: `tests/check-deps.sh`

## インストール

### 推奨: Claude Code プラグインとして導入（フックを plugin 経由でセット）

`cc-tmux` は Claude Code プラグインです。プラグインを入れると 6 つのフックが自動登録され、
tmux 表示設定（`window-status-format`）も**フックが起動時に遅延適用**するため、
`settings.json` や `~/.tmux.conf` を手で編集する必要はありません。

このリポジトリ直下にローカルマーケットプレイス（`.claude-plugin/marketplace.json`）を同梱しています。

```sh
# Claude Code 内で（<このリポジトリのパス> は clone した場所に読み替え）:
/plugin marketplace add <このリポジトリのパス>
/plugin install cc-tmux@claude-zed-tmux
```

導入後、tmux 内で Claude Code を起動すれば busy で赤＋スピナー、idle で既定色に戻ります。

アンインストール（フック解除）:

```sh
/plugin uninstall cc-tmux@claude-zed-tmux
# 実行中 tmux のグローバル表示設定も戻す場合:
tmux set -gu window-status-format \; set -gu window-status-current-format \; set -gu status-interval \; set -gu @cc_tmux_fmt
```

### 代替: プラグインを使わずスクリプトで導入

プラグイン機構を使わない場合は同梱インストーラで `settings.json` + `~/.tmux.conf` に直接設定できます。

```sh
cc-tmux/bin/cc-tmux-install --install     # settings.json へ hooks 登録 + ~/.tmux.conf へ表示設定追記
tmux source-file ~/.tmux.conf             # 実行中 tmux に反映（install 時に自動でも試行）
cc-tmux/bin/cc-tmux-install --uninstall   # hooks 削除・tmux 設定除去・既定表示へ復元
```

`--project` を付けると `~/.claude/settings.json` ではなくカレントの `.claude/settings.json` を対象にします。

## 仕組み

```
Claude Code hooks ──▶ bin/cc-tmux-hook ──▶ lib/{state,tmux,name}.sh
   SessionStart/UserPromptSubmit/PreToolUse/PreCompact/Stop/SessionEnd
                                   │
                                   ├─ ランタイム状態: ${XDG_RUNTIME_DIR:-${TMPDIR:-/tmp}}/cc-tmux/<session_id>/
                                   └─ 表示: tmux per-window options @cc_state / @cc_spin（tmux/cc-tmux.tmux が条件分岐）
                                   └─ スピナー: bin/cc-tmux-spinner（短命ループ, busy 中のみ）
```

- 全フックは常に **exit 0**（Claude のターンを妨げない）。
- 状態の真実はランタイム状態ファイル、表示の真実は tmux ユーザーオプション。各イベントで同期。

## テスト

```sh
bats cc-tmux/tests/unit          # state.sh / name.sh
bats cc-tmux/tests/integration   # tmux new-session 上で @opt→フォーマット展開を検証
```

> `bats` 未導入の環境では `tests/` のスクリプトは実行できません（Homebrew: `brew install bats-core`）。
> `shellcheck` も同様に任意（`brew install shellcheck`）。

## 既知の制約

- tmux ステータスバーのアニメーションは再描画スロットルにより **~1fps が上限**（滑らかな高速回転は不可）。
- `/rename` の完全追従は公開 API/フックが無く**ベストエフォート**（transcript に名前が残る場合のみ反映、壊れたら静かに諦める）。
- 1 ペイン 1 セッションを基本前提。