Skip to content

README.md

Latest commit

 

History

History
341 lines (244 loc) · 16.8 KB

README.md

File metadata and controls

341 lines (244 loc) · 16.8 KB

CommandMate

GitHub Stars npm version npm downloads license CI Status: Beta

English | 日本語

CommandMate デスクトップデモ

ターミナルをさばくな。エージェント CLI をオーケストレーションしよう。

CommandMate は、エージェント CLI のローカルコントロールプレーンです。

npx commandmate

インストールから最初のセッションまで 60 秒。 macOS / Linux · Node.js v20+ · npm · git · tmux · openssl

CommandMate は、既存のエージェント CLI の上にオーケストレーションと可視性を追加します。 tmux、Git worktree、ターミナルを置き換えません。大規模な管理を容易にします。

CommandMate モバイルデモ

デスクトップでもモバイルでも使えます。あらゆるブラウザからセッションを監視・操作できます。

このワークフローに共感したら、ぜひリポジトリに Star をお願いします。

主な機能

機能 できること なぜ重要か
Git Worktree セッション worktree ごとに独立したセッション、並列実行 複数の Issue が干渉なく同時に進む
マルチエージェント対応 Issue ごとに Claude Code、Codex、Gemini、ローカルモデルを選択 タスクに最適なエージェントを使い分け
Auto Yes モード 確認なしでエージェントが動き続ける 信頼できるワークフロー向けのオプショナル自動実行モード
Web UI（デスクトップ & モバイル） あらゆるブラウザからセッションを操作 デスクからでもスマホからでも監視・指示が可能
ファイルビューワ & Markdown エディタ ブラウザからファイルの閲覧・編集 IDE を開かずにコード確認や AI への指示更新
スクリーンショット指示 プロンプトに画像を添付 バグ画面を撮影 →「これ直して」— エージェントが画像を認識
スケジュール実行 CMATE.md に cron 式を定義して自動実行 毎朝レビュー、毎晩テスト — エージェントが定期的に働く
トークン認証 SHA-256 ハッシュ + HTTPS + レート制限 安全なリモートアクセス — 認証情報の漏洩なし、総当たり攻撃を防止

ユースケース

シナリオ CommandMate でできること
Issue 並列開発 複数の Issue を別々の worktree で同時に進行、各セッションに専用エージェント
Issue の精緻化 Issue を定義し、AI が不足を補い、コードを書く前に方向性を確認
夜間自律実行 スケジュール実行で Issue をキュー — 朝に進捗を確認
モバイルレビュー AI が生成した変更をスマホから確認・方向修正
ビジュアルバグ修正 スマホで UI バグを撮影 →「これ直して」で送信

セキュリティ

100% ローカル実行。外部サーバーなし、クラウド中継なし、アカウント登録不要。ネットワーク通信は Claude CLI 自体の API 呼び出しのみ。

  • フルオープンソース（MIT License）
  • ローカルデータベース、ローカルセッション
  • リモートアクセスはトンネリングサービス（Cloudflare Tunnel、ngrok、Pinggy）、VPN、または認証付きリバースプロキシを推奨

詳細はセキュリティガイドと Trust & Safety を参照してください。

仕組み

flowchart LR
    A["ブラウザ / スマホ"] -->|HTTP| B["CommandMate Server"]
    B --> C["Session Manager"]
    C -->|"spawn / attach"| D["tmux sessions\n(worktree ごと)"]
    D --> E["Claude Code CLI"]
    C <-->|"read / write"| F[("Local DB\n& State")]
Loading

Git worktree ごとに専用の tmux セッションが割り当てられるため、複数タスクを干渉なく並列実行できます。

Quick Start（詳細） 
# インストール & 起動をワンコマンドで
npx commandmate

# またはグローバルインストール
npm install -g commandmate
commandmate init
commandmate start --daemon

ブラウザで http://localhost:3000 にアクセスしてください。

詳しくは CLI セットアップガイド を参照してください。

CLI コマンド

基本

コマンド 説明
commandmate init 初期設定（対話形式）
commandmate init --defaults 初期設定（デフォルト値）
commandmate init --force 既存設定を上書き
commandmate start サーバー起動（フォアグラウンド）
commandmate start --daemon バックグラウンド起動
commandmate start --dev 開発モードで起動
commandmate start -p 3001 ポート指定で起動
commandmate stop サーバー停止
commandmate stop --force 強制停止（SIGKILL）
commandmate status 状態確認

