Codeman

AI コーディングエージェントの司令塔

Claude Code • OpenCode • Codex • Antigravity • Gemini • Pi • Grok • DeepSeek • OMP • Copilot • ターミナル - 1つのダッシュボード • あらゆるデバイス

英語 • 簡体字中国語

Codeman は、AI コーディングエージェントのためのセルフホスト可能な司令塔です。Claude Code、OpenCode、Codex、Antigravity、Gemini、Pi、Grok、DeepSeek Harness、OMP、GitHub Copilot CLI を永続的な tmux セッション内で起動し、実際のターミナルをあらゆるブラウザーにストリーミングします。席を外した後もエージェントの作業を継続できるよう、アイドル時にプロンプトを再送し、使用制限のリセット後に再開し、スケジュールされたジョブを実行し、バックグラウンドで動作中のすべてのエージェントをリアルタイムで表示します。

1行で始められます（macOS および Linux、Windows は WSL 経由）：

curl -fsSL https://getcodeman.com/install | bash

codeman web
# Open http://localhost:3000 and start your first session

インストーラーはシステムを変更する前に毎回確認を求めます。同じコマンドを再実行すると、そのまま更新されます。詳しくは、クイックスタート - インストールをご覧ください。

• 1つのダッシュボードで10種類のCLI - セッションごとに Claude Code、OpenCode、Codex、Antigravity、Gemini、Pi、Grok、DeepSeek、OMP、GitHub Copilot（および通常のシェル）をローカル、Docker 内、または SSH 経由で実行でき、独自のダッシュボードも ウェブタブとして並べて開けます
• 本当にスマートフォンで使いやすい - 即時のローカルエコー、QR ログイン、スワイプ操作、プッシュ通知に対応したタッチ操作に最適化されたターミナル
• 眠っている間も実行 - アイドル検出＋再起動サイクルと、サブスクリプションの制限がリセットされた際の自動再開により、24時間以上の無人実行が可能です
• エージェントの思考を確認 - すべてのサブエージェントとチームメイトを対象に、リアルタイムのトランスクリプト付きのライブフローティングウィンドウを表示します
• エージェントからも操作可能 - （すべてのエージェントCLIで使える）codeman スキル、codeman agent、および MCP サーバーを使うと、1つのエージェントから任意のCLIでワーカーを起動し、プロンプトを送信して応答を待ち、回答を収集できます
• 何も失われません - 再起動やネットワーク切断をまたいだ tmux の永続化、入力の厳密な1回配信、スクロールバック全体の再生に対応しています
• セルフホスト可能でプライベート - デフォルトではループバックのみで動作し、MIT ライセンス、テレメトリーなし、すべてをお使いのマシン上で実行します

クイックスタート - インストール

curl -fsSL https://getcodeman.com/install | bash

Node.js、tmux、ビルドツールチェーンが見つからない場合はインストールします（node-pty には Linux 用のビルド済みバイナリが含まれていないため、ソースからコンパイルされます）。Codeman を ~/.codeman/app にクローンしてビルドします。マシンにすでにあるものを確認し、質問は最大3つまでにしてから、すべての作業を無人で行い、最後にスマートフォン用の QR コード付き URL を表示します。知っておくとよい点をいくつか紹介します。

• 質問は最初に3つだけです。 ダッシュボードへのアクセス方法、このマシンを tailnet 上で何と呼ぶか（任意）、Codeman をバックグラウンドサービス（systemd/launchd、起動時に自動起動）として実行するかどうかです（Enter キーで「はい」）。不足しているパッケージをすべてインストールする際の同意、sudo パスワード、Tailscale へのログインなど、ユーザーの操作が必要なことはすべてビルド前に済むため、コンパイル中はその場を離れても大丈夫です。
• アクセス方法は選べます。 Tailscale（tailscale serve を前面にしたループバックバインドにより、実際の証明書とログインに tailnet を使って https://<machine>.<tailnet>.ts.net にアクセスできます。パスワードは不要です）、ネットワーク上のすべてのデバイス（0.0.0.0。パスワードの設定を強く推奨します）、またはこのマシンのみ（127.0.0.1。最も安全です）。ネットワークバインドでパスワードを省略するには明示的な確認が必要で、最後に目立つ警告が表示されます。ハイライト表示されるデフォルトはマシンの現在の状態を反映します（すでに接続済みなら Tailscale、再実行なら既存のバインド）。何も入力せずに Enter キーを押しても、新しいソフトウェアはインストールされません。ノードですでに別のアプリが :443 を使用している場合、置き換えるのではなく、Codeman は https://<machine>.<tailnet>.ts.net/codeman または別のポートで動作します。手動で起動した codeman web は、引き続きデフォルトでループバックを使用します。
• マシン名は自由に選べます。 デフォルトでは、URL にマシンの既存の tailnet 名が使われます。2つ目の質問に「はい」と答えると、マシン名が codeman-<hostname> に変更されます（SSH で使う名前も変わるため、デフォルトは「いいえ」です）。後から install.sh name で変更できます。
• 再実行して更新できます。 同じワンライナーで、インストール済みのものをそのまま更新できます。~/.codeman/app のローカル変更は一時退避され（破棄されません）、実行中のサービスは再起動されて動作確認されます。初回インストールが中断された場合、再実行すると代わりにセットアップ全体が再開されます。install.sh status を実行すると、URL と QR コードが再度表示されます。install.sh update、install.sh tailscale、install.sh uninstall も利用できます。
• すぐに進めたい場合のフラグ。 curl -fsSL https://getcodeman.com/install | bash -s -- --tailscale --service を実行すると、コマンドラインから質問に回答できます（--lan、--local、--run、--no-start、--name <n>、--port <n>、--yes も利用できます）。CI／ヘッドレス環境： ターミナルが接続されていない場合、システムに変更を加える手順は黙って実行されず、案内を表示して中止されます。自動化のために承認するには、CODEMAN_NONINTERACTIVE=1 を設定してください。

AI コーディング CLI が少なくとも1つインストールされている必要があります — Claude Code、OpenCode、Codex、Antigravity、Gemini CLI、Pi、Grok Build、DeepSeek Harness、OMP、または GitHub Copilot CLI（任意の組み合わせで利用できます。Google の一般向けサービス移行に伴い、Gemini CLI はエンタープライズ専用となっており、後継は Antigravity です）。インストーラーは、10種類のうちインストール済みのものを検出します。どれも見つからない場合は、メニューからいずれかをインストールできます（DeepSeek は除きます。npm パッケージには実行可能なプロファイルがなく、ランチャーしかインストールされないためです）。または、この手順をスキップして、後から自分でインストールすることもできます。インストール後：

codeman web
# Open http://localhost:3000 and start your first session

少人数のチームで共有しますか？ 代わりにマルチユーザーモードで起動すると、各ユーザーに専用のログインとワークスペースが用意されます。

codeman users add alice --admin      # create the first admin account
codeman web --multiuser              # named logins + per-user case spaces

Docker Compose をお好みですか？ ローカルイメージを使った Compose デプロイ用ファイルは docker/ にあります。docker/.env.example を docker/.env にコピーし、CODEMAN_PASSWORD を設定してから、Linux で bash docker/Start-Codeman.sh を実行してください。Codeman はコンテナ内で動作し、ホストソケット経由で兄弟コンテナとして Docker ケースを起動します。更新後は、単に docker compose up を実行するのではなく、スクリプトをもう一度実行してください。これにより、再ビルドされたイメージ、更新されたボリューム、エントリーポイントがまとめて反映されます。Compose コマンドの直接実行、ストレージ、ネットワークの各オプションについては、Docker デプロイガイドをご覧ください。

詳細は以下のマルチユーザーモードをご覧ください。

codeman web -d          # detach; logs to ~/.codeman/web.log
codeman web --status    # is it up, and on which pid
codeman web --stop      # graceful SIGTERM; agents keep running in tmux

codeman service install     # systemd user unit (Linux) or LaunchAgent (macOS)
codeman service status
codeman service uninstall

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/codeman-web.service << EOF
[Unit]
Description=Codeman Web Server
After=network.target

[Service]
Type=simple
ExecStart=$(which node) $HOME/.codeman/app/dist/index.js web
Restart=always
RestartSec=10

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now codeman-web
loginctl enable-linger $USER

mkdir -p ~/Library/LaunchAgents
cat > ~/Library/LaunchAgents/com.codeman.web.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.codeman.web</string>
  <key>ProgramArguments</key>
  <array>
    <string>$(which node)</string>
    <string>$HOME/.codeman/app/dist/index.js</string>
    <string>web</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key>
  <string>/tmp/codeman.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/codeman.log</string>
</dict>
</plist>
EOF
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.codeman.web.plist

wsl bash -c "curl -fsSL https://getcodeman.com/install | bash"

モバイルに最適化された Web UI

どのスマートフォンでも、最も応答性に優れた AI コーディングエージェント体験を提供します。ローカルエコー、スワイプナビゲーション、タッチ操作に最適化されたインターフェースを備えた完全な xterm.js ターミナルで、小さな画面にデスクトップ UI を詰め込んだものではなく、実際のリモート作業のために設計されています。

タッチ操作でプロンプトに回答	アクセサリーバー＋専用 Enter ボタン

• キーボードアクセサリーバー — 仮想キーボードの上に /init、/clear、/compact のクイックアクションボタンを表示します。誤操作を防ぐため、破壊的なコマンドの実行には2回のタップによる確認が必要です。Codex セッションでは、バーに ⇧← / ⇧→（Shift+Left / Shift+Right：最後にキューへ追加したメッセージを編集／プロンプトスタックをさかのぼる）も表示されます
• 専用 Enter ボタン — キー入力をターミナルに再送信し、ローカルエコーでバッファリングされたテキストをそのまま残さず、先にフラッシュします
• 添付ボタン：マイクの横にある写真アイコンを押すと、キーボードを表示せずにシステムの写真・ファイル選択画面が開きます。写真とカメラロールの動画（mp4、mov、webm、最大1 GB）はセッションのフォルダーにアップロードされ、そのパスが送信されない状態でプロンプトに入力されます
• シェルへの貼り付け：複数行の貼り付けは1つのブロックとして入力され、入力された行を逐次実行するのではなく、Enter が押されるまで待機します
• スワイプナビゲーションとスマートなキーボード処理 — 左右にスワイプしてセッションを切り替えます。キーボードを開くとツールバーとターミナルが上に移動します（visualViewport API）
• スマートフォン向け設計 — ノッチとホームインジケーターに対応するセーフエリアのインセット、44px のタッチターゲット、ボトムシート形式の case ピッカー、ネイティブの慣性スクロールを備えています。折りたたみ式スマートフォン（iPhone Duo）ではダイアログがヒンジに重ならず、デバイスの開閉がキーボード操作と誤認されることもありません

codeman web --https
# Open on your phone: https://<your-ip>:3000

localhost は通常の HTTP で動作します。別のデバイスからアクセスする場合は --https を使用するか、Tailscale（推奨）を使ってください。インストーラーで設定できます（ネットワークアクセスのプロンプトで Tailscale を選ぶか、既存のインストール環境で bash ~/.codeman/app/install.sh tailscale を実行してください）。これにより、実際の証明書を使用する https://<your-machine>.<tailnet>.ts.net が利用できます。tailnet 内でのみアクセスでき、パスワードは不要です。スマートフォンでは PWA のインストールとプッシュ通知も利用できます。インストーラーの最後に、スキャン用の QR コードとともにこの URL が表示されます。また、bash ~/.codeman/app/install.sh status を実行すれば、いつでも再表示できます。

セキュアな QR コード認証

スマートフォンのキーボードでパスワードを入力するのは大変です。Codeman はそれを暗号学的に安全な使い捨て QR トークンに置き換えます。デスクトップに表示されたコードをスキャンすれば、スマートフォンがすぐに認証されます。

