paseo

Paseo は、コーディングエージェントとターミナルを管理するリモートデーモンです。MCP ツールまたは CLI で操作できます。

接続済みホスト

list_hosts を呼び出すと、呼び出し元のデーモン（self）と登録済みの接続先（hosts）を確認できます。ツール呼び出しには、接続先の serverId を使用します。ラベルは表示名です。

create_workspace、list_workspaces、create_agent、send_agent_prompt、get_agent_status、get_agent_activity、list_agents は serverId を受け付けます。呼び出し元のデーモンを対象にする場合は省略してください。その他の MCP ツールは呼び出し元のデーモンで動作します。

エージェントの { serverId, agentId } は常にセットで扱ってください。たとえば、send_agent_prompt は次のように呼び出します。

{ "serverId": "srv_build", "agentId": "agent_123", "prompt": "Continue", "notifyOnFinish": true }

リモートパスとワークスペース ID は接続先に属します。リモートの list_agents には呼び出し元ディレクトリのデフォルト設定がありません。絞り込むには cwd を渡してください。

登録は CLI で管理します。更新や削除には、返された registrationId を使用してください。

paseo --host localhost:6768 host add localhost:6779 --label build
paseo --host localhost:6768 host ls --json

プロジェクト

デーモンのプロジェクトレジストリは CLI で管理します。

paseo project create [path]
paseo project ls
paseo project rename <project-id> <name>
paseo project rename <project-id> --reset
paseo project delete <project-id>

ローカルデーモンの場合、project create はデフォルトで現在のディレクトリを使用し、相対パスは CLI マシン上で解決します。--host または PASEO_HOST を指定する場合は、必ずパスを指定してください。対象のデーモンが、そのマシン上でパスを解決します。プロジェクトを削除すると、アクティブなワークスペースはアーカイブされ、プロジェクトディレクトリは削除されずに Paseo からプロジェクトが削除されます。

ワークスペース

create_workspace — エージェントとは独立してワークスペースを作成します。必須項目：isolation（local または worktree）。Worktree 分離では、mode: "branch-off" | "checkout-branch" | "checkout-pr" をサポートしています。新しいブランチには branchName／baseBranch、既存のブランチには branch、変更リクエストには prNumber と任意の forge を使用します。ローカルディレクトリまたはソースチェックアウトには path、所有プロジェクトには projectId を使用します。パスを指定しない場合、worktree は projectId からソースを解決できます。worktreeSlug は管理対象のパスを指定します。workspaceId を中心とするワークスペース記述子を返します。

background: true を指定すると、ワークスペースの内容は保持され、アクセス可能なまま、デフォルトのリストとサイドバーから非表示になります。background を省略すると、現在のワークスペースの値を継承します（呼び出し元がいない場合は false）。ユーザーが明示的に求めた場合にのみ、値を上書きしてください。

baseBranch は明示的に選択してください。origin/main はリモート追跡ブランチを選択し、refs/heads/main はローカルの main を選択します。単独の main は、ローカルの main が存在すればそれを優先し、存在しなければ origin/main を選択します。ブランチのリベース後や PR の対象変更後も、Paseo は解決済みの ref をワークスペース比較用に保持します。

list_workspaces — アクティブなワークスペースを一覧表示します。includeBackground: true を指定しない限り、バックグラウンドワークスペースは除外されます。

archive_workspace — { workspaceId }。ワークスペースとそのエージェントおよびターミナルをアーカイブします。ローカルディレクトリは残ります。所有する worktree は、最後のアクティブなワークスペース参照がアーカイブされた後にのみ、Paseo によって削除されます。

rename_workspace — { workspaceId, name }。ワークスペースの名前を変更します。

ワークスペーススクリプト

設定済みの paseo.json スクリプトは、ツールと CLI の両方で同じ監視付きライフサイクルを使用します。

list_workspace_scripts — { workspaceId }。設定済みスクリプトのライフサイクル、サービスポート、プロキシ URL、ヘルス状態、終了コード、ターミナル ID を一覧表示します。

start_workspace_script — { workspaceId, scriptName }。Paseo が管理するワークスペーススクリプトランチャーを通じて、設定済みスクリプトを 1 つ起動し、ステータスメタデータを返します。

stop_workspace_script — { workspaceId, scriptName }。監視対象のターミナルを通じて実行中のスクリプトを停止し、停止後のステータスメタデータを返します。

対応する CLI コマンドでは、ワークスペース ID を明示的に指定するか、現在のディレクトリから解決できます。

paseo script ls [--cwd <path> | --workspace <workspace-id>]
paseo script start <name> [--cwd <path> | --workspace <workspace-id>]
paseo script stop <name> [--cwd <path> | --workspace <workspace-id>]

エージェント

create_agent — 必須：title、provider（claude/opus、codex/gpt-5.4、…）、initialPrompt。任意：workspaceId、notifyOnFinish、settings、labels。{ agentId, workspaceId, … } を返します。

初期ランタイム設定は settings の下にあります：modeId、thinkingOptionId、プロバイダー固有の features です。これらの値には、エージェントプロファイルを使用することを推奨します。Codex の高速モードでは、エージェントの作成時に settings: { features: { "fast_mode": true } } を渡します。

エージェントスコープでの作成では、常にあなたのサブエージェントが作成されます。自分のホストでは、現在のワークスペースを使うために workspaceId を省略します。別のホストでは、まずその serverId を指定してワークスペースを一覧表示または作成し、その workspaceId と同じ serverId を create_agent に渡します。配置によって親子関係が変わることはありません。

デタッチはサブエージェントトラックで行う明示的なユーザー操作であり、エージェントツールではありません。別のワークスペースにいる子も、そこの通常のタブとして表示されますが、あなたのサブエージェントであることに変わりはありません。