Worktree 並列開発

Issue/worktree ごとにサーバーを分離起動し、自動ポート割当で並列開発が可能です。

コマンド 説明
commandmate start --issue 123 Issue #123 用サーバー起動
commandmate start --issue 123 --auto-port 自動ポート割当で起動
commandmate start --issue 123 -p 3123 特定ポートで起動
commandmate stop --issue 123 Issue #123 用サーバー停止
commandmate status --issue 123 Issue #123 用サーバー状態確認
commandmate status --all 全サーバー状態確認

GitHub Issue 管理

gh CLI のインストールが必要です。

コマンド 説明
commandmate issue create Issue を作成
commandmate issue create --bug バグ報告テンプレートで作成
commandmate issue create --feature 機能リクエストテンプレートで作成
commandmate issue create --question 質問テンプレートで作成
commandmate issue create --title <title> タイトルを指定
commandmate issue create --body <body> 本文を指定
commandmate issue create --labels <labels> ラベルを追加（カンマ区切り）
commandmate issue search <query> Issue を検索
commandmate issue list Issue 一覧

ドキュメント参照

コマンド 説明
commandmate docs ドキュメント表示
commandmate docs -s <section> 特定セクションを表示
commandmate docs -q <query> ドキュメント検索
commandmate docs --all 全セクション一覧

全オプションは commandmate --help で確認できます。

トラブルシューティング & FAQ

Claude CLI が見つからない / パスが変わった？

Claude CLI の npm 版とスタンドアロン版を切り替えるとパスが変わることがあります。CommandMate は次のセッション起動時に自動検出します。カスタムパスを設定するには .env に CLAUDE_PATH=/path/to/claude を追加してください。

ポート競合？

commandmate start -p 3001

セッションが固まっている / 応答がない？

tmux セッションを直接確認できます。CommandMate は mcbd-{ツール名}-{worktree名} の形式でセッションを管理しています：

# CommandMate が管理しているセッション一覧を確認
tmux list-sessions | grep mcbd

# 特定セッションの出力を確認（アタッチせずに）
tmux capture-pane -t "mcbd-claude-feature-123" -p

# セッションにアタッチして確認（detach は Ctrl+b → d）
tmux attach -t "mcbd-claude-feature-123"

# 壊れたセッションを手動で削除
tmux kill-session -t "mcbd-claude-feature-123"

注意： アタッチ中にセッション内で直接入力すると、CommandMate のセッション管理と干渉する可能性があります。Ctrl+b → d で detach し、CommandMate UI から操作してください。

Claude Code 内から起動するとセッション開始に失敗する？

Claude Code は CLAUDECODE=1 を設定してネストを防止しています。CommandMate は自動で除去しますが、問題が続く場合は tmux set-environment -g -u CLAUDECODE を実行してください。

FAQ

Q: スマホからどうやってアクセスする？ A: CommandMate は PC 上で Web サーバーを起動します。スマホと PC が同じネットワーク（Wi-Fi）にいる状態で、commandmate init で外部アクセスを有効にすると CM_BIND=0.0.0.0 が設定されます。スマホのブラウザで http://<PCのIPアドレス>:3000 を開いてください。

Q: 外出先からアクセスできる？ A: はい。トンネリングサービスを使えば、ルーターのポート開放なしにローカルサーバーを安全に公開できます：

  • Cloudflare Tunnel — 無料、Cloudflare アカウントが必要
  • ngrok — 無料枠あり、セットアップが簡単
  • Pinggy — サインアップ不要、SSH ベースのシンプルなトンネル

VPN や認証付きリバースプロキシ（Basic 認証、OIDC 等）も利用可能です。認証なしでインターネットに直接公開しないでください。

Q: iPhone / Android で使える？ A: はい。CommandMate の Web UI はレスポンシブ対応で、Safari・Chrome などのモバイルブラウザで動作します。アプリのインストールは不要です。

Q: tmux は必須？ A: CommandMate は内部で tmux を使用して CLI セッションを管理しています。ユーザーが tmux を直接操作する必要はありません。

Q: Claude Code の権限はどうなる？ A: Claude Code 自体の権限設定がそのまま適用されます。本ツールが権限を拡張することはありません。詳しくは Trust & Safety を参照してください。

Q: 複数人で使える？ A: 現時点では個人利用を想定しています。複数人での同時利用は未対応です。

開発者向けセットアップ

コントリビューターや開発環境を構築する場合：

git clone https://github.com/Kewton/CommandMate.git
cd CommandMate
./scripts/setup.sh  # 依存チェック、環境設定、ビルド、起動まで自動実行

手動セットアップ（カスタマイズしたい場合）

git clone https://github.com/Kewton/CommandMate.git
cd CommandMate
./scripts/preflight-check.sh          # 依存チェック
npm install
./scripts/setup-env.sh                # 対話式で .env を生成
npm run db:init
npm run build
npm start

Note: ./scripts/* スクリプトは開発環境でのみ使用可能です。グローバルインストール（npm install -g）では commandmate CLI を使用してください。

競合比較
機能 CommandMate Remote Control（公式） Happy Coder claude-squad Omnara
Auto Yes モード あり なし なし あり（TUI のみ） なし
Git Worktree 管理 あり なし なし あり（TUI のみ） なし
並列セッション あり なし（1つのみ） あり あり なし
モバイル Web UI あり あり（claude.ai） あり なし あり
ファイルビューワ あり なし なし なし なし
Markdown エディタ あり なし なし なし なし
スクリーンショット指示 あり なし なし 不可能 なし
スケジュール実行 あり なし なし なし なし
PC を閉じても継続 あり（デーモン） なし（ターミナル必須） あり あり あり
トークン認証 あり N/A（Anthropic アカウント） N/A（アプリ） なし N/A（クラウド）
無料 / OSS あり Pro/Max 必須 無料+有料 あり $20/月
完全ローカル実行 あり Anthropic API 経由 サーバー経由 あり クラウドフォールバック

オプショナルワークフローレイヤー

チームでより構造的な開発を行いたい場合、CommandMate は Issue の精査、設計レビュー、 計画立案、実装、受け入れチェックの標準化もサポートします。 これらのワークフローは同じ CLI セッションと worktree の上に構築されます。利用は任意です。

CommandMate は、ファイルを直接編集する時間よりも、Issue を定義し、方向性を確認し、コーディングエージェントの成果を受け入れる時間の方が長い開発者のために作られています。以下のコマンドは、そのワークフローを再現可能なプロセスに変えます。

Issue 定義 → AI で補強 → 方向性レビュー → 計画生成 → エージェントが実行
ステップ コマンド 実行内容
Issue を補強 /issue-enhance AI が不足情報を質問し、Issue を補完
Issue レビュー /multi-stage-issue-review 多段階レビュー（整合性・影響範囲）と指摘の自動対応
設計レビュー /multi-stage-design-review 4 段階レビュー（通常 → 整合性 → 影響分析 → セキュリティ）
作業計画 /work-plan タスク分割と依存関係を生成
TDD 実装 /tdd-impl Red-Green-Refactor サイクルを自動実行
受入テスト /acceptance-test Issue の受入基準を検証
PR 作成 /create-pr タイトル・説明・ラベルを自動生成
開発（一括） /pm-auto-dev TDD 実装 → 受入テスト → リファクタリング → 進捗レポート
Issue → 実装（一括） /pm-auto-issue2dev Issue レビュー → 設計レビュー → 作業計画 → TDD 実装 → 受入テスト → リファクタリング → 進捗レポート
設計 → 実装（一括） /pm-auto-design2dev 設計レビュー → 作業計画 → TDD 実装 → 受入テスト → リファクタリング → 進捗レポート

詳細は CommandMate リポジトリの Issues、開発レポート、ワークフロー例 を参照してください。

ドキュメント

ドキュメント 説明
CLI セットアップガイド インストールと初期設定
Webアプリ操作ガイド Webアプリの基本操作
クイックスタート Claude Code コマンドの使い方
コンセプト ビジョンと解決する課題
アーキテクチャ システム設計
デプロイガイド 本番環境構築手順
UI/UXガイド UI 実装の詳細
Trust & Safety セキュリティと権限の考え方

Contributing

バグ報告・機能提案・ドキュメント改善を歓迎します。詳しくは CONTRIBUTING.md を参照してください。

License

MIT License - Copyright (c) 2026 Kewton