各 QR コードには、サーバー上の 256 ビットの秘密情報（crypto.randomBytes(32)）に対応する 6 文字の短縮コードを含む URL がエンコードされています。トークンは60 秒ごとに自動更新され、最初のスキャン時にアトミックに消費されるため、再利用は常に失敗します。また、応答時間から情報が漏れない、ハッシュベースの Map.get() 検索を使用します。短縮コードは不透明なポインターであり、本当の秘密情報がブラウザーの履歴、Referer ヘッダー、Cloudflare のエッジログに現れることはありません。

このセキュリティ設計は、「Demystifying the (In)Security of QR Code-based Login」（USENIX Security 2025）で特定された QR 認証に関する 6 つの重大な欠陥すべてに対処しています。同論文では、上位 100 サイトのうち 47 サイトに脆弱性があることが判明しました。対策は、使い捨ての徹底、有効期間の短縮、暗号学的乱数、サーバー側での生成、スキャン時のデスクトップへのリアルタイム通知（QRLjacking の検知）、および IP + User-Agent によるセッションの紐付けと手動での取り消しです。二層のレート制限（IP ごと + 全体）により、62^6 = 568 億通りのコードに対する総当たり攻撃は実行不可能です。セキュリティ分析の全文はこちらです：docs/qr-auth-plan.md

Codeman の使い方 — ユーザー向けガイド

ブラウザーから Codeman を操作する手順を、最初から最後まで説明します。インストールしたばかりの場合は、ここから始めてください。

1. サーバーを起動する

codeman web                       # localhost:3000 (loopback only — safe default)
codeman web --port 8080           # custom port (or set CODEMAN_PORT)
codeman web --https               # self-signed TLS (only needed for remote access)
codeman web -H 0.0.0.0            # bind LAN — REQUIRES CODEMAN_PASSWORD (see Security)
codeman web -d                    # detach: survives closing the shell (--status, --stop)
codeman service install           # systemd/launchd service: comes back after reboots

表示された URL を開きます。このページは単一のダッシュボードで、以下の操作はすべてここで行います。

2. 最初のセッションを作成する

+ New Session（または Quick Start）をクリックします。セッションとは、それぞれ専用の tmux ベースのターミナルで実行される AI CLI のことです。次の項目を選択します。

開始すると、Codeman は実際の PTY を介して CLI を起動し、SSE 経由でブラウザーにストリーミングします。

3. ダッシュボードを見る

• タブ（上部） — セッションごとにタブが表示されます。Alt+1～9 で切り替え、Ctrl+Tab で次のタブに移動できます。ドラッグして並べ替えると、タブの順序がデバイス間で同期されます。リスト表示を使う場合は、App Settings → Appearance → Tabs で左側のサイドバー（フィルターボックス付き。Alt+B で折りたたみ可能）、またはアクティビティ順に並ぶ縦型レールに切り替えられます。縦型レールでは、応答待ちのセッション、実行時間の長いセッション、最後に操作されてから時間が経ったセッションの順に表示されます。レールには Search sessions ボックス、名前付きのタブグループ（グループのメニューから、そのグループに直接 New session を開始できます）、そしてよく使うタブへのショートカットをまとめた Focus セクションもあります。
• ターミナル（中央） — 実際の xterm.js ターミナルで、完全な TUI を正しく表示できます。直接入力し、Enter を押して送信します。Shift+Enter で改行を挿入できます。
• サイドパネル — Respawn、Orchestrator、Cron、Subagents、Settings（ツールバーから切り替えます）。

4. エージェントと会話する

• プロンプトを入力 — ターミナルに直接入力します。再接続をまたいでも入力は確実に一度だけ送信されます（接続が切れても、プロンプトが失われたり二重送信されたりすることはありません）。
• 画像、動画、ドキュメントを貼り付け、ドロップ、または添付 — PDF、Office ファイル、zip、プレーンテキストをセッションに直接取り込めます。ワークスペース内の非表示の .codeman-uploads/ フォルダーに保存されます（git では無視され、7 日後に削除されます）。ファイルのパスは、未送信の状態でプロンプトに追加されます。
• 音声入力 — Ctrl+Shift+V（Deepgram Nova-3、または API キー不要でこのマシンの Claude Code ログインを使用。無音を検知すると自動停止します）。
• 添付ファイル — 外部ファイルやドキュメントを登録して、Office ファイルや PDF をインラインでプレビューできます。エージェントが出力したファイルパスは、ターミナルとチャット画面の両方でクリックできます。~/ から始まるパス、相対パス、複数行にまたがるパスにも対応しています。.html レポートは実際のページとして開き、Markdown はレンダリングして表示し、フォルダーは中のファイルをグリッド表示します。
• 応答が必要なとき — 入力待ちのタブは黄色に、質問で処理が止まっているタブは赤色に変わります。承認受信トレイ (オプトイン) では、Claude Code、Codex、DeepSeek Harness のセッションで応答を待っているプロンプトを1つのリストにまとめます。Claude のプロンプトにはヘッダーのベルから回答でき、Claude のダイアログにはスマートフォンのホーム画面からも回答できます。また、Claude の権限確認プロンプトはプッシュ通知の［承認］／［拒否］ボタンからも回答できます。Codex と DeepSeek の項目はターミナルで回答するよう通知するアラートで、その他の CLI のプロンプトはこの受信トレイには表示されません。🧠 私の考えを読む (オプトイン) では、ケースの目標と最近の作業内容から次のプロンプトを作成します。
• 表示内容をコピー — CLI がマウスを使用中でも Shift+ドラッグ でテキストを選択でき、右クリックでコピーできます。自動コピー (オプトイン) を有効にすると、選択範囲を離した瞬間にコピーされます。OSC 52 でコピーするプログラム（Claude Code の /copy、tmux の yank、vim など）を使うと、ブラウザーのクリップボードにもテキストが保存されます。

5. 自律的に動作させる

6. どこからでもアクセスする

• スマートフォン／タブレット — UI はタッチ操作に最適化されています。デスクトップのQR コードをスキャンすれば、パスワードを入力せずにログインできます。
• ネットワーク外から — ./scripts/tunnel.sh start を実行すると、Cloudflare トンネルが開きます（先に CODEMAN_PASSWORD を設定してください）。
• SSH — codeman tui を実行すると、ターミナルでフルスクリーンのダッシュボードを開きます（codeman tui --list で一覧表示、codeman tui 2 でそのセッションに直接接続）。

7. 運用と保守

• アプリの設定 — モデル、作業量、起動時の権限モード、テーマ／スキン、ターミナルのフォントファミリーと太さ、入場アニメーションとタイルアニメーション（専用のアニメーションセクション）、通知（トーストとブラウザー通知の表示時間を調整可能）、表示の切り替え、CLIごとのオプション、同期されるカスタム表示名、デバイスごとの英語／簡体字中国語 UI 言語を設定できます。適用をクリックすると、設定を閉じずに保存できます。
• バックグラウンドで実行する — codeman web -d を使うとシェルから切り離して実行できます（--status、--stop）。codeman service install を使うと、再起動後も維持される systemd ユーザーユニット／macOS LaunchAgent としてインストールできます。どちらも成功を報告する前にサーバーが実際に応答することを確認し、同じデータディレクトリで2つ目のサーバーを起動しようとすると拒否します。バックグラウンドで実行し続けるを参照してください。
• セルフアップデート — git clone でインストールした場合は、アプリの設定 → システム → アップデートからインプレースで更新できます。
• 独自の変更をデプロイする — 開発を参照してください。

⚠️ 安全性： Codeman が管理するセッションの 内側 で作業している場合（echo $CODEMAN_MUX → 1）、tmux kill-session ／ pkill claude を直接実行しないでください。Web UI または ./scripts/tmux-manager.sh を使用してください。

ゼロ遅延入力オーバーレイ

VPN、Tailscale、SSH トンネル経由でコーディングエージェントにリモートアクセスする場合、通常はキー入力の往復に毎回200～300msかかります。Codeman は Mosh に着想を得たローカルエコーシステムを実装しており、遅延に関係なく、すぐに入力できるようにします。

xterm.js 内のピクセル単位で精密な DOM オーバーレイが、0ms でキー入力を描画します。バックグラウンド転送では、文字ごとの入力を50msのデバウンスバッチで PTY に静かに送信するため、Tab 補完、Ctrl+R の履歴検索、その他すべてのシェル機能が通常どおり動作します。200～300ms後にサーバー側のエコーが届くと、オーバーレイがシームレスに消え、実際のターミナルテキストに切り替わります。この移行は目に見えません。

• Ink の描画に影響されない設計 — .xterm-screen 内の z-index 7 にある <span> として動作し、Ink による絶え間ない画面再描画の影響を完全に受けません（terminal.write() を使った以前の2つの試みでは、Ink が挿入されたバッファーの内容を破損しました）。
• フォントを一致させた描画 — xterm.js の計算済みスタイルから fontFamily、fontSize、fontWeight、letterSpacing を読み取り、オーバーレイのテキストが実際のターミナル出力と視覚的に区別できないようにします。
• 完全な編集機能 — バックスペース、再入力、貼り付け（複数文字）、カーソル追跡、入力がターミナル幅を超える場合の複数行折り返しに対応します。
• 再接続後も維持 — 未送信の入力は localStorage を介してページの再読み込み後も保持されます。
• デフォルトで有効 — アイドル中と処理中の両方のセッションで、デスクトップとモバイルの両方で動作します。

スタンドアロンライブラリとして切り出されています：xterm-zerolag-input — 公開パッケージを参照してください。

ライブエージェント可視化

バックグラウンドエージェントの作業をリアルタイムで確認できます。Codeman はエージェントのアクティビティを監視し、各エージェントをドラッグ可能なフローティングウィンドウに表示します。親セッションにつながる、Matrix 風のアニメーション付き接続線も表示します。

• フローティングターミナルウィンドウ — エージェントごとのドラッグ・サイズ変更可能なパネルです。各ツール呼び出し、ファイルの読み込み、進捗更新をリアルタイムで表示するアクティビティログを備えています
• 接続線 — 親セッションと子エージェントをつなぐアニメーション付きの緑色の線です。エージェントの起動や完了に合わせてリアルタイムで更新されます
• ステータスとモデルのバッジ — 緑（アクティブ）、黄（アイドル）、青（完了）のインジケーターと、Haiku／Sonnet／Opus のモデル別カラー表示です
• 自動動作 — 起動時にウィンドウを自動で開き、完了時に自動で最小化します。タブのバッジには「AGENT」または「AGENTS (n)」と表示されます
• ネストされたエージェント — 3階層の構成（リードセッション -> チームメイトエージェント -> サブサブエージェント）に対応します

マルチエージェントのワークフロー実行（「ultracode」）も同様に可視化されます。フローティング実行ウィンドウでワークフロー全体をリアルタイムに追跡し、フェーズ、エージェントごとのトークン数、各エージェントが現在使用しているツールを表示します。

エージェントチーム — Claude Code のネイティブなマルチエージェントチームに完全対応しています（CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1）。TeamWatcher は ~/.claude/teams/ をポーリングし、チームメイトをリードセッションに紐付けて、ライブのサブエージェントウィンドウに表示します。チーム対応のアイドル検出により、チームメイトが作業中の間は Respawn Controller が起動しません。詳しくは docs/agent-teams/ をご覧ください。

Respawn Controller

自律作業の中核です。エージェントがアイドル状態になると、Respawn Controller がそれを検出し、続行プロンプトを送信します。また、コンテキスト管理コマンドを順に実行してコンテキストを更新し、作業を再開します。これにより、24時間以上完全に無人で実行できます。

WATCHING → IDLE DETECTED → SEND UPDATE → /clear → /init → CONTINUE → WATCHING

