{"id":51014505,"url":"https://github.com/yohasebe/tmux-ccm","last_synced_at":"2026-06-21T08:31:36.907Z","repository":{"id":355747447,"uuid":"1188403027","full_name":"yohasebe/tmux-ccm","owner":"yohasebe","description":"An attention manager for parallel Claude Code sessions — tmux plugin with live state detection, dashboard, and cross-project messaging.","archived":false,"fork":false,"pushed_at":"2026-06-15T22:27:33.000Z","size":6213,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T00:15:04.610Z","etag":null,"topics":["ai","attention-management","claude","claude-code","developer-tools","session-manager","terminal","tmux","tmux-plugin","tui"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yohasebe.png","metadata":{"files":{"readme":"README.ja.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-22T02:52:31.000Z","updated_at":"2026-06-15T22:27:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yohasebe/tmux-ccm","commit_stats":null,"previous_names":["yohasebe/tmux-ccm"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/yohasebe/tmux-ccm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohasebe%2Ftmux-ccm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohasebe%2Ftmux-ccm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohasebe%2Ftmux-ccm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohasebe%2Ftmux-ccm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yohasebe","download_url":"https://codeload.github.com/yohasebe/tmux-ccm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yohasebe%2Ftmux-ccm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34603546,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","attention-management","claude","claude-code","developer-tools","session-manager","terminal","tmux","tmux-plugin","tui"],"created_at":"2026-06-21T08:31:36.198Z","updated_at":"2026-06-21T08:31:36.900Z","avatar_url":"https://github.com/yohasebe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/logo-light.png\"\u003e\n  \u003cimg alt=\"ccm — Claude Code Manager for tmux\" src=\"assets/logo-light.png\" width=\"380\" align=\"left\"\u003e\n\u003c/picture\u003e\n\u003cbr clear=\"left\"\u003e\n\u003cbr\u003e\n\n[![tested](https://img.shields.io/badge/tested-Claude%20Code%20v2.1.185-brightgreen)](https://docs.anthropic.com/en/docs/claude-code)\n[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![tmux](https://img.shields.io/badge/tmux-3.2%2B-blue)](https://github.com/tmux/tmux)\n\nccm は、[Claude Code](https://docs.anthropic.com/en/docs/claude-code) を複数プロジェクトで並行して使う開発者のための tmux プラグインです。各 Claude セッションをタグ付きの tmux ウィンドウとして扱い、状態をライブで検出するので、「どれが応答中で、どれが許可待ちで、どれは終わってるんだっけ」と tmux ウィンドウを行き来する必要がなくなります。\n\n実質的に **アテンション・マネージャ** として動きます。各プロジェクトに状態 (BUSY / IDLE / 許可待ち) を付与し、ダッシュボードはそれを優先度順に並べ、キー 1 つで「次に対応すべきウィンドウ」に移動できます。\n\nポップアップダッシュボードで全プロジェクトの状態 (busy / idle / 許可待ち)、git ブランチ、リスニングポートを一目で確認できます。スナップショットで tmux 再起動後のレイアウトを復元し、デスクトップ通知で対応が必要なプロジェクトだけを知らせます。\n\nccm の価値は並行度に応じて伸びます。2–3 プロジェクトでも有用、4 つ以上を並行で動かすと日常のインフラになります。Max プランで複数プロジェクトに agent を並行で走らせている層に最もフィットします。\n\n## ccm のメンタルモデル\n\n1 つの **プロジェクト** = 1 つの **フォルダ** = 1 つの **tmux ウィンドウ**。ウィンドウは任意の数のペインを持ちます (claude code、シェル、開発サーバー、Agent Teams のチームメイト等)。各 claude code ペインの状態 (PERMIT / BUSY / IDLE) はウィンドウへ集約され、ccm ダッシュボード (`prefix + Tab`) でウィンドウ間を切り替えられます。\n\n![ccm メンタルモデル: tmux session が複数のウィンドウを持ち (各ウィンドウ = 1 プロジェクト = 1 フォルダ)、各ウィンドウに claude code とその他のペインが入り、claude code の状態はウィンドウに集約され、ccm が prefix + Tab でウィンドウ間を切り替える](assets/mental-model.svg)\n\n**ダッシュボード** (`prefix + Tab`) — 画面下部のモード 2 ステータスバーも同時に映っています:\n\n![ccm dashboard](assets/dashboard.png)\n\n## 機能\n\n- **リソース管理** — アイドル状態の Claude Code セッションを 10 分後に自動終了してメモリと CPU を解放。ウィンドウに戻ると会話を引き継いで自動再起動\n- **ダッシュボード** — Claude Code の状態 (BUSY / IDLE / PERMIT) をリアルタイム表示するインタラクティブポップアップ\n- **ツリービュー** — セッション / ウィンドウ / ペインの階層表示とナビゲーション\n- **Git 連携** — プロジェクトごとに git ブランチと dirty 状態を表示\n- **ポート検出** — プロジェクトごとのリスニングポートを表示\n- **スナップショット** — プロジェクトレイアウトの保存と復元\n- **プロジェクト間メッセージング** — `ccm send \u003cproject\u003e \u003cmessage\u003e` で他プロジェクトの Claude にプロンプト送信、状態に応じた安全な制御 (PERMIT は拒否、BUSY は `--force` でキュー投入)\n- **自動起動** — Claude Code が起動していないプロジェクトに attach すると自動起動\n- **ステータスライン** — アクティブプロジェクトの状態を tmux ステータスバーに表示\n- **多バイト文字対応** — CJK 文字や絵文字を含むプロジェクト名がダッシュボード・ステータスバー・CLI テーブルで正しく整列\n- **Agent Teams 対応** — Claude Code の [Agent Teams](https://code.claude.com/docs/en/agent-teams) と併用可能: ccm でプロジェクトを管理しつつ、各プロジェクト内で並行エージェントを実行\n\n## 動作要件\n\n- tmux 3.2+\n- Python 3.9+\n- [TPM](https://github.com/tmux-plugins/tpm)（手動インストールも可）\n- jq\n- fzf\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) **v2.1.107 以上**\n\n## インストール\n\n### TPM を使う場合（推奨）\n\n`~/.tmux.conf` に追加：\n\n```tmux\nset -g @plugin 'yohasebe/tmux-ccm'\n```\n\ntmuxをリロードし、`prefix + I` でインストール。\n\n### 手動インストール\n\n```bash\ngit clone https://github.com/yohasebe/tmux-ccm.git ~/.tmux/plugins/tmux-ccm\n```\n\n`~/.tmux.conf` に追加：\n\n```tmux\nsource-file ~/.tmux/plugins/tmux-ccm/ccm.tmux.conf\n```\n\n### PATHに追加\n\nCLI（`ccm add`、`ccm status` 等）を使うには、プラグインディレクトリをPATHに追加：\n\n```bash\n# .zshrc または .bashrc に追加\nexport PATH=\"$HOME/.tmux/plugins/tmux-ccm:$PATH\"\n```\n\n### Zsh補完（オプション）\n\n```bash\n# .zshrc に追加（compinit の前）\nfpath=($HOME/.tmux/plugins/tmux-ccm/completions $fpath)\n```\n\n## 初回セットアップ\n\nClaude Codeを初めて使う場合は、先に認証を済ませてください：\n\n```bash\nclaude\n```\n\n対話的なセットアップが始まり、プラン選択（サブスクリプションまたはAPIキー）とブラウザ認証を行います。認証が完了したら、セットアップウィザードを実行してください：\n\n```bash\nccm init\n```\n\nフックのインストール、自動復元、ステータスバーの設定をまとめて案内します。\n\n\u003e [!NOTE]\n\u003e フックはプラグイン読み込み時（TPM経由）に自動インストールされ、プラグイン更新時にも自動で最新化されます。手動で管理したい場合は `ccm setup-hooks` / `ccm remove-hooks` を使用してください。\n\n## 使い方\n\n### キーバインド\n\n| キー | 動作 | デフォルト |\n|------|------|-----------|\n| `prefix + Tab` | ダッシュボードをトグル | 有効 |\n| `prefix + T` | ツリービューをトグル | 無効（オプトイン） |\n| `prefix + C` | ccmメニューを開く | 無効（オプトイン） |\n\n他のプラグインとの競合を避けるため、ダッシュボードのみデフォルトで有効です。ツリービューとメニューはダッシュボード内で `t` または `m` を押してもアクセスできます。\n\nダッシュボードのキーを変更したり、任意キーを有効化するには `~/.tmux.conf` に追加してください：\n\n\u003e [!IMPORTANT]\n\u003e すべての `set -g @ccm-*` オプションは、ccm プラグインが読み込まれるよりも**前に** `~/.tmux.conf` で設定する必要があります。`source-file` 行(手動インストール)および TPM の `run` 行(TPM インストール)よりも**前**に配置してください。プラグインは読み込み時にこれらのオプションを参照するため、後に配置された設定は黙って無視されます。\n\n```tmux\nset -g @ccm-key-dashboard \"Tab\"  # デフォルト。リマップする場合に上書き(例: \"F12\")\nset -g @ccm-key-menu \"C\"         # 任意: prefix + C でメニュー\nset -g @ccm-key-tree \"T\"         # 任意: prefix + T でツリービュー\nset -g @ccm-key-search \"/\"       # 任意: prefix + / でダッシュボードをライブフィルタ検索で開く\n                                  # (日本語対応、入力でリアルタイム絞り込み、\n                                  #  Enter でアタッチ、Esc でキャンセル)\n```\n\n\u003e [!TIP]\n\u003e prefix なしの単一キーでダッシュボードをトグルする場合は `@ccm-key-dashboard-noprefix` を使います。例えば `F1` に割り当てる場合:\n\u003e\n\u003e ```tmux\n\u003e # 必ず ccm プラグインの読み込み行よりも前に配置 (上記 IMPORTANT 参照)。\n\u003e set -g @ccm-key-dashboard-noprefix \"F1\"\n\u003e ```\n\u003e\n\u003e `F1` で開き、もう一度 `F1` で閉じます。popup タイトルの色付き ccm ロゴもそのまま表示されます (自前で `bind-key -n F1 display-popup …` を書くこともできますが、`-T` の format 文字列を完全にコピーしないとロゴは出ません)。\n\n### デスクトップ通知\n\nプロジェクトの状態変化時にデスクトップ通知（macOS / Linux対応）を送信できます：\n\n```tmux\nset -g @ccm-notify \"permit,completed\"     # PERMITと完了時に通知\n```\n\n| 値 | 動作 |\n|----|------|\n| `permit,completed`（デフォルト） | 許可プロンプトと完了時に通知 |\n| `permit` | 許可が必要な時に通知 |\n| `completed` | 完了時に通知（Claudeのレスポンス完了） |\n| `all` | 全ての状態変化 |\n| `off` | 通知なし |\n\n通知音を有効化：\n\n```tmux\nset -g @ccm-notify-sound \"on\"     # デフォルト: off（macOSでは「Glass」サウンドを再生）\nset -g @ccm-notify-sound-name \"Ping\"  # 任意: サウンドをカスタマイズ（macOSのみ）\n```\n\n#### macOS — `terminal-notifier` の導入を推奨\n\nデフォルトでは ccm は macOS 通知に `osascript` を使用します。各通知は通知センターに追加され、ユーザーが消すまで残ります。マルチプロジェクトで長時間運用すると数百件の古い通知が蓄積し、WindowServer / NotificationCenter が高 CPU になることがあります。\n\n`terminal-notifier` を導入するとこの問題は解消します — ccm がプロジェクトごとの group ID (`-group ccm-\u003cproject\u003e`) で送信するため、同じプロジェクトの新しい通知は前の通知を **置き換え** ます。\n\n```bash\nbrew install terminal-notifier\n```\n\nccm が `PATH` 上の有無を自動検出して優先使用します。設定不要。\n\n\u003e [!IMPORTANT]\n\u003e `terminal-notifier` が初めて通知を送る際、macOS は通知許可ダイアログを表示することがあります — 許可してください。導入後に ccm 通知が届かない場合は「システム設定 → 通知 → terminal-notifier」を開き「通知を許可」が ON になっているか確認してください。通知は terminal-notifier 自身の bundle id 名義で配送されるため（使用しているターミナルエミュレータには非依存）、許可は一度で済み、Terminal.app / iTerm2 / WezTerm / kitty / ghostty いずれでも同じ動作になります。\n\n通知センターに残った ccm 通知を一括削除（`terminal-notifier` が必要）:\n\n```bash\nccm clear-notifications\n```\n\n削除対象は group id が `ccm-` で始まる通知のみで、ユーザーが他のスクリプト（デプロイ通知 / モニタリング等）で送った terminal-notifier 通知は影響を受けません。実際に削除した件数を表示します。\n\n`terminal-notifier` を導入できず蓄積問題に当たった場合は、`@ccm-notify \"permit\"` に設定して頻度の高い COMPLETED 通知をスキップし、要対応の PERMIT 通知のみ受け取るのが良いでしょう。\n\n#### Linux — `notify-send`\n\nLinux では `notify-send` を使用します。macOS の `-group` のようなプロジェクト単位の重複防止機構は無いため、長時間運用時は `@ccm-notify \"permit\"` に設定して通知量を抑えてください。\n\n`ccm clear-notifications` は macOS 専用です。Linux には既存通知を一覧/削除するコマンドラインAPIがないため、コマンドは「terminal-notifier is not installed」と表示して終了します。\n\n### ステータスバー\n\ntmuxステータスバーにプロジェクト状態を表示します。表示モードを設定：\n\n```tmux\nset -g @ccm-status-line 2     # デフォルト\n```\n\n| 値 | モード | 説明 |\n|----|--------|------|\n| `0` | アイコン | status-right にウィンドウ番号付きアイコンを追記（最も控えめ — 既存テーマを変えない） |\n| `1` | 全表示 | ウィンドウリストを ccm 形式の色付きエントリに置換 |\n| `2` | 専用行（デフォルト） | メインバー下に専用行を追加し、全プロジェクトをブランチ・ポート情報付きで表示 |\n\n**モード 2 がデフォルト**。既存の tmux テーマをそのまま残したい場合はモード 0 が最も保守的な選択です。\n\n#### モード0 — アイコン＋ウィンドウ番号\n\n既存のstatus-rightにウィンドウ番号付きアイコンを追加。時計やバッテリー表示はそのまま保持。アクティブなプロジェクトがある場合はウィンドウ番号も表示（例: `5: PERMIT ⚠`）。全てIDLEの場合は `≡` アイコンのみ：\n\n```\n ... 既存のstatus-right ...   5: PERMIT ⚠   14:32\n                              └────────────┘\n                          ウィンドウ番号 + 最高優先度の状態\n```\n\n| 優先度 | 条件 | アイコン | 色 |\n|--------|------|---------|-----|\n| 1（最高） | PERMITのプロジェクトあり | `⚠` | 黄 |\n| 2 | BUSYのプロジェクトあり | `◉` | オレンジ |\n| 3（最低） | 全てIDLE | `≡` | グレー |\n\nアイコンをクリックするとダッシュボードが開く。\n\n#### モード1 — 全表示（ccm形式ウィンドウリスト）\n\ntmux標準のウィンドウリストをccm形式の色付きエントリに置換。既存のstatus-right（時計等）は保持。\n\n```\n 2:weather-cli ●   3:recipe-blog ◉   4:todo-react ◉   5:api-server ⚠\n```\n\n#### モード2 — 専用ステータス行\n\nメインバーの下に専用ステータス行を追加。IDLEを含む全プロジェクトをgitブランチ・ポート情報付きで表示。メインバーは変更しない（上のダッシュボード画像下部にも mode 2 が映っています）。\n\n```\n ... 通常のステータス行はそのまま ...                            14:32\n ────────────────────────────────────────────────────────────────── (ガター)\n 5:api-server (main) ⚠ PERMIT  ·  3:recipe-blog (main) ◉ BUSY\n   ·  4:todo-react ◉ BUSY  ·  2:weather-cli ● IDLE * 20s\n```\n\n| 状態 | アイコン | 色 |\n|------|---------|-----|\n| PERMIT | `⚠` | 黄 |\n| BUSY | `◉` | オレンジ |\n| IDLE | `●` | ブルー |\n| IDLE（最近完了） | プロジェクト名後に `* \u003celapsed\u003e` | 緑 |\n| SHELL | `■` | 暗グレー |\n\n端末幅とプロジェクト数に応じて行数が自動拡張。\n\nダークグレーのガターが既存テーマと合わない場合は、tmux オプションで配色を上書きできます:\n\n```tmux\nset -g @ccm-status-bg         \"#262626\"   # エントリ行の背景色\nset -g @ccm-status-gutter-bg  \"#1a1a1a\"   # メインバーとエントリ行の間のガター（1行分）\nset -g @ccm-status-fg         \"#9E9E9E\"   # デフォルト前景色\nset -g @ccm-status-fg-dim     \"#5a5a5a\"   # 区切り記号やヒント表示\n```\n\n受理される値: 16 進カラー (`#RGB` / `#RRGGBB`)、`colour123` 形式のパレットインデックス、または名前付きカラー (`red` / `blue` / `default` 等)。無効な値はデフォルトにフォールバックします。\n\n\u003e [!NOTE]\n\u003e モード2は追加の `status-format` スロット（1行のガター + レイアウト1行ごとに1スロット、最大 16）を使用します。他のプラグインがこれらのインデックスを使用している場合、衝突が発生する可能性があります。\n\n### ダッシュボード操作\n\n| キー | 動作 |\n|------|------|\n| `↑↓` / `jk` | プロジェクト間をナビゲート |\n| `Enter` | 選択プロジェクトに切替 |\n| `s` | スナップショット保存 |\n| `p` | プレビュー表示（`c` でクリップボードにコピー） |\n| `a` | プロジェクト追加 |\n| `n` | 選択プロジェクトの名前変更 |\n| `g` | 既存ウィンドウを登録 |\n| `r` | 削除 — [u]nregister（ウィンドウ残す）か [d]elete を選択 |\n| `x` | アイドル状態のClaude Codeを一括終了 |\n| `/` | プロジェクト名で検索 |\n| `t` | ツリービューに切替 |\n| `b` | [バックグラウンドセッションセクション](#バックグラウンドセッションセクションagent-view共存) を切替 |\n| `m` | メニューに切替 |\n| `q` / `Esc` / `F1` | 閉じる |\n\n### CLIコマンド\n\n```\nccm add \u003cdir\u003e [name]              プロジェクト追加（ウィンドウ作成+Claude起動）。\u003cdir\u003e が\n                                  存在しない場合は作成するか確認（親ディレクトリは存在必須）\nccm open \u003cdir\u003e [name]             現在のペインでClaude起動（split-pane用）\nccm register \u003cwindow\u003e [name]      既存ウィンドウをccmプロジェクトとして登録\nccm unregister \u003cname\u003e             ccm管理から外す（ウィンドウは残る）\nccm rename \u003cname\u003e \u003cnew_name\u003e      プロジェクト名を変更\nccm remove \u003cname\u003e                 プロジェクトウィンドウ削除（ウィンドウを閉じる）\nccm attach \u003cname|number\u003e          プロジェクトウィンドウに切替\nccm list                          管理中プロジェクト一覧\nccm status                        全プロジェクト状態表示（ブランチ・ポート含む）\nccm tree                          セッション/ウィンドウ/ペインの階層表示\nccm ports                         プロジェクトごとのリスニングポート表示\nccm capture [--copy] \u003cname|#id\u003e   ペイン内容をキャプチャ（--copy: クリップボード）\nccm dashboard                     インタラクティブダッシュボードを開く\nccm menu                          インタラクティブメニュー\nccm snapshot save|load|list|delete  スナップショット管理\nccm start \u003csnapshot\u003e              スナップショットから復元\nccm stop [--all|name]             プロジェクト停止（--all時は_autosave自動保存）\nccm send \u003cname\u003e \u003cmsg\u003e [flags]     他プロジェクトのClaude Codeセッションにプロンプト送信\n                                  flags: --file --stdin --no-enter --force --start -y --\nccm bg list                       外部の Claude Code agent-view セッション一覧（読み取り専用）\nccm init                          対話型セットアップウィザード（フック・復元・ステータスバー）\nccm setup-hooks                   Claude Codeフックをインストール（検出精度向上）\nccm remove-hooks                  Claude Codeフックをアンインストール\nccm setup-claude-md               ~/.claude/CLAUDE.mdにccmセクションを追加\nccm remove-claude-md              ~/.claude/CLAUDE.mdからccmセクションを削除\nccm statusline                    1行ステータス出力（tmuxステータスバー用）\nccm inject-status                 tmuxステータスバー更新（内部使用）\nccm debug trace \u003cname\u003e [interval] 状態検出のライブトレース（読み取り専用、Ctrl-Cで終了）\nccm errors [--clear]              silent-exception ログの表示／クリア\nccm reset \u003cname\u003e                  プロジェクトの runtime 状態をリセット (最終手段の復旧)\nccm doctor                        セルフチェック (依存・フック・カナリア・プロジェクト・エラー)\nccm clear-notifications           macOS 通知センターから ccm 通知を削除\n```\n\n\u003e [!TIP]\n\u003e 多くのコマンドに短縮エイリアスがあります: `ls` (list), `st` (status), `a` (attach), `rm` (remove), `d` (dashboard), `reg` (register), `unreg` (unregister), `mv` (rename), `cap` (capture), `snap` (snapshot), `sl` (statusline)\n\n### ステータスアイコン\n\n| アイコン | 状態 | 説明 |\n|----------|------|------|\n| ⚠ | PERMIT | ユーザーの許可待ち |\n| ◉ | BUSY | Claude処理中 |\n| ● | IDLE | 入力待ち |\n| `* \u003celapsed\u003e` | IDLE（最近完了） | BUSY/PERMIT → IDLE 遷移後 30 秒間表示される一時マーカー（アスタリスク緑、時間 dim） |\n| `[N]` | （任意の状態、マルチペインウィンドウ） | ペイン数マーカー（角括弧 dim、数字 cyan）。ウィンドウに 2 ペイン以上ある場合に表示 |\n| ■ | SHELL | シェルのみ（Claude未起動） |\n| ○ | DOWN | ウィンドウ利用不可 |\n\n### Claude Codeフック（推奨）\n\nより正確な状態検出のために、Claude Codeフックをインストールします：\n\n```bash\nccm setup-hooks\n```\n\n`~/.claude/settings.json` にフックが追加され、状態変化を通知します：\n- **UserPromptSubmit** → プロンプト送信時にBUSY（テキスト生成を検出）\n- **PreToolUse / PostToolUse / PostToolUseFailure** → ツール実行中にBUSY\n- **SubagentStart / SubagentStop** → サブエージェント実行中にBUSY（親エージェントは作業継続中）\n- **PreCompact / PostCompact** → コンテキスト圧縮中にBUSY\n- **Stop / StopFailure** → Claude応答完了時にBUSY信号をクリア\n- **PermissionRequest** → ツールの許可が必要な時にPERMIT\n- **Notification** → 許可プロンプト/MCP elicitation 表示時にPERMIT（permission_prompt / elicitation_dialog）、アイドル通知時に信号クリア（idle_prompt）\n- **SessionEnd** → セッション終了時にSHELL（/exit、Ctrl+D等）\n- **PermissionDenied** → autoモードで拒否時にPERMIT（`/permissions`で再試行）\n\nccm はフック非依存のフォールバックを備えており、Claude Code がセッション途中でフック発火を停止しても検出が継続します:\n\n- **JSONL セッションログ心拍**: プロジェクトの最新 `~/.claude/projects/.../jsonl` に user/assistant レコードがあればセッション稼働中の証拠（housekeeping レコードは除外）\n- **許可ダイアログのフッター検出**: 許可フッター（`Esc to cancel · Tab to amend`）をペインから直接検出\n- **`~/.claude/hooks.log` 肥大化カナリア**: このファイルが 100MB を超えると silent fail の原因になるため警告表示。修復: `: \u003e ~/.claude/hooks.log`\n\nフックの状態はダッシュボードのフッターと `ccm status` の出力に表示されます（Hooks: ON/OFF）。既にインストール済みの場合、`ccm setup-hooks` は再インストールをスキップします。ccmを別のパスに再インストールした場合は、フックのパスが自動的に更新されます。\n\n削除するには: `ccm remove-hooks`\n\n### スナップショット\n\nワークスペースのレイアウトを保存して後から復元：\n\n```bash\nccm snapshot save my-workspace\nccm snapshot list\nccm start my-workspace\n```\n\n`_autosave` スナップショットはプロジェクトがアクティブな間、2分間隔で自動更新されます。`ccm stop --all` 実行時にも保存：\n\n```bash\nccm start _autosave   # 前回のセッションを復元\n```\n\n#### tmux起動時の自動復元\n\ntmux起動時に最後の `_autosave` スナップショットを自動復元：\n\n```tmux\nset -g @ccm-auto-restore \"on\"    # デフォルト: off\n```\n\n有効にすると、tmux起動時にTPM経由で `_autosave` スナップショットを自動ロードします（既にccmプロジェクトがある場合はスキップ）。\n\n### アイドル自動終了\n\n一定時間IDLEのままのClaude Codeセッションは自動的に終了し、システムリソースを解放します。終了したウィンドウに切り替えると、Claude Codeが `--continue` で自動再起動し、会話を再開します。\n\n```tmux\nset -g @ccm-idle-timeout \"10\"    # 分（デフォルト: 10、0で無効化）\n```\n\n### ダッシュボードプレビューパネル\n\n選択中のプロジェクトのターミナル内容をプロジェクトリストの横にライブ表示します：\n\n```tmux\nset -g @ccm-preview \"on\"              # デフォルト: off\nset -g @ccm-preview-position \"right\"  # または \"bottom\"\n```\n\nカーソル移動で即座に更新され、自動リフレッシュもされます。ANSIカラー（256色、RGB）に対応。端末幅80列以上（右配置）または高さ20行以上（下配置）が必要です。ダッシュボードメニュー（`m`）からもトグル可能。\n\n### Claude Code自動起動\n\nSHELL状態（Claude Codeが終了済み）のプロジェクトウィンドウに切り替えると、ccmが自動的に `--continue` 付きでClaude Codeを再起動し、会話を再開します。\n\n```tmux\nset -g @ccm-auto-start \"on\"     # デフォルト: on（\"off\"で無効化）\n```\n\nダッシュボードメニュー（`m`）からも設定可能です。\n\n### バックグラウンドセッションセクション（agent-view共存）\n\nClaude Code 2.1.139 で導入された agent view（`claude agents` / `claude --bg` / `claude attach`）は、ユーザーごとの supervisor daemon の下で複数セッションを実行します。ccm はこれら外部セッションをプロジェクト一覧の下に読み取り専用セクションとして表示できるため、tmux 管理下のプロジェクトと daemon 管理下のバックグラウンドセッションを 1 つのダッシュボードで俯瞰できます。\n\n```tmux\nset -g @ccm-bg-section \"always\"   # デフォルト: off\n```\n\nデフォルトはオフ（「window = project」運用には影響なし）。ダッシュボードで `b` を押すと一時的にトグル（設定は永続化しない）、`always` にすると常時表示されます（ダッシュボードメニュー `m` からも切替可能）。bg 行で `Enter` を押すと新規 tmux ウィンドウ（ccm 管理外）が開き `claude attach \u003cshort\u003e` が自動実行されます — ccm 管理外のウィンドウを使うことで auto-start による attach 横取り（Issue 6）を構造的に回避します。ccm は daemon の `roster.json` と各セッションの `state.json` を観察するだけで、dispatch / stop などのライフサイクル操作は `claude` CLI の責務のまま残しています。ダッシュボード外では `ccm bg list` で同じ情報を取得できます。\n\n### アンチフリッカー\n\nccmはtmux内でのClaude CodeのUIフリッカーを軽減するため、`CLAUDE_CODE_NO_FLICKER=1` を自動設定します。ユーザー側の設定は不要です。\n\n## Tips\n\n### Claude Codeに他プロジェクトの存在を教える\n\nデフォルトでは、各Claude Codeセッションは他のプロジェクトの存在を知りません。グローバル設定ファイル（`~/.claude/CLAUDE.md`）にccmコマンドの情報を追記することで、これを改善できます：\n\n```markdown\n## マルチプロジェクト環境\n\nこのユーザーはccm（Claude Code Manager for tmux）で複数プロジェクトを同時管理している。\n他プロジェクトの情報が必要な場合は以下のコマンドが利用可能:\n\n- `ccm list` — 管理中の全プロジェクト一覧（名前・ディレクトリ）\n- `ccm status` — 全プロジェクトの状態（ブランチ・ポート含む）\n- `ccm capture \u003cname\u003e` — 指定プロジェクトのClaude Code画面出力を取得\n```\n\nこれにより、すべてのClaude Codeセッションがccm配下の他プロジェクトを発見・参照できるようになります。例えば、あるライブラリが別のプロジェクトでどう使われているかを調べたり、別プロジェクトの `CLAUDE.md` を読んだりできます。\n\n自動設定：\n\n```bash\nccm setup-claude-md     # ~/.claude/CLAUDE.md にccmセクションを追加\nccm remove-claude-md    # ccmセクションを削除\n```\n\n### tmuxセッションでプロジェクトをカテゴリ分け\n\ntmuxセッションを分けることで、プロジェクトを文脈ごとにグループ化できます（例: 業務、OSS、研究）。ccmはセッションごとに独立して動作し、ダッシュボードとステータスバーはそのセッションのプロジェクトのみを表示します。\n\n```bash\ntmux new-session -s work       # 業務プロジェクト\ntmux new-session -s oss        # OSSプロジェクト\n\n# 各セッション内で通常通りプロジェクトを追加:\nccm add ~/code/auth-service\nccm add ~/code/dashboard-ui\n\n# セッション間の切り替え:\ntmux switch-client -t oss      # tmux標準のセッション切り替え\n```\n\n\u003e [!TIP]\n\u003e スナップショットとの併用も効果的です。各セッションで `ccm snapshot save` / `ccm start` を使えば、プロジェクトレイアウトの保存・復元をセッション単位で独立して行えます。\n\n## 仕組み\n\n- プロジェクトはtmuxウィンドウの `@ccm_project` / `@ccm_dir` タグで管理\n- Claude Codeの状態はフック信号＋プロセスツリー検査で検出（プロンプトパターンマッチも補助的に使用）\n- 完了マーカー（`* \u003celapsed\u003e`）はBUSY/PERMIT → IDLE遷移後に30秒間表示\n- tmuxテーマとの併用に対応（status-rightの変更を自動検出）\n\n## アンインストール\n\n1. `~/.tmux.conf` から削除：\n   ```tmux\n   # この行を削除:\n   set -g @plugin 'yohasebe/tmux-ccm'\n   # または source-file の場合:\n   # source-file ~/.tmux/plugins/tmux-ccm/ccm.tmux.conf\n   ```\n\n2. tmux状態をクリーンアップ：\n   ```bash\n   # ccmオプションを削除\n   tmux set -g -u @ccm-orig-status-right 2\u003e/dev/null\n   tmux set -g -u @ccm-orig-sr-length 2\u003e/dev/null\n   tmux set -g -u @ccm-status-line 2\u003e/dev/null\n   tmux set -g -u window-status-format 2\u003e/dev/null\n   tmux set -g -u window-status-current-format 2\u003e/dev/null\n\n   # 一時ファイルを削除\n   rm -rf \"${TMPDIR:-/tmp}/ccm-$(id -u)\"\n\n   # ランタイムデータを削除（任意 — スナップショットも消えます）\n   rm -rf ~/.local/share/ccm\n   ```\n\n3. tmuxをリロード: `tmux source-file ~/.tmux.conf`\n\n## ドキュメント\n\n- [ユーザーガイド](docs/guide.ja.md)\n- [English README](README.md) / [User Guide](docs/guide.md)\n\n## ライセンス\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyohasebe%2Ftmux-ccm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyohasebe%2Ftmux-ccm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyohasebe%2Ftmux-ccm/lists"}