エージェントスコープの create_agent では、notifyOnFinish は既定で true です。明示的に報告する場合や完了コールバックが不要な場合は、false に設定します。

send_agent_prompt — { agentId, prompt, activeTurnBehavior? }。既存のエージェントへの追加指示に使用します。エージェントスコープの呼び出しでは既定で steer、トップレベルの呼び出しでは既定で interrupt になります。既定値を上書きするには、activeTurnBehavior を steer または interrupt に設定します。ステアリングが利用できない場合は、中断に切り替わります。CLI エージェントへの送信でも同じ既定値が使われ、--behavior steer|interrupt を指定できます。エージェントスコープの呼び出しは、キューに追加されたことを示す受領情報をすぐに返します。各受信者へのメッセージは、2 秒間メッセージがない状態になった後に配信されます。トップレベルの呼び出しは、ディスパッチの確認後に戻ります。エージェントスコープの呼び出しでは notifyOnFinish は既定で true ですが、トップレベルの呼び出しには親へのコールバックがありません。

update_agent — { agentId, name?, labels?, settings? }。既存のエージェントのランタイム設定を変更するには、settings を使用します：modeId、model、thinkingOptionId、プロバイダー固有の features です。Codex の高速モードでは、settings: { features: { "fast_mode": true } } を渡します。

list_agents — cwd、statuses、sinceHours、includeArchived で絞り込みます。バックグラウンドワークスペース内のエージェントも含めるには、includeBackground: true を設定します。

archive_agent — { agentId }。実行中の場合は中断し、アクティブリストから削除します。

エージェントプロファイルとプロバイダーの検出

list_profiles — 人が設定した名前付きの起動設定一式です、委任したエージェントの起動方法を選ぶ前に、このツールを呼び出し、すべてのプロファイルの notes を読みます。ユーザーが指定した名前付きプロファイル、または作業内容に最も合う notes を持つプロファイルを選びます。

create_agent に profile パラメーターはありません。選択したプロファイルの設定を呼び出しに反映します：

• provider と model を組み合わせて provider/model の値にし、create_agent.provider に指定します
• modeId を settings.modeId にコピーします
• thinkingOptionId を settings.thinkingOptionId にコピーします
• featureValues を settings.features にコピーします

値が存在しない場合は省略します。選択したプロファイルを記憶したり、後から設定が変わったと推測したりしないでください。プロファイルは起動設定としてのみ使用します。

適合するプロファイルがない場合、またはプロファイルが設定されていない場合は、推測せずに以下のプロバイダー検出ツールを使用します。設定済みのプロファイルが適合しないために別の方法を使う場合は、その旨をユーザーに伝えます。

list_providers — プロバイダーの利用可否とモードの概要を取得します。

list_models — 1 つのプロバイダーの全モデル一覧を取得します。モデル ID または思考オプションが必要な場合にのみ使用してください。一覧が大きい場合があります。

inspect_provider — プロバイダーの機能と設定項目の概要を取得します。必須：provider。エージェントスコープのセッション外では cwd を渡します。任意：下書きの model、modeId、thinkingOptionId、features を含む settings。

inspect_provider が返す機能 ID のみを設定します。Codex の高速モードでは、fast_mode を探し、settings: { features: { "fast_mode": true } } を create_agent または update_agent に渡します。

スケジュールとハートビート

create_schedule — cron のスケジュールに従って新しいエージェントを起動します。必須項目：prompt、cron、provider。任意項目：timezone、name、cwd、maxRuns、expiresIn。定期的な作業を毎回新しいエージェントで実行する場合に使用します。

create_heartbeat — cron のスケジュールに従ってプロンプトを送信します。必須項目：prompt、cron。任意項目：timezone、name、maxRuns、expiresIn。リマインダー、PR やビルドの監視、この会話に結果を返すステータス確認に使用します。

delete_heartbeat はハートビートを停止します。MCP では意図的にハートビートの更新ツールを公開していません。タスクやスケジュールを変更する場合は、削除して作成し直してください。

スケジュールには、一覧表示／確認／更新／一時停止／再開／1 回実行／ログ／削除のすべての機能があります。ハートビートには意図的にこれらの機能を設けていません。

待機

サブエージェントを作成するかプロンプトを送信すると、notifyOnFinish はデフォルトで true になり、ホストをまたいで完了、エラー、権限リクエストを報告します。 ポーリングせずにターンを終了し、その通知を待ってください。 send_agent_prompt で明示的な返信を受け取りたい場合は、notifyOnFinish: false を設定する前に、送信側で list_hosts を確認し、受信者のサーバーを確認してください。

CLI の仕様

構文が異なる場合でも、CLI とツールは同じ所有権の仕様に従います。

paseo workspace create --isolation worktree --mode branch-off --new-branch fix-x --base origin/main
paseo workspace create --isolation worktree --mode checkout-branch --branch existing-work
paseo workspace create --isolation worktree --mode checkout-pr --pr-number 42
paseo run --provider codex/gpt-5.4 --mode full-access --workspace <workspace-id> "<prompt>"
paseo run --provider codex/gpt-5.4 --mode full-access --new-workspace worktree --worktree-mode branch-off --new-branch fix-x --base origin/main "<prompt>"
paseo send <agent-id> "<follow-up>"
paseo ls
paseo schedule create --cron "*/15 * * * *" "ping main build"
paseo heartbeat create --cron "*/15 * * * *" "check the build"

paseo --help と paseo <cmd> --help で確認できます。

製品に関する質問、セットアップ、ログ、バージョンの問題、トラブルシューティングには、paseo-help スキルを使用してください。