• 多層アイドル検出 — 完了メッセージ、AI によるアイドルチェック、出力の無通信状態、トークンの安定性を検出します
• 利用上限時の自動再開 （オプトイン、デフォルトではオフ） — Claude がサブスクリプションの上限に達して停止した場合（「You've hit your limit · resets 3pm」）、Codeman がリセット時刻を解析し、安全のための2分間を加えて待機します。その後、レート制限ダイアログを閉じて continue を送信するため、一晩の実行が5時間の制限時間を超えても、朝まで停止せずに済みます。Claude Code のあらゆる上限メッセージ形式を認識し、上限が続く場合は再試行します。Codeman の再起動後も状態を保持し、待機中の会話が /clear で消去されないよう、一時停止中は respawn サイクルを保留します。Respawn タブ上部からセッションごとに有効化できます
• サーキットブレーカー — Claude が停止状態に陥った際の過剰な respawn を防ぎます（CLOSED -> HALF_OPEN -> OPEN の状態を持ち、進捗のない状態の連続やエラーの繰り返しを追跡します）
• ヘルススコア — サイクルの成功率、サーキットブレーカーの状態、反復の進捗、停止状態からの復旧に関するコンポーネントスコアから、0〜100 のヘルススコアを算出します
• 組み込みプリセット — solo-work（アイドル3秒、60分）、subagent-workflow（45秒、240分）、team-lead（90秒、480分）、ralph-todo（8秒、480分）、overnight-autonomous（10秒、480分）

オーケストレーターループ

単一セッションの再起動にとどまらず、Orchestrator は高レベルの目標をフェーズごとの計画に変換し、複数のエージェントをまたいで完了まで進めます。これは、idle → planning → approval → executing → verifying → (replanning) → completed と実行されるステートマシンです。

• 計画してから実行 — 目標からフェーズごとの計画を生成し、何かに手を加える前に承認を求めます。却下時にフィードバックを添えると、計画を再生成します
• フェーズごとの検証ゲート — 次のフェーズに進む前に各フェーズを検証します。失敗した場合、Orchestrator は先へ強引に進まず、計画を立て直します
• マルチエージェント実行 — フェーズをチームエージェントやタスクキューに振り分け、単一セッションでは大きすぎる作業を調整します
• クラッシュセーフ — 状態全体が state.json の orchestrator キーに永続化されるため、再起動後も保持されます
• UI または API から実行 — Orchestrator パネル、または POST /api/orchestrator/start → /approve → /status（10 個のエンドポイント）を使用します

設計の全容： docs/orchestrator-loop-architecture.md。

マルチセッションダッシュボード

20 個のセッションを並行して実行し、リアルタイムの xterm.js ターミナル（60fps）、セッションごとのトークン数とコストの追跡、タブベースのナビゲーション、ワンクリック管理で、すべてを把握できます。

タイルグリッド

1 つのウィンドウで、最大 6 個のセッションを横並びで表示し、操作できます。ヘッダーの Tiles をクリックするか、Ctrl+Shift+G を押すと、セッションがライブターミナルのグリッドとして開きます。各タイルでキー入力を受け付け、ヘッダーにはエージェントのロゴ、モデル、状態が表示されます。Tiles を右クリックすると、タイル数を 2、4、6 から選べます。タイルのヘッダーをドラッグすると移動できます。Tiles をもう一度クリックすると、単一セッションに戻ります。デスクトップのみ対応（ウィンドウ幅は約 1180px 以上）。詳しくは、タイルグリッドをご覧ください。

• 重要なセッションを開く：グリッドをまだ配置していない場合、まず作業中のセッション、次に応答待ちのセッション、続いて最近使用したセッションをタイルに配置します。また、現在操作中のセッションは必ず含まれます。
• レイアウトを保持：一度グリッドを配置すると（どのセッションがどこにあるか、空のセル、タイル数、仕切りのサイズ、フォーカス中およびズーム中のタイル）、Tiles ボタンで正確に復元できます。グリッドを開いたままページを再読み込みした場合も同様です。
• タイルアニメーション (オプトイン)：App Settings → Animations → Tile Animations を有効にすると、グリッドを演出付きで開けます。CRT（上部の GIF のように、各タイルが熱線のように点灯します）、Fly from tab、Deal、Beam down、Cascade、Pop、Soft から選べます。視差効果を減らす設定が有効な場合は動きません。
• メインターミナルと同じようにスクロール：マウスホイールでタイル内の全画面表示の Claude の会話をスクロールでき、Codex タイルではトランスクリプトをページ送りできます。Shift+wheel ではタイル内の履歴をスクロールします。
• タイルの分離 (ベータ版、オプトイン)：App Settings → Appearance → Detach Tiles を有効にすると、タイルのヘッダーをブラウザーの外へドラッグして、独立したウィンドウとして開けます。別の Codeman ウィンドウのタイルにドロップすると、そこへ移動します。
• ハンズフリー：ジェスチャーオーバーレイを有効にすると、タイルをつまんで別のタイルへ運んで入れ替えたり、空のセルへ運んで移動したり、タブをグリッドへ運んで追加したりできます。

永続セッション

すべてのセッションは tmux 内で実行されるため、サーバーの再起動、ネットワークの切断、マシンのスリープ後も存続します。起動時に二重の冗長性を備えた自動復旧が行われます。ゴーストセッション検出機能により、孤立した tmux セッションを見つけます。管理対象のセッションには環境タグが付けられるため、エージェントが自分自身のセッションを終了することはありません。

セッションマネージャーとコマンドパレット

Ctrl/Cmd/Alt+K を押すと、ファジー検索対応のセッションパレットが開きます。すべてのセッションを参照を選ぶと、セッションマネージャーが開きます。ここには、Codeman が把握しているすべてのセッション（実行中のセッション、状態とライフサイクル履歴に残っている過去のセッション、Claude のトランスクリプト）が重複なく一覧表示され、各行に最初と直近のプロンプトが表示されます。

• ピン留め：セッションをピン留めすると、リストの先頭に表示されます。ピン留めしたセッションは終了しても残り、軽量な停止中エントリに降格されて、引き続き表示され、再開できます。
• 名前の保持：過去のセッションを再開しても、新しい名前が付けられることなく、元の名前が維持されます。
• デバイス間でのタブ順序：ドラッグして並べ替えたタブはサーバー側に保存されるため、デスクトップからスマートフォンまで、同じ順序で利用できます。

ホスト名に対応したウィンドウタイトル

複数のホスト（ノート PC、開発用マシン、NAS など）で Codeman を実行していますか？ブラウザーのタブタイトルが codeman:<hostname> になるため、クリックしなくても各タブがどのバックエンドを指しているか確認できます。

codeman web                                # codeman:<os.hostname()>
codeman web --title-hostname dev-box       # codeman:dev-box (manual override for noisy hostnames)

タイトルは最初のバイトが配信される時点で HTML に埋め込まれるため、最初の描画から正しく表示され、JavaScript がなくても動作します。同じホスト名のプレフィックスは、タブの点滅形式（⚠️ (N) codeman:<host>）と OS レベルのデスクトップ通知（codeman:<host>: <event>）にも適用されるため、システムの通知センターに届くホスト間のアラートも明確に識別できます。

スマートなトークン管理

タブのアラート

各タブを見れば、状態がひと目でわかります。実行中のセッションには、緑色のステータスドットが表示されます。セッションが停止して入力を待っているときは、タブが黄色になります。リングが点灯し続け、背景が色付きになり、黄色のドットが表示され、その上でゆっくりと明滅します。許可のプロンプトや質問によってエージェントがブロックされているときは、タブがより速く点滅する赤色になります。基本の色合いは点滅中に消えないため、一瞬見ただけでも（スクリーンショットでも）実際の状態を読み取れます。タブを選択している間もリングは表示され、ページを再読み込みすると保留中のアラートがサーバーから再設定されるため、ブロックされたセッションが新しく見えるタブの陰に隠れることはありません。

通知

セッションに対応が必要になったとき、デスクトップにリアルタイムで通知します。permission_prompt と elicitation_dialog は重要度の高い赤いタブの点滅を、idle_prompt は黄色い点滅をトリガーします。通知をクリックすると、該当するセッションに直接移動できます。フックはケースディレクトリごとに自動設定されます。

実行サマリー

セッションタブのグラフアイコンをクリックすると、再起動サイクル、トークンの節目、自動コンパクトのトリガー、アイドル状態と作業中状態の切り替え、フックイベント、エラーなど、発生したすべての出来事のタイムラインを確認できます。

チラつきのないターミナル

ターミナルベースの AI エージェント（Claude Code の Ink、OpenCode の Bubble Tea）は、状態が変わるたびに画面を再描画します。Codeman は 6 層のチラつき防止パイプラインを実装し、すべてのセッションで滑らかな 60fps の出力を実現します。

PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xterm.js (60fps)

その他の機能

