diff --git a/README.md b/README.md index 3b009c8fe..d30719158 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/public-docs/browser.md b/public-docs/browser.md index 6201069c7..82f931692 100644 --- a/public-docs/browser.md +++ b/public-docs/browser.md @@ -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. diff --git a/public-docs/index.md b/public-docs/index.md index 3bb529537..004505223 100644 --- a/public-docs/index.md +++ b/public-docs/index.md @@ -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) diff --git a/public-docs/mcp.md b/public-docs/mcp.md index 3ddab791a..26ab1b2a8 100644 --- a/public-docs/mcp.md +++ b/public-docs/mcp.md @@ -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 | diff --git a/public-docs/orchestration-workflows.md b/public-docs/orchestration-workflows.md new file mode 100644 index 000000000..0fbbefbac --- /dev/null +++ b/public-docs/orchestration-workflows.md @@ -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). diff --git a/public-docs/orchestration.md b/public-docs/orchestration.md new file mode 100644 index 000000000..2ab26bfe5 --- /dev/null +++ b/public-docs/orchestration.md @@ -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. diff --git a/public-docs/skills.md b/public-docs/skills.md index c6fddf6ea..a4509797e 100644 --- a/public-docs/skills.md +++ b/public-docs/skills.md @@ -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 diff --git a/public-docs/troubleshooting.md b/public-docs/troubleshooting.md index 55d2c140c..556b83748 100644 --- a/public-docs/troubleshooting.md +++ b/public-docs/troubleshooting.md @@ -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? diff --git a/public-docs/why.md b/public-docs/why.md index 307aaf599..89ce141e0 100644 --- a/public-docs/why.md +++ b/public-docs/why.md @@ -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