hafuture

Paseo 完全ガイド:複数のAIコーディングエージェントを並列管理する作業場アプリ

Claude CodeやCodexなど複数のAIエージェントをGitワークツリーで同時実行し、スマホ・CLI・自宅サーバーから操作できるPaseo(paseo.sh)の解説。導入、paseo.json、スキル・トラブル対処まで網羅しました。

PaseoAI Coding AgentsClaude CodeCodexGit WorktreeOrchestrationDeveloper Tools

目次


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つのインストール方法

自分の環境に合うPaseo導入方法を選ぶ
デスクトップアプリ(★☆☆)

初めてなら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 が開くか確認
bash
npm install -g @getpaseo/cli
paseo
起動時にデーモンが立ち上がり、暗号化リレー(QRペアリング)を有効にするか尋ねられます。設定は PASEO_HOME(既定 ~/.paseo)へ保存されます。

3. 必須の3用語:プロジェクト・ワークスペース・セッション

Paseoのサイドバーはチャット一覧ではなく「場所の一覧」です。プロジェクト > ワークスペース > セッションを「学校 → 教室 → 生徒」と覚えると一気に理解できます。

  • プロジェクト = 学校:Gitリポジトリやフォルダの登録単位。フォルダを複製しないため、削除しても元コードは消えません。
  • ワークスペース = 教室(部屋):作業フォルダ1つを持つ空間。チャットを新しく始めても部屋は残り、AIなしでターミナルやブラウザだけ開くこともできます。
  • セッション = 生徒(タブ):部屋の中で動く1つの実行単位(AIチャット・ターミナル・ブラウザ)。同じ部屋のセッションはファイルは共有しますが、会話履歴(コンテキスト)は共有しません。
よくある誤解実際の挙動
1ワークスペース=1チャット?いいえ。ワークスペースは部屋であり、1つの部屋で複数のAI会話・ターミナル・ブラウザが同時に動きます。
アーカイブするとコードが消える?ローカル部屋は一覧から隠れるだけです。ただしワークツリー部屋は最後の1つをアーカイブするとワークツリーフォルダが削除されるため、未マージ変更を先に確認してください。
新規セッションは前の会話を引き継ぐ?同じフォルダを見るだけで会話は真っ新です。引き継ぐには既存セッションを使うか要約を貼り付けます。

4. 並列ワークツリー実践と paseo.json 設定

ECアプリ my-app で 商品並び替え(sort-products) と ログイン画面改善(login-polish) を同時に進める流れです。

  1. 1
    1つ目のワークツリー部屋を作成

    New workspace → Isolation: New worktree → 起点 origin/main → AI(例:Claude Code)を選択。元のmainを汚さず独立ブランチ&フォルダが作られます。

  2. 2
    やること+検証方法をセットで指示

    「価格順・名前順の並び替えを追加し、関連テストを実行して」のように確認手段まで伝えると精度が上がります。

  3. 3
    2つ目の部屋を作って別タスクを並列投入

    サイドバーのmy-appから login-polish 部屋を作成し、ファイルが競合しない別タスクを別のAIに任せます。

  4. 4
    ポート3000競合を paseo.json で自動回避

    type: service と $PASEO_PORT を定義しておけば空きポートが自動割り当てされ、web--sort-products--my-app.localhost:6767 のような専用URLで両方同時に確認できます。

json
{
  "worktree": {
    "setup": "npm ci",
    "teardown": "rm -rf .cache || true"
  },
  "scripts": {
    "test": { "command": "npm test" },
    "web": {
      "command": "npm run dev -- --port $PASEO_PORT",
      "type": "service"
    }
  }
}
Paseoはbaseブランチ(origin/main)にコミットされた paseo.json を読み込みます。portは省略して $PASEO_PORT を使うのがポイントです。

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を任せる(オーケストレーション・スキル・プラグイン)

サブエージェントへ自動委任する

  1. 設定 → マイホスト → Agents → Enable Paseo tools をオン(既定はオフ)。
  2. 新規セッションを開いてツールを読み込ませる。
  3. メイン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. つまずきやすいポイント(症状別トラブル検索)

切り分けの順番は常に ①デーモンが動いているか → ②正しいデーモンに繋いでいるか → ③プロキシ・ネットワーク です。

Paseo 症状別トラブルシューティング9件
  • 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の契約は不要ですか?
いいえ。Paseoは手元に導入済みのAIコーディングCLIを並列管理する作業場アプリであり、各AIモデルの契約・API料金はそのまま必要です。
Q2. 既存の /grill-me などのスキルがPaseoの設定画面に表示されません。
正常です。Paseoの Orchestration skills カードは /paseo 系4種のみ管理します。既存スキルは対象CLI(例:Claude Code)をプロバイダに選べば ~/.claude/skills/ からそのまま読み込まれます。
Q3. paseo.json を置いたのにワークツリー作成時に setup が動きません。
9割は未コミットが原因です。Paseoは起点ブランチ(通常 origin/main)にコミットされた paseo.json と .worktreeinclude を参照します。
Q4. 自宅サーバー(Docker/NAS)で公開する際の必須セキュリティは?
外部公開前に必ず paseo daemon set-password(または PASEO_PASSWORD)を設定し、HTTPSリバースプロキシ(Caddy/Nginx)と daemon.hostnames 許可リストを組み合わせてください。
Q5. Paseoのプラグインはサンドボックスで隔離されていますか?
いいえ。デーモン権限およびアプリ内で隔離されずに実行されるため、出所が確かな信頼できるプラグインのみ導入してください。

基本用語集

用語やさしい意味
エージェント(Agent)ファイル編集やコマンド実行を自律的に行うAIコーディングツール
プロバイダ(Provider)Paseoと各AI CLIを繋ぐ実行・出力アダプタ規約
デーモン(Daemon)裏で常駐する本体エンジン(既定ポート 6767)。全クライアントが接続
ワークツリー(Worktree)同じGitリポジトリから独立フォルダとブランチを切り出す仕組み
ACP / MCPACPはAIクライアント共通規格、MCPはAIへ外部ツールを繋ぐ規格
オーケストレーション複数のAIへ仕事を割り振り結果を統合する指揮手法

Hafuture JSONフォーマッターで paseo.json・config.json をローカル検証

ワークツリー自動化用の paseo.json やデーモン設定 config.json の構文をブラウザ上でサーバー送信なしに整形・検証できます。

JSONフォーマッターを開く