• バックグラウンドデーモンとサービスのインストール — codeman web -d は pidfile と ~/.codeman/web.log を使用して、サーバーをデタッチ状態で実行します。また、起動を検証します（サーバーが応答するまでポーリングするため、ポートの競合が成功と誤認されることはありません）。codeman service install は、シェルの PATH を組み込んだ systemd ユーザーユニット（Linux）または LaunchAgent（macOS）を書き込みます。これにより、nvm や Homebrew の node、tmux、claude が実際に見つかります。シークレットがユニットファイルに書き込まれることはありません
• 設定の診断 — App Settings → System → Diagnostics → Run checks を実行すると、サーバー上で codeman doctor が実行され、Node、tmux、すべてのエージェント CLI、オプションのオフィスツールについて、バージョン、パス、インストール方法が表示されます。PATH に加えて、各 CLI の一般的なインストール先（~/.local/bin、~/.npm-global/bin など）も検索するため、PATH が最小限のサービス環境でも、ほとんどのインストールが見つかります。マルチユーザーモードでは管理者専用です。
• セルフアップデート — systemd/launchd の下に git clone してインストールした場合、App Settings → System → Updates からその場でアップデートできます。最新リリースを検出し、変更のあるツリーを自動的に stash して、サービスの再起動中もビルドの進行状況をストリーミングします（npm インストールはアップデート不可と表示されます）
• 下部バーの Git ステータス — デフォルトではオフです（デバイスごとに App Settings → Header & Panels → Bottom bar → Git status で設定）。下部バー右側の小さなインジケーターで、アクティブなセッションのリポジトリの状態をひと目で確認できます。● 3 は未コミットのファイルが 3 つ、↑ 2 は未プッシュのコミットが 2 つ、⚠ はマージの競合あり、✓ はすべてコミットおよびプッシュ済みを表します。クリックすると、ステージ済み、未ステージ、未追跡、競合中のファイル（折りたたまれたフォルダーごとにグループ化。設定をオフにするとフラットな一覧になります）と未プッシュのコミットを表示する、ドラッグ可能なウィンドウが開きます。ファイルをクリックすると差分を表示します（新規ファイルは追加のみ、削除済みファイルは削除のみを表示）。Open file をクリックするとビューアーに移動できます。複数のプロジェクトを含むフォルダーでは、2 階層下までに見つかった各リポジトリが折りたたみ可能なセクションとして表示され、開くまではすべて折りたたまれています。読み取り専用かつオフラインです（Codeman がリポジトリをフェッチしたり変更したりすることはありません）。Docker セッションとリモートセッションでは表示されません。
• GitHub リポジトリをケースとしてクローン — リポジトリの URL を Add Case → Clone Repo に貼り付けると、Codeman が ~/codeman-cases/<name> にクローンし、通常のケースとして登録します。エージェントをすぐに実行できます。入力中に URL を事前確認し（匿名でクローンできるかどうかを知らせ、任意のブランチ／タグ欄にリポジトリの実際のブランチとタグを提示します）、URL からケース名を自動入力します。また、Run ボタンで使用する CLI も選択できます。https:// を介したパブリックリポジトリに対応します。Codeman が認証情報を収集または保存することはありません
• 任意のフォルダーにケースを作成 — Add Case → Create New で Create in a custom folder にチェックを入れ、親フォルダー（Browse も使用できます）と名前を選ぶと、Codeman は ~/codeman-cases ではなく、その場所に新しいケースを作成します。対象は新規または空のフォルダーである必要があります。システムディレクトリ、ホームフォルダー自体、~/.ssh などの認証情報を含むディレクトリ、Codeman 自身のデータフォルダーは指定できません。マルチユーザーモードでは管理者専用です。
• マルチ CLI — セッションごとに Claude Code、OpenCode、Codex、Antigravity、Gemini、Pi、Grok、DeepSeek Harness、OMP、または GitHub Copilot CLI を実行できます。環境変数のプレフィックスは自動的に対象を絞ります（CLAUDE_CODE_* と OPENCODE_*、CODEX_*、ANTIGRAVITY_*、GEMINI_*／GOOGLE_*、PI_*、GROK_*／XAI_*、DSH_*／DEEPSEEK_*、OMP_*、COPILOT_*）。docs/opencode-integration.md、docs/pi-integration.md、docs/grok-integration.md、docs/deepseek-integration.md、docs/omp-integration.md、docs/copilot-integration.md を参照してください
• カスタムモデルエンドポイント (1.29.0 で追加。現時点では HTTP API) — セッションの CLI をネイティブのバックエンドではなく、OpenAI 互換の任意のエンドポイントに接続できます。ローカルの llama.cpp、llama-swap、Ollama、vLLM 環境や、Azure AI Foundry、OpenRouter などのクラウドゲートウェイが対象です。エンドポイントを一度保存し（POST /api/model-endpoints。モデルは /v1/models から検出されます）、セッションに適用すると（POST /api/sessions/:id/custom-model）、CLI はそのエンドポイントを使ってその場で再起動します。Claude、OpenCode、Pi、Grok、OMP で実動作を確認済みです。Codex、Gemini、DeepSeek には文書化されている制約があり、Antigravity には対応する仕組みがありません。次の段階でツールバーの選択機能を追加する予定です。docs/custom-model-endpoints.md を参照してください
• Web タブ — セッションの隣にタブとして、Grafana、Uptime Kuma、Vite の開発サーバー、その他のダッシュボード URL を開けます（Run ドロップダウン → Web / URL → Add URL）。ダッシュボードは Codeman 自身のオリジン経由でプロキシされるため、HTTPS 経由でスマートフォンからアクセスする場合やトンネル経由でも http:// の対象が動作し、シングルページアプリは独自のパスでルーティングされ、再読み込みされたフレームも復旧します。エージェントが出力した localhost のリンクは、自動的に Web タブで開きます。docs/web-tabs.md を参照してください
• Docker セッション — 分離され、セキュリティが強化されたコンテナー内でケースを実行できます。Create New のチェックボックスを 1 つオンにするだけで、適切なデフォルト設定のコンテナーが起動し、その中でエージェントが実行されます。複数のセッションでケースごとに 1 つのコンテナーを共有することも、すでに実行中のコンテナーにケースを接続することもできます。コンテナーとそのワークスペースをポータブルな .tar.gz にエクスポートして、別のマシンに移すこともできます。docs/docker-cases.md を参照してください
• リモート SSH セッション — ケースを別のマシンに接続し、そこで永続的なリモート tmux 内でエージェントを実行できます。SSH 接続が切れてもセッションは維持され、自動再接続し、ホストですでに実行中のセッションを検出して接続することもできます。ファイルのプレビューとダウンロードは同じ SSH 接続経由で行われます。docs/remote-sessions.md を参照してください
• Effort と Ultracode — セッションごとのデフォルトの effort（low～max）を設定するか、ultracode（動的なマルチエージェントワークフロー）を有効にできます。デフォルトは強制されないため、セッション内で /effort を使っていつでも切り替えられます。拡張思考の予算も設定可能です
• 音声入力 — Deepgram Nova-3、または API キー不要の、このマシンの Claude Code ログイン経由でプロンプトを音声入力できます（App Settings → Voice。Web Speech API によるフォールバックあり）。録音の切り替え、自動無音停止、リアルタイムのレベルメーターに対応しています（Ctrl+Shift+V）
• 画像入力 — 画像をセッションに直接貼り付けるか、ドラッグ＆ドロップできます
• ジェスチャー操作 (オプトイン) — MediaPipe の手のトラッキングオーバーレイを使って、セッションウィンドウの移動やボタンのピンチ操作をハンズフリーで行えます。有効にするには CODEMAN_GESTURE=1 を設定し、App Settings → Terminal & Input を開きます
• 複数モニターへの拡張表示 (macOS) — クリック 1 回で、すべてのディスプレイにまたがるように最大化したブラウザーウィンドウを開き、フローティングのエージェント／ジェスチャーパネルを物理的な境界を越えて移動できます
• ファイルビューアーボタン (オプトイン) — タップ 1 回で組み込みのファイルブラウザーパネルを切り替えるヘッダーボタンです。App Settings → Header & Panels → Header buttons で有効にできます
• HTML レポートをページとして開く：エージェントが出力した .html のパス（テストレポート、カバレッジページ、ダッシュボードなど）をクリックすると、File Viewer に実際のページとして表示されます。そのフォルダーにあるスクリプト、スタイル、画像、データファイルも読み込まれます。Page ピルをクリックするとソースに切り替わり、その編集ボタンも表示されます。ページは不透明なオリジンのサンドボックス内で動作するため、Codeman の Cookie の読み取り、Codeman の API の呼び出し、フォルダー外のファイルの読み取りはできません。ネットワークアクセスは許可されるため、CDN から Chart.js やフォントを読み込むダッシュボードも、ディスク上にある場合と同じように動作します。広範囲のフォルダー（/、ホームフォルダー、/tmp）は拒否されるため、レポートには専用のフォルダーを用意してください。ターミナルでクリックした .md のパスもレンダリングして開きます
• クリック可能なパスとフォルダーグリッド：~/… 形式、セッションフォルダーからの相対パス、またはターミナルの複数行にまたがるパスは、ターミナルと Response Viewer でクリックできます。フォルダーも同様で、クリックするとファイル（レンダー画像、スクリーンショット、レポートなど）のグリッドが開き、矢印キーでページを切り替えられます
• OSC 52 クリップボード：セッション内のプログラムが OSC 52 でクリップボードを設定すると（Claude Code の /copy、tmux のヤンク、vim など）、メインターミナルとすべてのタイルで、そのテキストがブラウザーのクリップボードにコピーされます。クリップボードの読み取り要求は拒否され、バッファーを再生してもコピーされません
• MCP サーバーの同期 (オプトイン)：インストール済みの各 CLI（Claude、Codex、Gemini、OpenCode、Antigravity、GitHub Copilot CLI）が持つユーザーレベルの MCP サーバーを、他の CLI の設定ファイルにコピーします。追加のみの動作で、無効にしたサーバーがコピーされることはありません。Preview で先に変更内容を確認でき、変更前のファイルは .codeman-bak として保存されます。App Settings → Agents & CLIs。マルチユーザーモードでは管理者専用です
• CJK／IME 入力 — 中国語／日本語／韓国語の完全な合成入力に対応し、Ctrl キーや Alt キーを使ったナビゲーションキーを CLI に渡します
• 設定のバックアップ — カスタマイズを保持するファイル（設定、CLI オーバーライド、カスタムエンドポイント、Webhook、リンク済みケース、リモートおよび Docker のホスト、保存済みダッシュボード、マルチユーザーモードではアカウント）のタイムスタンプ付きコピーを、起動時と変更時に作成します。デフォルトで有効で、保存先は ~/.codeman/backups/config です。フォルダー、保存する世代数（2～500）、保存期間（日数。0 = 無制限）を設定でき、Settings → System から Back up now と検証済みの Restore を実行できます。保持期間による削除は Codeman が作成したフォルダーに限られ、最新のバックアップは削除されません。Wiki ページを参照してください
• ヘッダーのプラン使用量 — ステータスラインエクスポーターを使った Claude サブスクリプションのリアルタイム使用量（5 時間および週次のウィンドウ）を表示します。Codeman は起動時にこのエクスポーターを claude に渡し、設定ファイルには書き込みません。Codex の上限は Codex 自身のアプリサーバーから取得し、GitHub Copilot の月間プレミアムリクエスト枠も表示します（サーバーは Copilot 自身のサインイントークンを使い、10 分ごとに api.github.com に問い合わせます。Copilot CLI がインストールされ、サインイン済みの場合はデフォルトで有効です。Plan Usage Limits をオフにすると問い合わせも停止します）。デバイスごとに設定され、デスクトップではオン、スマートフォンではオフです
• プロンプトキャッシュの表示：各 Claude セッションでは、プロンプトキャッシュがウォーム状態（cache:until HH:MM）かコールド状態かを、フッター（独自のステータスラインがない場合）と Session Options → Respawn に表示します。キャッシュの再作成コストと、コンパクション後の注記も表示します。表示のみで、再起動後も維持されます
• セッション一覧を自由に表示 — ヘッダーストリップ、フィルターボックス付きの左サイドバー、または作成時刻と状態を含む詳細行がアクティビティ順に並ぶ縦型レールから選べます。スマートフォンのホーム画面とデスクトップのホームレールでは同じ順序が使われます。レールの Search sessions で、すべてのグループを対象に一致するタブに絞り込めます。アラートがあるタブは、名前が一致しなくても表示されます。名前付きのタブグループは折りたたみ、並べ替え、ドラッグに対応しています。グループのメニューには New session があり、エージェントが起動したワーカーは親のすぐ後ろに配置されます（デフォルトでオフの Spawned tabs follow their parent を有効にすると、親の移動に追従します）。Add to Focus で、任意のセクションにあるタブへのショートカットをレール上部にピン留めできます。また、CLI Logos on Tabs はデバイスごとにオフにできます
• ターミナルの外観 — 7 種類のスキン（うち 4 種類はライト）、デバイスごとのフォントファミリーとウェイト（同梱の JetBrains Mono はウェイト 100～800 に対応）、タブ、エージェントウィンドウ、ターミナルペイン、接続線、タイルグリッドのタイルのオプトインアニメーションを利用できます。すべて App Settings → Animations から設定でき、アニメーションを試すラボもあります
• OS 通知とホスト名を含むタイトル — デスクトップ通知とタブタイトルには codeman:<host> がプレフィックスとして付加されるため、複数ホストの環境でも区別できます

分離された Docker セッション

ホスト上で直接実行する代わりに、それぞれのケースを専用の堅牢な Docker コンテナで実行できます。セキュリティ分離、再現可能なツールチェーン、ワンクリックでのポータビリティを実現します。

