jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

Document workspace-first agent automation (#2192)

Browse Source 
* docs: explain workspace-first automation

* docs: make automation examples self-contained
This commit is contained in:
Mohamed Boudra
2026-07-18 15:18:05 +02:00
committed by GitHub
parent 05d1f838d8
commit 72752b7db6
12 changed files with 237 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public-docs/orchestration.md
+12 -8
View File
@@ -8,7 +8,7 @@ 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.
Paseo orchestration gives a coding agent control of the Paseo daemon. The agent can discover every provider and model you have configured, create workspaces, 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
@@ -22,13 +22,13 @@ 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.
Paseo subagents are full agents managed by the Paseo daemon. The orchestrator can choose any configured provider and model, keep the worker in the current workspace, or place it in another workspace created for the task. 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 |
| Working directory | Managed by the parent provider | Current or explicitly selected workspace |
| Lifecycle | Owned by the parent provider | Managed by Paseo; can receive follow-ups |
| 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 |
@@ -40,26 +40,30 @@ 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.
create a worktree-isolated workspace, then launch a GPT-5.6 subagent there. 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.
Agent creation has one default: when an agent creates another agent without a workspace ID, the new agent is its subagent in the same workspace. Passing a workspace ID changes where the subagent works, not who its parent is.
## 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.
- **Paseo subagents** open as full agent sessions. You can talk to them directly, change their settings, or archive them.
- **Native provider subagents** open as read-only timelines. You can inspect their work, but their provider owns their lifecycle.
A cross-workspace subagent still belongs to its parent's Subagents track. Paseo also opens its workspace so the work is not hidden in an otherwise empty workspace. If you want to turn any subagent into a top-level agent, detach it manually in the app or with `paseo agent detach`; detachment is not an agent-creation mode.
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.
A heartbeat sends a prompt back into the same agent on a cron 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: