Paseo 完全ガイド:複数のAIコーディングエージェントを並列管理する作業場アプリ
Claude CodeやCodexなど複数のAIエージェントをGitワークツリーで同時実行し、スマホ・CLI・自宅サーバーから操作できるPaseo(paseo.sh)の解説。導入、paseo.json、スキル・トラブル対処まで網羅しました。
目次
- 1. Paseoとは?&事前準備
- 2. 3つのインストール方法
- 3. 必須の3用語:プロジェクト・ワークスペース・セッション
- 4. 並列ワークツリー実践とpaseo.json設定
- 5. 差分レビュー・スマホ連携・CLI主要7コマンド
- 6. AIにAIを任せる(オーケストレーション・スキル・プラグイン)
- 7. つまずきやすいポイント(症状別トラブル検索)
- 8. よくある質問(FAQ)と用語集
1. Paseoとは?&事前準備
Claude CodeやCodexなどのコーディングエージェントは便利ですが、通常は1つのターミナル窓に閉じ込められているため、2つの作業を同時に進めるとウィンドウやブランチが混乱しがちです。
- 注意点:Paseo自体はAIモデルではありません。すでに導入・ログイン済みのCLI(
claude・codex・opencode等)を呼び出す作業場アプリなので、既存のサブスクリプション・MCPサーバー・スキルがそのまま引き継がれます。
事前準備
| 準備するもの | 内容 |
|---|---|
| AIコーディングCLI 1つ以上 | Claude Code、Codex、OpenCode、Pi、Antigravity、Muse Code等を導入・ログイン済みであること(ターミナルで起動できれば準備完了) |
| Git + プロジェクトフォルダ | 並列作業の中核がGitワークツリーのためGitリポジトリが実質必須 |
GitHub CLI(gh・推奨) | ログインしておくとPR単位のワークスペース作成やPR認識が可能 |
| Node.js(CLI導入時のみ) | デスクトップアプリを使う場合は不要 |
2. 3つのインストール方法
デスクトップアプリ(★☆☆)初めてなら100%おすすめ — デーモン内蔵
“ダウンロードして開くだけ”
- 導入
- paseo.sh/download または GitHub Releases からOS版を実行
- 利点
- 裏エンジン(デーモン)内蔵で追加の初期設定がほぼ不要
- スマホ接続
- 設定 → マイホスト → デバイス接続(Pair Device)でQR読取
サーバー / CLI(★★☆)リモート開発機・ターミナル中心の運用
“npm install -g @getpaseo/cli”
- 導入
- グローバルnpm導入後に paseo を実行(データ保存先 ~/.paseo)
- 遠隔接続
- 暗号化リレーQR、Tailscale、VPN、SSHに対応
- Web UI
- paseo daemon config set features.webUi.enabled true でブラウザ提供可
Docker / 自前サーバー(★★★)NAS・ホームサーバー常時稼働向け
“ghcr.io/getpaseo/paseo:latest”
- 注意点
- 公式イメージ内にAI CLIは未同梱のため、使いたいCLIを追加する必要あり
- 必須セキュリティ
- PASEO_PASSWORD変更 + 外部公開時は必ずHTTPSリバースプロキシ(Caddy/Nginx)
- 確認順
- まずサーバー内で http://localhost:6767 が開くか確認
npm install -g @getpaseo/cli
paseo3. 必須の3用語:プロジェクト・ワークスペース・セッション
Paseoのサイドバーはチャット一覧ではなく「場所の一覧」です。プロジェクト > ワークスペース > セッションを「学校 → 教室 → 生徒」と覚えると一気に理解できます。
- プロジェクト = 学校:Gitリポジトリやフォルダの登録単位。フォルダを複製しないため、削除しても元コードは消えません。
- ワークスペース = 教室(部屋):作業フォルダ1つを持つ空間。チャットを新しく始めても部屋は残り、AIなしでターミナルやブラウザだけ開くこともできます。
- セッション = 生徒(タブ):部屋の中で動く1つの実行単位(AIチャット・ターミナル・ブラウザ)。同じ部屋のセッションはファイルは共有しますが、会話履歴(コンテキスト)は共有しません。
| よくある誤解 | 実際の挙動 |
|---|---|
| 1ワークスペース=1チャット? | いいえ。ワークスペースは部屋であり、1つの部屋で複数のAI会話・ターミナル・ブラウザが同時に動きます。 |
| アーカイブするとコードが消える? | ローカル部屋は一覧から隠れるだけです。ただしワークツリー部屋は最後の1つをアーカイブするとワークツリーフォルダが削除されるため、未マージ変更を先に確認してください。 |
| 新規セッションは前の会話を引き継ぐ? | 同じフォルダを見るだけで会話は真っ新です。引き継ぐには既存セッションを使うか要約を貼り付けます。 |
4. 並列ワークツリー実践と paseo.json 設定
ECアプリ my-app で 商品並び替え(sort-products) と ログイン画面改善(login-polish) を同時に進める流れです。
- 11つ目のワークツリー部屋を作成
New workspace → Isolation: New worktree → 起点 origin/main → AI(例:Claude Code)を選択。元のmainを汚さず独立ブランチ&フォルダが作られます。
- 2やること+検証方法をセットで指示
「価格順・名前順の並び替えを追加し、関連テストを実行して」のように確認手段まで伝えると精度が上がります。
- 32つ目の部屋を作って別タスクを並列投入
サイドバーのmy-appから login-polish 部屋を作成し、ファイルが競合しない別タスクを別のAIに任せます。
- 4ポート3000競合を paseo.json で自動回避
type: service と $PASEO_PORT を定義しておけば空きポートが自動割り当てされ、web--sort-products--my-app.localhost:6767 のような専用URLで両方同時に確認できます。
{
"worktree": {
"setup": "npm ci",
"teardown": "rm -rf .cache || true"
},
"scripts": {
"test": { "command": "npm test" },
"web": {
"command": "npm run dev -- --port $PASEO_PORT",
"type": "service"
}
}
}5. 差分レビュー・スマホ連携・CLI主要7コマンド
目で見て確認してからマージ
- Changesタブで緑(追加)・赤(削除)のdiffを確認し、気になる点はチャットで修正指示。
- 同じ部屋に
New agentでレビュー専用AIを追加可能ですが、レビューAIの「問題ありません」も意見に過ぎないため、Terminalでnpm testを実行し内蔵Browserで画面を確認してからコミット・アーカイブします。 Cmd+K(Windows/LinuxはCtrl+K)でCommand Centerを開けます。
外出先からスマホ・SSHで続きを操作
部屋は自宅PCのデーモン(既定ポート 6767)に1つだけ存在し、スマホやCLIはそこを覗く窓です。
- モバイルリレー:デスクトップの設定 → マイホスト → デバイス接続 → Enable relayをオンにしてQRを読むだけで、ポート開放・VPN不要のエンドツーエンド暗号化接続が完了します。
- Tailscale / SSH:リレーが使えない環境ではTailscale(
tailscale ip -4+ ポート6767)や、デーモン起動済みサーバーへのssh://user@host接続が可能です。
Paseo CLI 主要7コマンド
サービス・プロバイダ・リモートSSH
6. AIにAIを任せる(オーケストレーション・スキル・プラグイン)
サブエージェントへ自動委任する
- 設定 → マイホスト → Agents → Enable Paseo tools をオン(既定はオフ)。
- 新規セッションを開いてツールを読み込ませる。
- メインAIに「Paseoで2人目のAIを立ち上げて、ファイル変更なしでこのブランチをレビューさせて」と指示すると、
Subagentsに専用ワーカーが現れます。モデルや思考レベルをエージェントプロフィールとして保存したり、スケジュール/ハートビート実行も可能です。
標準オーケストレーションスキル4種
アプリの Orchestration skills または npx skills add getpaseo/paseo で導入できます。
| スキル | 用途 |
|---|---|
/paseo | エージェント・ワークスペース・スケジュール操作の基本リファレンス |
/paseo-handoff | ファイル・進捗・決定事項・完了条件をまとめて別AIへ引き継ぎ |
/paseo-committee | 難題を2つのAIに独立分析させ、メインAIが統合 |
/paseo-advisor | ファイルを変更せず計画やdiffへのセカンドオピニオンだけを取得 |
7. つまずきやすいポイント(症状別トラブル検索)
切り分けの順番は常に ①デーモンが動いているか → ②正しいデーモンに繋いでいるか → ③プロキシ・ネットワーク です。
- AI一覧が空っぽのまま· 導入・AI認識
ターミナルで claude や codex を一度起動してログインを完了させたあと、Paseoを開き直してください。
解決ポイント:CLI導入&ログイン後に再起動分類:導入 - 診断に「コマンドが見つからない」と出る· 導入・AI認識
Providers → Diagnostic で実パスを確認し、config.json の agents.providers.<名前>.command に絶対パスを記載します。
解決ポイント:config.json へ絶対パス指定分類:導入 - 2つ目の部屋で「ポートが使用中」エラー· 並列・ポート・.env
--port 3002 を手動指定するか、paseo.json で type: service と $PASEO_PORT を使い自動割り当てにします。
解決ポイント:$PASEO_PORT + type: service分類:並列 - 新ワークツリーに .env がなくサーバーが起動しない· 並列・ポート・.env
リポジトリルートに .worktreeinclude を作って .env を記載しコミットします(内蔵 worktree-include プラグイン有効を確認)。
解決ポイント:.worktreeinclude をコミット分類:並列 - QRコードを読み込んでも反応がない· スマホ・Tailscale・SSH
リレーは初期値オフです。設定 → マイホスト → デバイス接続 → Enable relay を有効にしてQRを再表示します(CLI:paseo daemon pair)。
解決ポイント:Enable relay をオンにする分類:遠隔 - Tailscaleタイムアウト/SSH接続拒否· スマホ・Tailscale・SSH
両端末のTailscale稼働とIPを確認。SSHはデーモンを自動起動しないため、接続先で paseo daemon start を先に実行してください。
解決ポイント:tailscale ip -4 / paseo daemon start分類:遠隔 - Web UIが真っ白・404、または開いても接続されない· Web UI・プロキシ・プラグイン
features.webUi.enabled を有効にして再起動。Nginxでは Upgrade/Connection・Host保持・proxy_buffering off・長いタイムアウトを設定します(Caddyは標準対応)。
解決ポイント:webUi.enabled + WebSocketヘッダ分類:サーバー - 403 Invalid Host header やHTTPS混在コンテンツ警告· Web UI・プロキシ・プラグイン
DNSリバインディング保護のため daemon.hostnames にドメインを登録し、X-Forwarded-Proto: https と daemon.trustedProxies を設定します。
解決ポイント:daemon.hostnames / X-Forwarded-Proto分類:サーバー - 設定変更が反映されない/プラグインが表示されない· Web UI・プロキシ・プラグイン
daemon.listen 変更時はデーモン再起動が必要です。プラグインは Enable plugins・running状態・対象ホストを確認し paseo plugin logs で確認します。
解決ポイント:paseo reload / plugin logs分類:設定
8. よくある質問(FAQ)と用語集
Q1. Paseoを入れればClaudeやCodexの契約は不要ですか?
Q2. 既存の /grill-me などのスキルがPaseoの設定画面に表示されません。
Q3. paseo.json を置いたのにワークツリー作成時に setup が動きません。
Q4. 自宅サーバー(Docker/NAS)で公開する際の必須セキュリティは?
Q5. Paseoのプラグインはサンドボックスで隔離されていますか?
基本用語集
| 用語 | やさしい意味 |
|---|---|
| エージェント(Agent) | ファイル編集やコマンド実行を自律的に行うAIコーディングツール |
| プロバイダ(Provider) | Paseoと各AI CLIを繋ぐ実行・出力アダプタ規約 |
| デーモン(Daemon) | 裏で常駐する本体エンジン(既定ポート 6767)。全クライアントが接続 |
| ワークツリー(Worktree) | 同じGitリポジトリから独立フォルダとブランチを切り出す仕組み |
| ACP / MCP | ACPはAIクライアント共通規格、MCPはAIへ外部ツールを繋ぐ規格 |
| オーケストレーション | 複数のAIへ仕事を割り振り結果を統合する指揮手法 |
Hafuture JSONフォーマッターで paseo.json・config.json をローカル検証
ワークツリー自動化用の paseo.json やデーモン設定 config.json の構文をブラウザ上でサーバー送信なしに整形・検証できます。