• ワンクリック — 新しいケース → 新規作成で、🐳 隔離された Docker コンテナで実行にチェックを入れます。Codeman がケースフォルダーを作成し、デフォルト設定でコンテナを起動して、その中でエージェントを開始します。ホスト、イメージ、ネットワークの各フィールドを入力する必要はありません。
• リソーステンプレート — チェックボックスを展開して小 / 中 / 大 / GPUのプリセット（メモリ、CPU、GPU）を選ぶか、独自の設定を指定できます。ディスク容量は可変で、データの流入に合わせてストレージが拡張され、固定の上限はありません。
• ケースごとに共有するコンテナ — 複数のセッションが同じコンテナに対してdocker execを実行できます。1つのセッションを終了しても、ほかのセッションが利用中のコンテナが停止することはありません。
• デフォルトで堅牢 — 非 root、--cap-drop ALL、no-new-privileges、PID とメモリの上限を設定し、--privilegedや Docker ソケットは使用しません。封印済みプロファイル（ホストの認証情報なし、ネットワーク無効）にもワンタップで切り替えられます。
• シームレスな認証、分離された認証情報 — ホストでの Claude / Codex / Antigravity / Gemini / OpenCode / Pi / Grok / OMP のログインは、そのままコンテナ内で利用できます。起動時に認証情報がコピーされ、オンボーディングや信頼確認のプロンプトにも事前に回答されるため、ログインウィザードは表示されません。コンテナは認証情報の独自コピーを保持し、ホストの認証情報ストアに書き戻すことはありません。共有されるのは会話のトランスクリプトのみで、エクスポートに秘密情報が含まれることもありません。
• 実行中のコンテナへの接続 — Docker パネルで既存のコンテナに接続にチェックを入れると、コンテナを新規作成せずにケースを接続できます。Codeman はそのコンテナに対してexecのみを実行し、起動、停止、再起動、削除は行いません。1つの接続済みコンテナを、異なるディレクトリを使う複数のケースで共有できます。また、既存のケースをコピーすると、フォームに同じグループのケースの情報が事前入力されます。マルチユーザーモードでは、コンテナのマウントが起動したユーザーに属するため、管理者のみが利用できます。
• 別のマシンへの移行 — コンテナの環境全体（ツールチェーンとワークスペース）をポータブルな.tar.gzにエクスポートし、移行先でdocker loadを実行して、新しいケースにインポートできます。
• 永続性 — 再起動後に再接続すると、同じ実行中のエージェントに戻ります。コンテナを停止または再起動しても、バインドマウントされたトランスクリプトから会話を再開できます。

前提条件は Docker（または Podman）のみです。エージェントのベースイメージは初回使用時に自動でビルドされ、進行状況は UI に表示されます（または、node scripts/build-agent-image.mjsで事前にビルドできます）。詳しくは、完全ガイドをご覧ください。

リモート SSH セッション

ケースを別のマシンに向けて、同じダッシュボード、モバイル UI、自律機能を使いながら、SSH 経由でそのマシン上でエージェントを実行できます。ノート PC は、リモートホスト上にあるセッションを映す窓にすぎません。

• 設計上、永続的：エージェントはリモートホスト上の専用 tmux セッション内で実行されるため、SSH 接続の切断、ネットワークの変更、ノート PC のスリープによって実行が終了することはありません。再接続すると、同じ進行中の会話に戻ります。
• 自動再接続：バックオフに上限を設けた監視機能が、SSH ペインの切断を検知し、まだ動作しているリモートセッションに静かに再接続します（設定で無効化できます。意図的に終了されたセッションが復元されることはありません）。
• 検出して接続：ホスト上ですでに実行中の codeman-* セッション（そのマシンの Codeman、または別のオペレーターが開始したもの）を一覧表示し、接続できます。所有していないセッションに接続した場合、タブを閉じても切断されるだけで、終了されることはありません。
• セッションの共有：複数のクライアントが異なるウィンドウサイズで同じリモートセッションに接続しても、互いのサイズを制限しません。検出結果にはクライアント数を示す「共有」バッジが表示されます。
• インジェクション対策：すべての ssh コマンドラインは単一のシェルエスケープ処理ビルダーを経由し、ホスト、パス、ID の各フィールドはスキーマで検証されます。
• ファイルにも対応：リモートケースでのプレビュー、ダウンロード、テキストの読み取りは、同じ ssh 接続経由で行われます（realpath と stat によるプローブを 1 回実行した後、cat でストリーミングします。Range によるシークにも対応）。そのため、クリックしたパスのファイルはエージェントが実行されているマシン上で開きます。Codeman ホストにファイルがコピーされることはありません。編集機能や Office プレビューは、誤解を招く 404 ではなく、明確な 400 を返します。
• スクロールバック全体を保持：リモートセッションの履歴を読み込む際は、リモートの tmux から上限付きの SSH 往復 1 回で読み取ります。そのため、再接続やタブの切り替え後もセッションのスクロールバック全体が保持され、履歴とライブ画面の境界で行が失われることはありません。

新しいケース → リモート（ホスト、ユーザー、ID ファイル、任意の踏み台ホスト）から設定します。設計の詳細：docs/remote-sessions.md。

マルチユーザーモード（オプトイン）

信頼できる少人数のチームで 1 つの Codeman を共有し、各メンバーが自分専用のログインとワークスペースを使用できます。デフォルトではオフです。フラグを指定しなければ、何も変わりません。

codeman web --multiuser（または CODEMAN_MULTIUSER=1）で有効にします。最初の管理者を作成したら、CLI またはアプリ設定のユーザータブからユーザーを管理できます。

codeman users add alice --admin      # prompts for a password (or --password-stdin)
codeman users add bob                # a regular user
codeman users list

• ユーザーごとのスペース — 各ユーザーのケースは ~/codeman-users/<name>/cases に保存されます。セッション、ケース、検索、リアルタイムイベントはユーザーごとに分離されます。管理者はすべてを閲覧できます。
• 個別に取り消し可能なログイン — ~/.codeman/users.json に scrypt でハッシュ化したパスワードを保存する、名前付きユーザーを使用します。アカウントはいつでも無効化、リセット（ワンタイムパスワード）、削除できます。管理者の操作は ~/.codeman/admin-audit.jsonl に監査記録として保存されます。
• 一般ユーザー向けのより安全なデフォルト設定 — 管理者以外のユーザーは Claude を --permission-mode auto（Anthropic の分類器による保護モード）で実行します。生のシェルセッション、cron の launchCommand、権限確認のスキップには、ユーザーごとの明示的な許可が必要です。

⚠️ これはワークスペースを分離する機能であり、ユーザー同士をサンドボックス化するものではありません。 すべてのセッションは同じ OS アカウントで実行されるため、意図的に操作するユーザーのエージェントは、他のユーザーのファイルにもアクセスできる可能性があります。確実に分離するには、ユーザーにDocker ケースを割り当てるか、別々の OS アカウントで個別のインスタンスを実行してください。docs/multi-user-plan.md と docs/security-architecture.md のマルチユーザーに関するセクションを参照してください。

リモートアクセス — Cloudflare Tunnel

無料の Cloudflare クイックトンネル を使うと、ポートフォワーディング、DNS、静的 IP を設定せずに、スマートフォンやローカルネットワーク外のデバイスから Codeman にアクセスできます。

Browser (phone/tablet) → Cloudflare Edge (HTTPS) → cloudflared → localhost:3000

前提条件： cloudflared をインストールし、環境変数に CODEMAN_PASSWORD を設定してください。

# Quick start
./scripts/tunnel.sh start      # Start tunnel, prints public URL
./scripts/tunnel.sh url        # Show current URL
./scripts/tunnel.sh stop       # Stop tunnel
./scripts/tunnel.sh status     # Service status + URL

初回実行時に、スクリプトが systemd ユーザーサービスを自動的にインストールします。トンネルの URL はランダムに生成される *.trycloudflare.com アドレスで、トンネルを再起動するたびに変わります。

# Enable as a persistent service
systemctl --user enable codeman-tunnel
loginctl enable-linger $USER

# Or via the Codeman web UI: App Settings → System → Remote access → Cloudflare Tunnel

QR コード認証

スマートフォンのキーボードでパスワードを入力するのは大変です。Codeman は、一時的な使い捨て QR トークンでこの問題を解決します。デスクトップに表示されたコードをスキャンするだけで、スマートフォンがすぐに認証されます。パスワードの入力も、タイピングも、クリップボードも必要ありません。

Desktop displays QR  →  Phone scans  →  GET /q/Xk9mQ3  →  Server validates
→  Token atomically consumed (single-use)  →  Session cookie issued  →  302 to /
→  Desktop notified: "Device authenticated via QR"  →  New QR auto-generated

QR コードを持たず、トンネルの URL だけを知っている人には、通常のパスワード入力画面が表示されます。QR コードは手早く認証するための方法で、パスワードは代替手段です。

仕組み

サーバーは、有効期間の短い使い捨てトークンのプールをローテーションしながら管理します。各トークンは 256 ビットのシークレット（crypto.randomBytes(32)）と、URL パス内で不透明な検索キーとして使われる 6 文字の base62 ショートコードで構成されます。QR コードには https://abc-xyz.trycloudflare.com/q/Xk9mQ3 のような URL が含まれます。ショートコードはシークレットそのものではなく、その参照先を示すものなので、ブラウザーの履歴、Referer ヘッダー、Cloudflare のエッジログを通じてシークレットが漏れることはありません。

サーバーは 60 秒ごとに新しいトークンへ自動的にローテーションします。直前のトークンは、ローテーションと同時にスキャンした場合に備えて 90 秒間有効です。その後は無効になります。各トークンは使い捨てです。スマートフォンで正常にスキャンされた時点でトークンは原子的に消費され、デスクトップの表示用に新しいトークンがすぐに生成されます。

セキュリティ設計

設計には、"Demystifying the (In)Security of QR Code-based Login"（USENIX Security 2025）の知見が反映されています。この研究では、42 件の CVE にまたがる 6 つの重大な設計上の欠陥により、トップ 100 のウェブサイトのうち 47 サイトが QR 認証攻撃に対して脆弱であることが判明しました。Codeman は 6 つすべてに対処しています。

タイミングセーフな検索

短縮コードは Map<shortCode, TokenRecord> に保存されます。検証には Map.get() を使用します。これはハッシュベースの O(1) 検索であり、応答時間から対象文字列に関する情報が漏れることはありません。ホットパスには文字単位の文字列比較が一切ないため、タイミングサイドチャネル攻撃を完全に排除できます。

レート制限（二重レイヤー）

QR 認証には独自のレート制限があり、パスワード認証とは完全に独立しています。

• IP ごと：IP ごとに QR 認証に 10 回失敗すると、429 ブロックが発生します（減衰期間は 15 分）。Basic Auth の失敗回数とは別のカウンターを使うため、パスワードの入力ミスで QR の試行枠が消費されることはありません
• 全体：すべての IP を合計して、1 分あたり 30 回の QR 試行を制限します。分散ブルートフォース攻撃を防ぎます。短縮コードの候補は 62^6 = 568 億通りで、常に有効なコードは約 2 つしかないため、いずれにしてもブルートフォースは計算上実行不可能です

QR コードのサイズ最適化

URL は意図的に短く保たれています（/q/ パス + 6 文字のコードで合計約 53〜56 文字）。これにより、バージョン 5（37x37 モジュール）ではなく QR バージョン 4（33x33 モジュール）を目標にできます。QR コードが小さいほど低価格帯のスマートフォンでもスキャンが速く、最新のデバイスならバージョン 4 を 100〜300ms で読み取れます。/q/ プレフィックスは /qr-auth/ と比べて 7 バイト短く、これだけで QR のバージョンが変わります。

デスクトップでの操作

QR 表示は SSE を通じて 60 秒ごとに自動更新されます。SVG はイベントペイロードに直接埋め込まれるため（約 2〜5KB）、追加の HTTP フェッチは不要で、更新は 50ms 未満です。カウントダウンタイマーで残り時間を表示します。「再生成」ボタンを押すと、既存のトークンをすべて即座に無効化し、新しいトークンを作成します（QR を撮影された疑いがある場合に便利です）。

誰かが QR 経由で認証すると、デスクトップにデバイスの IP とブラウザーを示す通知トーストが表示されます。心当たりがない場合は、ワンクリックですべてのセッションを取り消せます。

脅威への対策

他のプラットフォームとの比較

設計の根拠、セキュリティ分析、実装の詳細については、docs/qr-auth-plan.mdをご覧ください。

セキュリティ

