puter/paseo
1
0
Fork 0
mirror of https://github.com/getpaseo/paseo.git synced 2026-07-29 12:01:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(orchestration): explain cross-provider workflows (#2062)

Browse Source
This commit is contained in:
Mohamed Boudra
2026-07-14 12:56:45 +02:00
committed by GitHub
parent 81113d1582
commit f35b16b316
9 changed files with 203 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -70,7 +70,7 @@ You need at least one agent CLI installed and configured with your credentials:
Download it from [paseo.sh/download](https://paseo.sh/download) or the [GitHub releases page](https://github.com/getpaseo/paseo/releases). Open the app and the daemon starts automatically. Nothing else to install.
To connect from your phone, scan the QR code shown in Settings.
To connect from your phone, open **Settings → your host → Connections → Pair a device**.
### CLI / headless

4
public-docs/browser.md
View File

@@ -25,7 +25,7 @@ Because you share the browser with the agent, you can watch it work — and step
Browser tools are off by default. Turn them on per host:
- **In the app:** open your host's settings and enable **Browser tools**.
- **In the app:** open **Settings → your host → Agents** and turn on **Browser tools**.
- **In `config.json`** (`~/.paseo/config.json`):
```json
@@ -38,7 +38,7 @@ Browser tools are off by default. Turn them on per host:
}
```
The tools are part of the [Paseo MCP toolset](/docs/mcp), so **Inject Paseo tools** (`daemon.mcp.injectIntoAgents`) must also be on for agents to receive them. Existing agents may need a reload to pick up new tools.
The tools are part of the [Paseo MCP toolset](/docs/mcp), so **Enable Paseo tools** on the same page must also be on for agents to receive them. Existing agents may need a reload to pick up new tools.
> Browser tools let agents access and control Paseo browser tabs, including logged-in browser state. Only enable this for agents you trust.

3
public-docs/index.md
View File

@@ -14,7 +14,7 @@ Paseo runs your coding agents on your machine and gives you a mobile, desktop, w
Download from [paseo.sh/download](https://paseo.sh/download) or the [GitHub releases page](https://github.com/getpaseo/paseo/releases). Open it and you're done.
The desktop app bundles its own daemon and starts it automatically, no separate install required. On first launch you'll see a brief startup screen, then connect from your phone by scanning the QR code in Settings.
The desktop app bundles its own daemon and starts it automatically, no separate install required. On first launch you'll see a brief startup screen, then connect from your phone using **Settings → your host → Connections → Pair a device**.
## Server / CLI
@@ -53,6 +53,7 @@ The image runs the daemon and serves the bundled web UI. It does not bundle agen
- [Docker](/docs/docker), run the daemon and bundled web UI in a container.
- [Workspaces](/docs/workspaces), the project, workspace, and session model Paseo is built around.
- [Providers](/docs/providers), what a provider is and how Paseo wraps existing CLIs.
- [Orchestration](/docs/orchestration), let one agent delegate work to other providers and models.
- [CLI reference](/docs/cli), every command.
- [Self-hosting the web UI](/docs/web-ui), serve the browser app from your own daemon.
- [GitHub repo](https://github.com/getpaseo/paseo)

40
public-docs/mcp.md
View File

@@ -1,14 +1,18 @@
---
title: Paseo MCP
description: Paseo MCP tools injected into agents.
nav: Paseo MCP
order: 30
title: MCP reference
description: Reference for the Paseo tools agents use to manage agents, workspaces, terminals, and schedules.
nav: MCP reference
order: 33
category: Orchestration
---
# Paseo MCP
# MCP reference
Paseo can inject these MCP tools into every new agent it launches. Turn on **Inject Paseo tools** in host settings, or set `daemon.mcp.injectIntoAgents` to `true`.
This is the complete catalog behind the workflows in [Orchestration](/docs/orchestration) and [Common workflows](/docs/orchestration-workflows). You normally ask for an outcome in natural language and let the agent choose the tools.
Paseo can inject these tools into every new agent it launches. Open **Settings → your host → Agents** and turn on **Enable Paseo tools**, or set `daemon.mcp.injectIntoAgents` to `true`.
Depending on the provider, Paseo delivers the catalog through its native tool interface or MCP. The capabilities are the same either way.
The MCP server itself is controlled by `daemon.mcp.enabled`. Existing agents may need a reload.
@@ -29,6 +33,15 @@ The MCP server itself is controlled by `daemon.mcp.enabled`. Existing agents may
| `get_agent_activity` | Return recent agent timeline entries as a curated summary. |
| `set_agent_mode` | Switch an agent's session mode. |
### Workspaces and worktrees
| Tool | Function |
| ------------------ | ----------------------------------------------------------------------------- |
| `rename_workspace` | Change the user-visible name of the current or specified workspace. |
| `list_worktrees` | List Paseo-managed git worktrees for a repository. |
| `create_worktree` | Create a Paseo-managed git worktree from a branch, base branch, or GitHub PR. |
| `archive_worktree` | Delete a Paseo-managed git worktree. |
### Terminals
| Tool | Function |
@@ -44,10 +57,13 @@ The MCP server itself is controlled by `daemon.mcp.enabled`. Existing agents may
| Tool | Function |
| ------------------ | ----------------------------------------------------------------- |
| `create_schedule` | Create a recurring schedule that runs on an agent or a new agent. |
| `create_heartbeat` | Send a recurring prompt back into the current agent. |
| `list_schedules` | List schedules managed by the daemon. |
| `inspect_schedule` | Inspect a schedule and its run history. |
| `pause_schedule` | Pause an active schedule. |
| `resume_schedule` | Resume a paused schedule. |
| `update_schedule` | Change the cadence, prompt, limits, or other schedule settings. |
| `schedule_logs` | Return recent runs and output for a schedule. |
| `delete_schedule` | Delete a schedule permanently. |
### Providers
@@ -58,14 +74,6 @@ The MCP server itself is controlled by `daemon.mcp.enabled`. Existing agents may
| `list_models` | List models for an agent provider. |
| `inspect_provider` | Inspect compact provider capabilities and draft feature settings. |
### Worktrees
| Tool | Function |
| ------------------ | ----------------------------------------------------------------------------- |
| `list_worktrees` | List Paseo-managed git worktrees for a repository. |
| `create_worktree` | Create a Paseo-managed git worktree from a branch, base branch, or GitHub PR. |
| `archive_worktree` | Delete a Paseo-managed git worktree. |
### Permissions
| Tool | Function |
@@ -73,6 +81,10 @@ The MCP server itself is controlled by `daemon.mcp.enabled`. Existing agents may
| `list_pending_permissions` | Return pending permission requests across agents. |
| `respond_to_permission` | Approve or deny a pending permission request. |
### Browser
Browser automation is opt-in and adds tools for opening tabs, reading pages, clicking, typing, and taking screenshots. See the [Browser tools reference](/docs/browser-tools).
### Voice
| Tool | Function |

92
public-docs/orchestration-workflows.md Normal file
View File

@@ -0,0 +1,92 @@
---
title: Common orchestration workflows
description: Copyable prompts for delegating, parallelizing, reviewing, and continuing agent work with Paseo.
nav: Common workflows
order: 31
category: Orchestration
---
# Common orchestration workflows
These examples are prompts for your main agent. Change the provider, model, task, and branch names to fit your work.
## Send work to a different model
Keep a strong planner in the main chat and send implementation to a workhorse:
```text
Stay as the orchestrator. Use Paseo to find the available Codex 5.6 model, then
create a subagent in a new worktree. Ask it to implement the parser change and
run the focused tests.
```
Ask the orchestrator to inspect providers first when you are unsure of the exact model ID. Available models come from your own installed and authenticated CLIs.
## Fan out research
Read-only work can safely share one workspace:
```text
Create three Paseo subagents in this workspace. Have one trace the request path,
one inspect the tests, and one look for related regressions. Do not edit files.
Synthesize their findings when all three report back.
```
Each worker appears in the Subagents track, and the orchestrator can keep working while they run.
## Parallelize edits without collisions
Give each independent implementation its own git worktree:
```text
Split these two issues between two Paseo subagents. Create a separate worktree
from main for each issue, use the best available implementation model, and have
each agent run the focused checks for its change. Summarize both diffs when done.
```
Use the current workspace for collaboration on the same files. Use worktrees when agents may edit independently.
## Implement, then review
Use different models for making and judging the change:
```text
Create a worker in a new worktree to implement this feature. When it finishes,
create a second subagent on the same worktree to review the diff for correctness,
missing tests, and unnecessary complexity. Bring the review back here.
```
The second agent sees the worker's files without sharing its conversation context, which makes the review more independent.
## Check, redirect, or continue work
The orchestrator can inspect a worker and send a follow-up without starting over:
```text
Summarize what the subagents are doing and flag anything blocked.
```
```text
Tell the parser worker to add the malformed-input case and rerun its test file.
```
```text
Cancel the UI worker's current turn, but keep the agent so I can redirect it.
```
## Keep an agent working with a heartbeat
Use a heartbeat when the current agent should wake itself up, reassess the task, and continue working:
```text
Use Paseo to create a heartbeat every 10 minutes. Continue this migration in
small steps, run the focused checks after each step, and stop when the migration
is complete or after two hours.
```
```text
Create a heartbeat every 5 minutes to check this deployment. Investigate any
failure and report meaningful changes in this conversation. Stop after one hour.
```
A heartbeat returns to the same conversation. For cron-style recurring work such as daily triage, use a [schedule](/docs/schedules). For reusable workflows such as handoffs, committees, advisors, and bounded loops, see [Orchestration skills](/docs/skills).

75
public-docs/orchestration.md Normal file
View File

@@ -0,0 +1,75 @@
---
title: Orchestration
description: Give any coding agent control of Paseo so it can launch and coordinate agents from other providers.
nav: Overview
order: 30
category: Orchestration
---
# Orchestration
Paseo orchestration gives a coding agent control of the Paseo daemon. The agent can discover every provider and model you have configured, create worktrees, launch other agents, send them follow-ups, and create heartbeats or schedules. The same work stays visible in the Paseo app.
## Native subagents vs Paseo subagents
The most important difference from native subagents is that **Paseo subagents can cross provider boundaries**.
```text
Claude Code (Fable 5) => Codex (GPT-5.6)
Codex (GPT-5.6) => Grok Build
Cursor => Claude Code (Fable 5)
```
Native subagents belong to one provider. Claude Code launches Claude Code subagents; Codex launches Codex subagents. They are useful when the parent provider can handle the whole task itself.
Paseo subagents are full agents managed by the Paseo daemon. The orchestrator can choose any configured provider and model, place the worker in the current workspace or a new worktree, and keep coordinating it after launch. Use them when you want one model to plan, another to implement, and another to review.
| | Native subagent | Paseo subagent |
| -------------------- | ----------------------------------------- | -------------------------------------------------- |
| Provider | Same provider as its parent | Any provider configured in Paseo |
| Working directory | Managed by the parent provider | Current workspace, existing workspace, or worktree |
| Lifecycle | Owned by the parent provider | Managed by Paseo; can receive follow-ups or detach |
| Where you inspect it | Read-only timeline in the Subagents track | Full agent session in the Subagents track |
| Best for | Fast, provider-native delegation | Cross-provider work and explicit workspace control |
## Try it
Open **Settings → your host → Agents**, then turn on **Enable Paseo tools**. Start a new agent, or reload an existing one so it receives the tools.
Then ask naturally:
```text
Stay as the orchestrator. Use Paseo to find my available Codex models, then
launch a GPT-5.6 subagent in a new worktree. Ask it to implement the parser
change, run the focused tests, and report back here.
```
The orchestrator discovers the provider and model IDs, starts the worker, and receives a notification when it finishes. You can keep talking to the orchestrator in the meantime.
## Where the work appears
Spawned work appears in the **Subagents track** above the composer. Open a row to read the live conversation.
Both kinds of subagent appear there:
- **Paseo subagents** open as full agent sessions. You can talk to them directly, change their settings, detach them, or archive them.
- **Native provider subagents** open as read-only timelines. You can inspect their work, but their provider owns their lifecycle.
If an agent says background work is running but the track is empty, update Paseo. Provider-created subagent timelines require Paseo 0.1.107 or newer.
## Keep an agent working with a heartbeat
A heartbeat sends a prompt back into the same agent on a cadence. Use one when the agent should keep reassessing a live task: continue a refactor, babysit CI, watch a deployment, or retry after an external system changes.
Ask the agent directly:
```text
Use Paseo to create a heartbeat every 10 minutes. Keep checking this PR, fix any
new CI failures, and stop when all checks pass or after two hours.
```
The base [`/paseo` orchestration skill](/docs/skills) teaches agents how to create heartbeats, so you only need to ask. A heartbeat continues the current conversation; a [schedule](/docs/schedules) is better for standalone cron-style jobs such as daily triage.
You do not need to name MCP tools in your prompts. Ask for the workflow; the agent uses the tools underneath.
Continue with [Common workflows](/docs/orchestration-workflows) for copyable prompts, [Orchestration skills](/docs/skills) for packaged workflows, or the [MCP reference](/docs/mcp) for the complete tool catalog.

4
public-docs/skills.md
View File

@@ -8,7 +8,9 @@ category: Orchestration
# Orchestration skills
Paseo ships orchestration skills that teach coding agents (Claude Code, Codex) how to use the Paseo CLI to spawn, coordinate, and manage other agents. Skills are slash commands your agent can invoke, they provide the prompts, context, and workflows so agents know how to orchestrate without you writing boilerplate. Install them from the desktop app's Integrations settings or via the CLI.
Paseo ships orchestration skills that teach coding agents how to use Paseo tools and the CLI to spawn, coordinate, and manage other agents. Skills package common workflows as slash commands, so agents know how to orchestrate without you writing the briefing and safety rails each time.
Start with [Orchestration](/docs/orchestration) if you want the mental model, or [Common workflows](/docs/orchestration-workflows) for prompts you can use without installing skills.
## Installation

2
public-docs/troubleshooting.md
View File

@@ -81,7 +81,7 @@ Desktop app log location:
paseo daemon restart
```
Or in the app, open **Settings → your host → Host** and use **Restart daemon**. Running agents keep going, and clients reconnect automatically.
Or in the app, open **Settings → your host → Overview** and use **Restart daemon**. Running agents keep going, and clients reconnect automatically.
## Still stuck?

2
public-docs/why.md
View File

@@ -37,7 +37,7 @@ Paseo is a self-hostable platform for running and orchestrating coding agents. I
## Automation
- The CLI exposes the same surface as the app. Anything in the UI is scriptable.
- MCP server. Agents can drive Paseo themselves: create worktrees, spawn other agents, open terminals, send prompts.
- [Paseo tools](/docs/orchestration). Agents can drive Paseo themselves: create worktrees, spawn other agents, open terminals, and send prompts.
## What it isn't