コンテンツにスキップ

ccs

ハブ 1 本から、tmux 上に複数の Claude Code セッションを立て・見つけ・畳むための CLI。

これは何を解くのか

Claude Code のセッションを増やしたいとき、これまでは人がターミナルを開いて claude を打つ 必要があった。セッションの中にいるエージェントからは新しいセッションを開けない。

ccs はそこだけを埋める。ハブ（Remote Control を張った 1 本）から ccs new を呼べば、 tmux の上に新しいセッションが立ち、そのままハブの ListAgents に現れて指示を送れる。 ターミナルを閉じても tmux が残すので、セッションは生き続ける。

詳しくは なぜ ccs が要るのか — 素のセッションで何が起きないかの実測と、 tmux・CLI を選んだ理由。

薄い

セッション管理でやりたいことの大半は、Claude Code 2.1.x が既に持っている （実測）。

やりたいこと 担当
全セッションの一覧・状態 claude agents --json（組み込み）
ハブ → 子セッションへの指示 ListAgents / SendMessage（組み込みツール）
tmux ペインとの対応づけ Claude 自身が記録する
セッション ID の固定 claude --session-id <uuid>（組み込み）
skills が見えること ~/.claude/skills がユーザレベルなので cwd に依らない
セッションの新規作成 ccs
workspace trust ダイアログの回避 ccs
ghq / 一時ディレクトリの解決 ccs
命名規約と後片付け ccs

ccs が持つのは下 4 つだけ。

コマンド
ccs new <target> [-- <初期プロンプト>] セッションを立てる
ccs ls [--json] 立っているものを一覧する
ccs ls -l [--json] 盤面 ── 直近の依頼 / RSS / 最終更新も出す
ccs attach [<slug>] 乗り込む（slug を省くと番号で選ぶ）
ccs agents [-l] [--json] このマシンの claude を俯瞰する（管轄外は SLUG が -。ccs ls には混ぜない）
ccs adopt <target> [--pid <pid>] ccs 管轄外のセッションを引き取る（元を閉じ、同じ会話を cc/<slug> で開き直す）
ccs kill [--force] <slug> 畳む。畳んだ会話は「終わった」と記録され、再起動のあとの ccs restore に並ばない（名指しなら戻せる）
ccs kill --self [--force] そのセッション自身を畳む（アプリのアーカイブでは残るため）。ccs 管轄外のセッションからも使える。ccs が立てたセッションには「終了と言われたらこれを打つ」と伝えてある（CCS_DONE_NOTE）
ccs gc [--yes] 止まったセッション・アプリで閉じられたセッション・空の作業枠・不要になった worktree を掃除する（worktree は clean + 本体に入っている + push 済み のときだけ。squash マージも見る）
ccs restore [--yes] [--json] 止まった／消えたセッションを同じ会話で立て直す
ccs resolve <target> [--json] 立てる前に、どこに解決されるかを見る
ccs config [--json] 効いている設定と、その出どころを見る
ccs version [--short] どの版が走っているかを見る（コミットまで）
ccs doctor 何の版が入っていて、最新かを見る
ccs hub … 常時 1 本のハブを立て、落ちても戻るようにする

手元にいないときのために

スマホから触るなら、ハブ 1 本が常に生きていることが前提になる。アプリから 届くのは生きているセッションだけなので、ハブが死ぬと ccs を叩く経路ごと消える。

ccs hub up は冪等（生きていれば何もしない）なので、launchd / systemd から 定期的に呼ぶだけで死活監視になる。推奨は「ログイン時 + 5 分ごと」（既定の CCS_HUB_AUTOSTART=on）── healthy なときは claude を起動せずに 0.06 秒で 終わるので、頻度を落とす利得がない。

ccs hub up                                                    # まず手で 1 回立てる
ccs hub agent --print > ~/Library/LaunchAgents/local.ccs.hub.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.ccs.hub.plist

Linux（systemd）の手順、確かめ方、外し方は hub を常時立てる。

自分の環境に合わせる

既定値は作者の環境に合わせてある。困るところは設定で変えられる ── hub という名前のリポジトリを持っているなら hub の名前を、Remote Control を 使わないならその要求を、自動起動が要らないならそれ自体を。

いま効いている値は ccs config、キーの一覧は 設定。

ccs attach は同じマシンからしか使えない

ccs のセッションは tmux が pty を持つため、Claude アプリからは端末の画面が見えない。 外出先でアプリしか持っていない状況では端末に届かない。 事情と回避策は なぜ ccs が要るのか §4、 追跡は #19。

要件

  • tmux
  • jq
  • claude 2.1.x 以降（--session-id と claude agents --json に依存する）
  • macOS / Linux。Windows は対象外（POSIX sh 前提）

この先