Codeman はデフォルトで --dangerously-skip-permissions を指定してセッションを起動するため、Web UI は設計上、アクセスできるユーザーにとってリモートコード実行の攻撃対象領域となります。セキュリティモデルは、その「ユーザー」が誰かを制御するために存在します。（起動時の権限モードは設定可能です。下記をご覧ください。）最近のセキュリティ強化（v0.9.0 + v0.9.5）により、セルフホスト型の開発ツールを狙う、ブラウザー経由の攻撃経路が塞がれました。セキュリティモデルの全容については、docs/security-architecture.mdをご覧ください。脆弱性を見つけましたか？ 非公開での報告方法と既知の制限事項の一覧については、SECURITY.mdをご覧ください。

ネットワークとアクセス

• デフォルトではループバックにバインド — サーバーバイナリは 127.0.0.1 にバインドされ、同じマシンからのみアクセスできます。そのため、パスワードなしのデフォルト設定でも、すぐに安全に使用できます（ガイド付きインストーラーでは、ネットワークアクセスについて確認し、バインド先とパスワードを設定します）。ループバック以外のホストにバインドする場合、CODEMAN_PASSWORD が設定されていないと、起動はしますが、具体的な対処法を3つ（パスワードを設定する、ループバックにバインドして認証済みトンネルを使う、または --allow-unauthenticated-network で明示的に了承する）示す目立つ警告が表示されます
• 任意の認証と実際のセッション — CODEMAN_USERNAME（デフォルトは admin）／CODEMAN_PASSWORD による HTTP Basic 認証です。認証に成功すると、不透明な256ビットの codeman_session Cookie（randomBytes(32)）が発行されます。これはクライアント側で署名するものではなく、サーバー側で検証されるため、オフラインで偽造できません（有効期間は24時間、自動延長、デバイスコンテキストの監査ログ）
• IPごとのレート制限 — 認証に10回失敗すると、Retry-After を含む 429 が返されます（減衰時間は15分）。攻撃者が同じ IP から大量のリクエストを送っていても、有効な Cookie または正しいパスワードがあれば、すぐに復帰できます。すべてのトンネル通信が同じループバック IP を共有するため、これは重要です。QR 認証には独立したレート制限があります
• 設定可能な権限モード — --dangerously-skip-permissions はデフォルト設定にすぎません。App Settings → Agents & CLIs → Claude → Startup Mode では、新しいセッションを Anthropic の分類器で保護された auto モード（プロンプトが少なく、Claude Code 2.1.207+ が必要）、normal プロンプト、または明示的に許可するツールのリストに切り替えられます。マルチユーザーモードでは、権限を付与されていないユーザーは強制的に auto になり、シェルセッションと権限のスキップにはユーザーごとの明示的な許可が必要です

常時有効なブラウザーのセキュリティ強化（v0.9.5）

以下は、デフォルトのパスワードなしループバックインストールでも、認証前にすべてのリクエストに対して実行されます。

• Host ヘッダーの許可リスト → DNS リバインディングをブロックします。 127.0.0.1 に再バインドされたカスタムドメインは、ハンドラーが実行される前に 403 host not allowed で拒否されます。許可されるもの：localhost、任意の IP リテラル、バインド先ホスト、.ts.net／.trycloudflare.com／.cfargotunnel.com、アクティブな管理対象トンネル、CODEMAN_ALLOWED_HOSTS（カスタムのリバースプロキシドメインをここに追加します。カンマ区切りで、ホスト名の完全一致、またはサブドメインに対する先頭ドット付き .suffix を指定します）
• クロスサイト Origin／CSRF ガード。 状態を変更するメソッド（POST／PUT／PATCH／DELETE）では、Origin が同じ許可リストを通過する必要があります。通過しない場合は 403 cross-site request blocked になります。Origin がない場合は許可されます（そのため、curl、CLI、Claude Code フックは引き続き動作します）。拒否されるのは、Origin が指定されていて他サイトのもの、または不透明な null の場合のみです
• 生の text/plain 本文。 グローバルパーサーは text/plain を JSON として解析しなくなりました。これにより、プリフライトなしのクロスサイト fetch で JSON を書き込みルートに紛れ込ませる、CORS の「シンプルリクエスト」を利用した CSRF の経路を塞ぎます
• WebSocket の Origin 検証。 ターミナルの WS アップグレードでは、同じ Host と Origin のチェックが実行され、失敗時はコード 4003 で切断されます（CSWSH 対策）
• XSS 対策を施したエージェント出力。 AI 由来の文字列（ツール名、コマンド引数、サブエージェントの説明）は、サブエージェント／アクティビティパネルに表示する前に、各挿入箇所で HTML エスケープされます

入力、ファイル、ヘッダー

• スキーマ検証済みの入力 — すべての API ボディを Zod v4 スキーマで検証します。CLAUDE_CODE_* / OPENCODE_* / CODEX_* / ANTIGRAVITY_* / GEMINI_* / GOOGLE_* / PI_* / GROK_* / XAI_* / DSH_* / DEEPSEEK_* / OMP_* / COPILOT_* の環境変数プレフィックス許可リストにより、各 CLI に渡せる設定を制限します。また、CLI のトラフィックをリダイレクトできるキー（ベース URL、設定ディレクトリ）は、管理者以外のユーザーに対して制限されます
• パスの包含制御 — ファイルルートでは境界チェックの前に realpath を実行します（TOCTOU は発生しません）。..、絶対パス、作業ディレクトリの外を指すシンボリックリンクは拒否されます。上限は、テキストプレビューが 10 MB、未加工データとダウンロードが 2 GB（CODEMAN_MAX_DOWNLOAD_BYTES）です（ボディはストリーミングされ、Range リクエストにも応答するため、この上限はメモリ保護ではなく、妥当性を確認するための制限です）。/api/download では機密性の高いパス（.env、*credentials*、~/.ssh/、.aws/credentials）をブロックリストで拒否します。SVG/HTML は octet-stream、nosniff、添付ファイルとして配信されるため、実行されずにダウンロードされます。HTML がレンダリングされる唯一の場所は、File Viewer のページビューです。ファイル自体のフォルダー内に限定された別の /html-view/<capability>/ アドレスで配信され、allow-same-origin を指定しない Content-Security-Policy: sandbox が適用されるため、ページは不透明なオリジンを持ち、Codeman の Cookie を読み取ったり、その API を操作したりできません。非表示のフォルダーと広範囲なルート（/、ホーム、/tmp）は拒否され、ログアウト時にケイパビリティは取り消されます
• セキュリティヘッダー — Content-Security-Policy（default-src 'self'。例外はすべて列挙）、X-Content-Type-Options: nosniff、X-Frame-Options: SAMEORIGIN、HTTPS での HSTS を設定します。CORS は localhost / 127.0.0.1 / ::1 に対してのみ反映されます

サプライチェーンと分離

• 依存関係のバージョン固定と検証 — セキュリティ上重要な間接依存関係は、npm の overrides で修正済みバージョンに固定されます。すべてのコミットと PR でロックファイルの整合性を確認します（すべてのエントリーが sha512 ハッシュ付きで registry.npmjs.org に解決されます）。CI では公開アセットの NUL バイトをスキャンし、node --check で検証します
• 複数インスタンスの分離 — CODEMAN_INSTANCE により、tmux ソケット（-L codeman-<name>）とデータディレクトリ（~/.codeman-<name>）の両方をインスタンスごとに分けるため、2 つのインスタンスが互いの実行中セッションに接続することはありません

モバイルログインでは、1 回限りの 60 秒間有効な QR トークンを使用します。設計の全容については、上記の QR Code Authentication をご覧ください（USENIX Security 2025 の QR ログイン研究で指摘された 6 つの問題すべてに対処しています）。

ターミナル UI（codeman tui）

ターミナルでセッションを管理する全画面ダッシュボードです。同じサーバーのクライアントであるため、Web UI と同じ状態が表示されます。

codeman tui              # the dashboard
codeman tui --list       # numbered session list, then exit (scriptable)
codeman tui 2            # attach straight to session 2 of that list

セッションは、待ち時間の長い順に 対応が必要 → 作業中 → アイドル → 最近 のグループに分けられます。↑↓ / j / k で選択し、1～9 と [ / ] でセッションを切り替え、Enter で tmux ペインに接続します（戻るには F1）。ペイン内では、上部のバーにセッション一覧が表示されたままになり、ペインを離れずに Alt+1～Alt+9 で切り替えられます。y / n / 数字キーで、一覧から保留中の権限ダイアログに応答できます。p で 1 行のプロンプトを送信し、n でセッションを開始して直接開きます。x でセッションを終了し（確認には y）、/ で検索、g で不在時のダイジェストを表示、? でヘルプを開き、q で終了します。幅が 72 列未満の場合はプレビュー領域をなくして 1 列の一覧に切り替わるため、スマートフォンの Termius でも快適に使えます。サーバーが起動していない場合も、接続のみの縮退モードで起動します。

Web UI は引き続きメインのインターフェースです。詳しいガイドは docs/tui.md をご覧ください。

キーボードショートカット

Ctrl キーの操作は、macOS では Cmd キーでも実行できます。

エージェントから Codeman を操作する — プログラムガイド

ブラウザーを使わずに Codeman を制御する AI エージェントや自動化向けです。ワーカーセッションを起動するエージェント、CI ボット、またはCodeman セッション内で実行され、他のセッションを統括する Claude Codeが対象です。UI の操作はすべて HTTP と CLI で行われるため、エージェントでも同じ操作ができます。

エージェントスキル（まずはこちら）

このセクションのすべての内容は、Claude Code、Codex、Gemini CLI、OpenCode、Grok、OMP、その他ほとんどのエージェント CLI が読み込む SKILL.md 形式のエージェントスキル、skills/codeman としても提供されています。一度インストールすれば、API ドキュメントをプロンプトに貼り付ける必要はもうありません。やりたいことを平易な英語で伝えるだけで、すでに Codeman セッション内にいるエージェントがレシピを読み込み、API を操作します。すべてのインストール方法、録画、そして自動で行うこと・行わないことを網羅したガイドはこちらです：Codeman スキル。

ステップ 1：インストールする

codeman skill uninstall [--case <name>] を実行すると、CLI からインストールしたスキルを削除できます（--case を指定した場合、そのケースにある Codeman 管理下のすべてのコピーが対象となり、配置先の CLI ディレクトリは問いません）。自分で作成した skills/codeman には一切触れません。

Step 2: 依頼する

インターフェースはこれだけです。curl も、エンドポイント名も、セッション ID も必要ありません。次のようにそのまま依頼できます。

短い一文で十分です。ここでは、Claude Code のリードに use codeman to start 5 claude workers, one per TODO item と指示すると、5つの実際の Claude Code ワーカーが起動し、タイルグリッドに並んで表示されます。

Step 3: あとは何もしない

エージェントは、自分が起動したすべてのセッションを削除します。作業中にダッシュボードでタブが表示されたり消えたりする様子を確認できます。ワーカーが8つの場合、それぞれに専用のタブが作られ、起動元のリードまでつながる系譜の線が表示されます。

最初から最後までの実際の実行例

あなた： シェルワーカーを3つ起動して、lint／typecheck／フロントエンドの構文チェックを並列で実行し、失敗したものを教えてください。

lint       -> 9f2d8e5f   dispatched
typecheck  -> aff9c691   dispatched     3 tabs appear in the dashboard
syntax     -> be9f1f15   dispatched

lint         DONE_lint_17909      rc=0
typecheck    DONE_typecheck_3409  rc=0   gathered as each one finishes
syntax       DONE_syntax_18501    rc=0

deleted 9f2d8e5f, aff9c691, be9f1f15    tabs disappear

DONE_<task>_<random> という文字列は、スキルの分割マーカーの仕組みです。フックのない shell セッションでもファンアウトが確実に動作するのはこのためです。入力された行には ${M}_17909 が含まれるため、DONE_17909 が現れるのはコマンドの実際の 出力 だけです。分割されていないマーカーを使うと、コマンドが実行される前に、自分が入力したキーのエコーに一致してしまいます。

同梱内容

ここにあるすべてのレシピは稼働中のサーバーで検証済みで、コメントには推測ではなく実測された失敗モードが記録されています。

知っておくべき 2 つのこと

• 自動的に適用範囲を制限します。 Codeman セッション外（CODEMAN_MUX が未設定）では、スキルは動作を拒否し、API URL を推測しないため、グローバルインストールをしても、無関係な Claude Code セッションには何の影響もありません。
• 意図的に慎重な設計です。 指示がない場合、セッションの起動、プロンプトの送信、同じ会話内で自ら作成したセッションの正確な ID を指定した削除だけが許可されます。削除を拒否するフェイルクローズのガードによって、エージェント自身のセッションは削除されません。ケースの削除（コードの実ディレクトリを消去します）、一括終了、再起動／ralph／cron／オーケストレーターの変更、設定の書き込みを行うには、対象を指定して依頼する必要があります。

⚠️ agentSkillEnabled をオフに戻しても、すでに注入されたコピーは削除されません（作成時の一括処理で削除すると、同じワークスペースを共有する他の稼働中セッションからスキルを取り上げてしまいます）。codeman skill uninstall --case <name> を使って、ケースごとに削除してください。

このセクションの残りは手動で操作する方法です。CI ボット、シェルスクリプト、またはスキルに対応していないエージェント向けに、同じ操作を生の HTTP で行う方法を説明します。

Codeman 内で実行されていることを検出する

CLI が Codeman 管理下のセッション内で実行されると、次の環境変数が設定されます。何もハードコーディングせず、これらを読み取ってください。

利用時のルール（POST する前にお読みください）

1. 入力は \r で終わらせてください。 プログラムからの入力はリテラルテキストとして送信され、Enter が実行されるのは、入力にキャリッジリターンが含まれている場合のみです。例：{"input":"run tests\r"}。\r がないと、テキストはセッションのプロンプトに未送信のまま残ります（その状態で wait を組み合わせると、開始されていないターンに対してタイムアウト時間いっぱいまで待機します）。useMux を使う場合、埋め込み改行は保持され、複数行はひとまとまりの貼り付けとして送信されます。そのため、"echo A\necho B\r" はシェルで両方のコマンドを実行します。取り残された Enter を再度押すチェックでは、複数行の貼り付けを確実に認識できません。長い複数行の内容はファイルに保存し、エージェントに読み込むよう指示してください。
2. 入力を冪等にしてください。 POST …/input では、安定した clientId と、セッションごとに単調増加する seq を含めてください。サーバーは重複を排除するため、接続が切れた後に再試行しても、プロンプトが二重に送信されることはありません。
3. 認証。 CODEMAN_PASSWORD が設定されている場合は、HTTP Basic 認証（ユーザー名は admin または CODEMAN_USERNAME）か、codeman_session Cookie を送信してください。デフォルトのループバックインストールでは、パスワードは不要です。Origin ヘッダーがなくても許可されるため、通常の curl が使えます。クロスサイトのブラウザーオリジンは拒否されます（CSRF ガード）。⚠️ 401 は JSON エンベロープではなく、文字列 Unauthorized のみを返します。そのため、これを jq にパイプすると解析エラーになり、失敗の内容が表示されません。解析の前にステータスを確認してください。
4. レスポンスエンベロープ。 ほとんどのエンドポイントは { "success": true, "data": … } を返します（エラーの場合は { "success": false, "error", "errorCode" }）。一部のレガシーな GET は本文をそのまま返すため、両方に対応してください（body.data ?? body）。
5. /api/v1/* は /api/* の安定したエイリアスです。
6. ポーリングではなく待機を使い、タイムアウトをエラーとして扱わないでください。 待機エンドポイントは、時間内に何も起きなかった場合でも HTTP 200 と wait.timedOut: true を返します。トンネルではアイドル接続が切断されるため、一度に長時間待機するのではなく、短い待機（デフォルトは 60s）を繰り返してください。wait.timeoutMs には、上限適用後にサーバーが実際に適用したタイムアウト（上限は 600s）が示されます。
7. stop を出力するのは claude と deepseek セッションのみです。codex は blocked も出力します。 これらはフックから送られます（Claude Code 独自のフックと DeepSeek Harness のステータスブリッジ）。ただし codex の blocked は例外で、承認、質問、または信頼確認のダイアログが表示されている間、Codeman が画面から読み取ります（ターミナルで回答してください）。shell とその他の外部 CLI（opencode/gemini/antigravity/pi/grok/omp）が受け付けるのは idle、working、exit のみで、codex では blocked も受け付けます。これらに対して stop を明示的に要求すると 400 になります。until を省略すれば、常に安全です。⚠️ shell セッションでは、idle は起動時に一度だけ発生し、その後は発生しません。そのため、送信して待機してもタイムアウトするだけです。フックのないセッションは、wait-output マーカーを使って同期してください。
8. 「準備完了」を知らせるものはないため、明示的に待機してください。 新しいセッションは、PID が存在するまで {"signal":"exit","immediate":true} を返します（これはクラッシュではなく、未起動を意味します）。その後、新しいケースの claude ワーカーは CLI の信頼確認ダイアログで停止します。そこでプロンプトを入力すると、約 2 秒後に idle で待機が解決します。これはターンが完了したように見えますが、テキストはダイアログ内で止まったままです。これを避ける手順は、以下のレシピ 2b にあります。

レシピ

# CODEMAN_API_URL is auto-set inside every Codeman session, correct scheme included.
# The fallback below fits a stock install; on a --https install set the https:// URL
# yourself and add -k to each curl (self-signed cert).
API="${CODEMAN_API_URL:-http://127.0.0.1:3000}"
# (add  -u admin:"$CODEMAN_PASSWORD"  to each call if a password is set)

# 1. See what's running
curl -s "$API/api/sessions" | jq '.data // .'

# 2. Spin up a worker session (a "case" = named working dir)
curl -s -X POST "$API/api/quick-start" \
  -H 'Content-Type: application/json' \
  -d '{"caseName":"refactor-auth","mode":"claude","effort":"high"}' | jq

# 2b. Wait until that worker is actually READY (see rule 8): composer marker first,
#     first-run trust dialog only as the fallback. (Probing trust first and sending
#     a blind Enter misfires on re-runs: the dialog text stays in the buffer forever,
#     so the probe matches stale text and the Enter lands in a ready composer.)
#     Match single tokens: TUI text can reach the matcher without its spaces.
until [ "$(curl -s "$API/api/sessions/$SID" | jq '.data.pid')" != null ]; do sleep 1; done
R=$(curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=bypass' \
      --data-urlencode 'from=buffer' --data-urlencode 'timeout=5000')
if ! jq -e '.data.wait.matched' <<<"$R" >/dev/null; then
  T=$(curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=trust' \
        --data-urlencode 'from=buffer' --data-urlencode 'timeout=2000')
  jq -e '.data.wait.matched' <<<"$T" >/dev/null && \
    curl -s -X POST "$API/api/sessions/$SID/input" -H 'Content-Type: application/json' \
      -d '{"input":"\r","useMux":true}'        # accept the first-run trust dialog
  curl -sG "$API/api/sessions/$SID/wait-output" --data-urlencode 'match=bypass' \
    --data-urlencode 'from=buffer' --data-urlencode 'timeout=45000' >/dev/null
fi

# 3. Send a prompt into a session (exactly-once: clientId + seq)
curl -s -X POST "$API/api/sessions/$SID/input" \
  -H 'Content-Type: application/json' \
  -d '{"input":"Run the test suite and summarize failures\r","useMux":true,"clientId":"agent-1","seq":1}'

# 4. Send a prompt and BLOCK until that turn is done (registers the wait before
#    writing, so it can't answer with the previous turn's idle state)
curl -s -X POST "$API/api/sessions/$SID/input" \
  -H 'Content-Type: application/json' \
  -d '{"input":"Run the test suite and summarize failures\r","useMux":true,
       "clientId":"agent-1","seq":2,"wait":"stop,exit","waitTimeout":60000}' \
  | jq '.data.wait'      # -> {"signal":"stop","timedOut":false,"waitedMs":41230,...}
#    (`stop` is the definitive end-of-turn hook. Adding `idle` makes it resolve on a
#     spinner pause too, and on anything that redraws a ❯ prompt — like a dialog.)

# 4b. Timed out? That's a 200, not a failure. Loop over short waits.
curl -s "$API/api/sessions/$SID/wait?until=stop,exit&timeout=60000" | jq '.data.wait'

# 4c. Or wait for a marker in the output (works for shell sessions too).
#     ⚠️ Unique per call (tmux repaints replay old screen text), and SPLIT so the
#     typed line never contains it: your own keystrokes echo into the output
#     stream, so an unsplit marker matches before the command has run. from=buffer
#     catches a marker that printed before the wait landed.
N=$RANDOM
curl -s -X POST "$API/api/sessions/$SID/input" -H 'Content-Type: application/json' \
  -d "{\"input\":\"M=DONE; npm test; echo \${M}_$N rc=\$?\r\",\"useMux\":true}"
curl -sG "$API/api/sessions/$SID/wait-output" \
  --data-urlencode "match=DONE_$N" --data-urlencode 'from=buffer' \
  --data-urlencode 'timeout=60000' | jq '.data.wait'

# 5. Read the answer. claude / codex / deepseek sessions have last-response: it comes
#    from the transcript, not the screen, so no TUI frames or repaint noise.
#    ⚠️ Poll rather than read once: the transcript lands slightly after the stop
#    signal, so a read right after send-and-wait returns often comes back empty.
for _ in $(seq 1 10); do
  TXT=$(curl -s "$API/api/sessions/$SID/last-response" | jq -r '.data.text')
  [ -n "$TXT" ] && break; sleep 1
done
printf '%s\n' "$TXT"

# 5b. Other modes (shell/opencode/gemini/antigravity/pi/grok/omp/copilot) have no transcript:
#     read the terminal. ⚠️ Use terminal?tail=, NOT /output: the latter's textOutput
#     is empty for every tmux-backed (i.e. every interactive) session. tail counts
#     BYTES, and what comes back is terminal data, ANSI included.
curl -s "$API/api/sessions/$SID/terminal?tail=8000" | jq -r '.data.terminalBuffer'

# 6. Stream live events (session output, agent activity, status)
curl -sN "$API/api/events"          # Server-Sent Events

# 7. Schedule recurring work (cron-style job)
curl -s -X POST "$API/api/cron/jobs" \
  -H 'Content-Type: application/json' \
  -d '{"name":"nightly-deps","agentType":"claude","workingDir":"/home/me/proj",
       "promptMode":"inline_text","promptText":"Update dependencies and open a PR",
       "inputMode":"typed","scheduleType":"daily","dailyTime":"03:00",
       "enabled":true,"concurrencyPolicy":"warn_only"}' | jq

# 8. Inspect background sub-agents and their transcripts
curl -s "$API/api/subagents" | jq '.data // .'
curl -s "$API/api/subagents/$AID/transcript" | jq -r '.data // .'

# 9. Whole-system snapshot (sessions, settings, respawn, stats)
curl -s "$API/api/status" | jq

または、同梱の CLI を使う

同じ操作をコマンドとして利用できます（codeman <cmd>。括弧内はエイリアスです）。セッション内のシェルツールから実行する場合に便利です。

codeman session start -d /path/to/repo   # (s)  start a session
codeman session list                     #      list sessions
codeman session logs <id>                #      tail output
codeman task add "fix the failing test"  # (t)  queue a task
codeman attach <path>                    #      show an attachment card for a local file
codeman tui --list                       #      numbered session list (plain text when piped)
codeman tui 3                            #      attach to session 3 of that list

codeman agent — すべての CLI モードで使えるセッション間の動詞

上記のスキルは、セッションごとに Codeman が用意する前文から curl と jq を使って API を操作します。対応できない環境（pi または shell セッション、jq のないマシン）でも、同じ環境変数（CODEMAN_MUX=1、CODEMAN_SESSION_ID、CODEMAN_API_URL）がすべてのペインにエクスポートされているため、codeman agent を使って同じ動詞をコマンドとして実行できます。これはAPIに記載されたエンドポイントを利用する薄いクライアントです。新しいルートやトランスポートは追加せず、認証と所有権の扱いも変わりません。ケースの AGENTS.md に「他のセッション：codeman agent --help」と1行記載するだけで十分です。

codeman agent ls                                          # sessions; * marks this one
SID=$(codeman agent spawn scratch-1 --mode claude)        # quick-start + wait for the composer where the mode has a ready mark
codeman agent send "$SID" 'review src/, then say DONE' --until stop,exit --timeout 300000   # --wait = default signal set
codeman agent read "$SID"                                 # last answer (as the server reads it for that mode)
codeman agent read "$SID" --tail 3000                     # terminal tail, ANSI stripped (every mode)
codeman agent send "$SID" 'run the tests, then print WORKDONE followed by _4711'   # hook-less modes (opencode, pi, …): ask for the marker in halves …
codeman agent wait "$SID" --match WORKDONE_4711           # … and wait on the joined form, which the prompt's echo never contains
codeman agent interrupt "$SID"                            # a bare ESC, conversation intact
codeman agent rm "$SID"                                   # any session except this one

コマンドがドキュメントで説明するのではなく、実際に適用するルール：Codeman セッション外では実行を拒否し、URL を推測することはありません。send が送信するのは印字可能なテキストと Enter のみです（Ctrl+C などの制御バイトは opencode では app_exit です。ESC は interrupt 専用で、Enter は追加されません）。rm は空の ID、本人の ID だと証明できない ID、またはどちらかの方向で一致するプレフィックスを拒否します。ID には ls が出力する8文字のプレフィックスを使えます（リストを通じて解決します。プレフィックスが曖昧な場合は拒否され、8文字未満のものはすべての動詞で拒否されます）。- で始まるプロンプトは -- の後に指定します（send "$SID" -- "- fix the bug"）。送信したプロンプトのエコーも出力されます。プロンプト内に --match のマーカーがそのまま含まれている場合、ワーカーが何もする前に即座に一致するため、プロンプトではマーカーを分割して指定します。ホストがスリープ中のリモートセッションに対して、結果を待たない send を実行すると、buffered（Codeman がホストを起動し、ペインが復帰した後にプロンプトを入力します）または dropped（ウェイクバッファーの上限を超えており、何も入力されません。終了コードは 1）が返ります。終了コード：0 は配信／一致／シグナル、1 はエラー、2 はタイムアウト、3 はワーカーが終了したか、応答がないまま待機が終了した場合（delivered:false、ended:true）、4 は拒否を表します。spawn は標準出力に ID のみを出力し（説明文は標準エラーに出力します）、SID=$(…) で ID だけを正確に取得できます。すべての動詞で --json はエンベロープの data を出力します。フックシグナルのないモードで --until stop を指定すると、サーバーからの 400 エラーがそのまま渡されます。その場合はスキルと同様に、マーカーパス（--match）が応答になります。

MCP サーバー（codeman mcp）：任意の MCP クライアントから Codeman を操作

codeman mcp は、stdio 上で動作するModel Context Protocolサーバーです。そのため、任意の MCP クライアント（Claude Code、Claude Desktop、Codex、Gemini CLI、Cursor、……）から、Codeman の内外を問わず、インストール済みの任意のエージェント CLI で Codeman セッションを開始し、プロンプトを送信し、完了を待ち、回答を読み取り、後片付けできます。codeman agent と同様に、これは HTTP API のクライアントです。新しいルートは追加されず、認証と所有権の扱いも変わりません。

# Claude Code
claude mcp add codeman -e CODEMAN_API_URL=https://127.0.0.1:3000 -- codeman mcp

{
  "mcpServers": {
    "codeman": {
      "command": "codeman",
      "args": ["mcp"],
      "env": { "CODEMAN_API_URL": "https://127.0.0.1:3000" }
    }
  }
}

# Codex (~/.codex/config.toml): raise the 60 s default tool timeout for long waits
[mcp_servers.codeman]
command = "codeman"
args = ["mcp"]
env = { CODEMAN_API_URL = "https://127.0.0.1:3000" }
env_vars = ["CODEMAN_MUX", "CODEMAN_SESSION_ID"]  # Codex passes MCP servers a minimal env; these let it know the Codeman session it runs in
tool_timeout_sec = 120

JSON 形式は Claude Desktop、Cursor、Gemini CLI が使用する形式です。サーバーにパスワードが設定されている場合は、env に "CODEMAN_PASSWORD" を追加してください（または、データディレクトリの .env を読み込ませてください）。インストーラーを使わずに Git チェックアウトを実行していて、codeman コマンドが PATH にない場合は、node /path/to/Codeman/dist/index.js mcp を使用してください。

サーバーが文書で説明するのではなく、適用するルールは次のとおりです。

• サーバーを推測して選ぶことはありません。 URL は CODEMAN_API_URL または --url から取得します。どちらも指定されていない場合でも起動してツール一覧を表示し、各呼び出しで設定方法を案内します。
• 操作対象はサーバー自身のセッションに限られます。 プロンプト送信、中断、削除の対象は、このサーバーが開始したセッション（Codeman セッション内で実行する場合は、そのセッション自身のワーカー）に限られます。一覧表示、読み取り、待機はすべてのセッションで利用できます。codeman mcp --allow-any-session を指定すると、既存のタブをアシスタントに操作させたいユーザー向けに、この制限が解除されます。実行中のセッション自体を操作することはありません。
• 待機時間はクライアントに合わせています。 待機時間のデフォルトは 45 秒（Codex はデフォルトで MCP ツールを 60 秒で打ち切ります）で、上限は 600 秒です。timed_out / still_working が返された場合は、もう一度呼び出してください。
• 両方のプロトコル世代に対応しています。 2026-07-28 のリビジョン（リクエストごとの _meta、server/discover）と、2024-11-05 から 2025-11-25 までの initialize ハンドシェイクに応答します。

フック（Codeman に 戻る イベント）

Codeman は Claude Code のフックを登録し、POST /api/hook-event（permission_prompt、idle_prompt、stop、task_completed、……）を送信することで、ダッシュボードがリアルタイムに反応できるようにします。このエンドポイントはループバックでは認証が免除されますが、管理対象のトンネル経由では X-Codeman-Hook-Secret ヘッダーが必要です（$CODEMAN_HOOK_SECRET_FILE から読み取ってください）。通常、これは手動で呼び出しません。Codeman が設定します。しかし、自律性レイヤーがエージェントの動作を「認識」する仕組みです。

エンドポイント一覧とリクエスト／レスポンスの形式は以下のとおりです。

API

Fastify 上の REST。25 個のルートモジュールに約 230 個のハンドラーを備え、SSE ストリームと WebSocket ターミナルチャンネルもあります。すべてのレスポンスで ApiResponse<T> エンベロープ（{success, data} / {success, error, errorCode}）を使用します。/api/v1/* は安定したエイリアスです。代表的な一部を以下に示します。

セッション

再起動

オーケストレーター

Cron（スケジュール済みジョブ）

サブエージェント

システム

Codeman を基盤に何かを構築していますか？ docs/extending-codeman.md は統合ガイドです。独自の UI をタブとして表示する方法、SSE イベントストリームを購読してエージェントがユーザーの対応を必要とするときに反応する方法、スクリプトから Codeman を操作する方法、そして始める前に知っておくべき注意点を説明しています。Codeman にプラグインの実行環境がないのは意図的です。そのため、統合は独自のプロセスから HTTP で通信するだけです。

アーキテクチャ

flowchart TB
    subgraph Codeman["CODEMAN"]
        subgraph Frontend["Frontend Layer"]
            UI["Web UI<br/><small>xterm.js + Agent Windows</small>"]
            API["REST API<br/><small>Fastify</small>"]
            SSE["SSE Events<br/><small>/api/events</small>"]
        end

        subgraph Core["Core Layer"]
            SM["Session Manager"]
            S1["Session (PTY)"]
            S2["Session (PTY)"]
            RC["Respawn Controller"]
            ORC["Orchestrator Loop"]
        end

        subgraph Detection["Detection Layer"]
            SW["Subagent Watcher<br/><small>~/.claude/projects/*/subagents</small>"]
            TW["Team Watcher<br/><small>~/.claude/teams/*</small>"]
        end

        subgraph Persistence["Persistence Layer"]
            SCR["Mux Manager<br/><small>(tmux)</small>"]
            SS["State Store<br/><small>state.json</small>"]
        end

        subgraph External["External"]
            CLI["AI CLI<br/><small>Claude Code / OpenCode / Codex / Antigravity / Gemini / Pi / Grok / DeepSeek / OMP / GitHub Copilot</small>"]
            BG["Background Agents<br/><small>(Task tool)</small>"]
        end
    end

    UI <--> API
    API <--> SSE
    API --> SM
    SM --> S1
    SM --> S2
    SM --> RC
    SM --> ORC
    SM --> SS
    S1 --> SCR
    S2 --> SCR
    RC --> SCR
    ORC --> SCR
    SCR --> CLI
    SW --> BG
    SW --> SSE
    TW --> SSE

開発

npm install
npx tsx src/index.ts web    # Dev mode
npm run build               # Production build
npm test                    # Run tests (same suite CI runs; browser/mobile/perf suites have their own commands)

詳細なドキュメントについては、CLAUDE.md を参照してください。

コミュニティ

質問、セットアップのサポート、アイデアについては、GitHub Discussions をご利用ください。Q&A セクションでは、よくある質問（スマートフォンからのアクセス、夜間の実行、更新など）に回答しています。ロードマップは Ideas で決定されます。バグは issues へ報告してください。通常、報告には 1 日以内に返信があり、各リリースでは報告者と貢献者の名前が記載されます。貢献を希望される場合は、CONTRIBUTING.md をご覧ください。スキン、翻訳、ドキュメントは初めての PR に最適です。大きな機能は Discussion から始めましょう。自慢の環境があれば、Show and tell に投稿してください。

コードベースの品質

コードベースでは7段階にわたる包括的なリファクタリングを実施し、巨大なオブジェクトを解消し、設定を一元化して、モジュール型アーキテクチャを確立しました。

詳細：docs/archive/code-structure-findings.md

公開済みパッケージ

xterm-zerolag-input

xterm.js 用の、キー入力に即座に反応するオーバーレイです。入力した文字をピクセル単位で正確な DOM オーバーレイとしてすぐに描画することで、高 RTT 接続時に感じる入力レイテンシーを解消します。依存関係ゼロ、gzip 圧縮時6.1 kB、設定可能なプロンプト検出、CJK／絵文字の全角文字サポート、238件のテストを備えた完全なステートマシンを提供します。

npm install xterm-zerolag-input

ドキュメント全文

バージョニング

Codeman は SemVer に準拠しています。バージョン番号が実際に保証する内容と、内部仕様（HTTP/SSE API、ディスク上の状態、実験的機能）として扱われる内容については、docs/versioning-policy.md に明記されています。HTTP API に対するスクリプトを作成する場合は、バージョンを正確に指定してください。

ライセンス

MIT — LICENSE を参照してください。

セッションを追跡し、エージェントを可視化し、再起動を制御します。眠っている間も実行し続けられます。

Codeman が時間の節約に役立った場合は、スターを付けていただくと、ほかの人にも見つけてもらいやすくなります。
バグ報告や機能のアイデアは、Issues でお寄せください。