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

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

69
public-docs/cli.md
View File

@@ -1,6 +1,6 @@
---
title: CLI
description: "Paseo CLI reference: manage agents, daemons, permissions, and worktrees from your terminal."
description: "Paseo CLI reference: manage agents, workspaces, schedules, daemons, and permissions from your terminal."
nav: CLI
order: 3
category: Getting started
@@ -10,7 +10,7 @@ category: Getting started
The Paseo CLI lets you manage agents from your terminal. It's the same interface exposed by the daemon's API, so anything you can do in the app you can do from the command line.
> **Agent orchestration:** You can tell coding agents to use the Paseo CLI to spawn and manage other agents. This enables multi-agent workflows where one agent delegates subtasks to others and waits for results.
> **Agent orchestration:** You can tell coding agents to use the Paseo CLI to spawn and manage other agents. Paseo recognizes the calling agent, so CLI-created workers get the same workspace and parent defaults as MCP-created workers.
## Quick reference
@@ -30,17 +30,59 @@ Use `paseo run` to start a new agent with a task:
```bash
paseo run "implement user authentication"
paseo run --provider codex "refactor the API layer"
paseo run --detach "run the full test suite" # background
paseo run --worktree feature-x "implement feature X"
paseo run --background "run the focused test suite"
paseo run --isolation worktree --base main "implement feature X"
paseo run --workspace <workspace-id> "review the current diff"
paseo run --output-schema schema.json "extract release notes"
paseo run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "summarize release notes"
```
The `--worktree` flag creates the agent in an isolated git worktree, useful for parallel feature development.
From a human shell, a bare `paseo run` creates a new local workspace for the current directory. Use `--workspace <id>` to add the agent to an existing workspace, or `--isolation worktree` to create a new workspace backed by an isolated git worktree.
Use `--output-schema` to return only matching JSON output. You can pass a schema file path or an inline JSON schema object. This mode cannot be used with `--detach`.
When an existing Paseo agent runs the same command, Paseo recognizes it through `PASEO_AGENT_ID`. Without explicit placement, the new agent becomes its subagent in the same workspace. `--workspace` can place that subagent elsewhere without changing its parent.
By default, `paseo run` waits for completion. Use `--detach` to run in the background.
Use `--output-schema` to return only matching JSON output. You can pass a schema file path or an inline JSON schema object. This mode cannot be used with `--background`.
By default, `paseo run` waits for completion. Use `--background` to return immediately while the agent keeps running.
## Workspaces
Create a workspace independently when you want to prepare its files before starting an agent:
```bash
paseo workspace create --isolation local --path ~/dev/my-app --title main
paseo workspace create \
--isolation worktree \
--path ~/dev/my-app \
--mode branch-off \
--new-branch feature/auth \
--worktree-slug feature-auth \
--base main
paseo workspace create \
--isolation worktree \
--path ~/dev/my-app \
--mode checkout-branch \
--branch feature/existing \
--worktree-slug existing-copy
paseo workspace create \
--isolation worktree \
--path ~/dev/my-app \
--mode checkout-pr \
--pr-number 2186
```
Then list, use, or archive it:
```bash
paseo workspace ls
paseo run --workspace <workspace-id> "implement authentication"
paseo workspace archive <workspace-id>
```
Add `--forge <name>` to PR checkout when Paseo cannot infer the forge from the source checkout. See [Git worktrees](/docs/worktrees) for setup hooks and services.
## Listing agents
@@ -93,7 +135,7 @@ Useful in scripts or when one agent needs to wait for another.
## Schedules
Run an agent on an interval or a cron. See [Schedules from the CLI](/docs/schedules-cli) for the full reference.
Run an agent on a cron schedule. The CLI also accepts simple cadence presets and compiles them to cron. See [Schedules from the CLI](/docs/schedules-cli) for the full reference.
```bash
paseo schedule create --every 30m --cwd ~/dev/my-app "Continue the refactor and leave a note."
@@ -119,8 +161,11 @@ Change an agent's operational mode (provider-specific):
paseo agent mode <id> --list # Show available modes
paseo agent mode <id> bypass # Set bypass mode
paseo agent mode <id> plan # Set plan mode
paseo agent detach <id> # Make a subagent top-level
```
Detaching is an explicit lifecycle action, not a creation flag. The agent keeps running; only its relationship to its parent changes.
## Daemon management
```bash
@@ -157,11 +202,13 @@ The CLI is designed to be used by agents themselves. You can instruct an agent t
```bash
# Agent A spawns Agent B and waits for it
paseo run --detach "implement the API" --name api-agent
paseo wait api-agent
paseo logs api-agent --tail 5
agent_id=$(paseo run --background --quiet --title api-agent "implement the API")
paseo wait "$agent_id"
paseo logs "$agent_id" --tail 5
```
Because Agent A's ID is present in the environment, Agent B is created as its subagent in the same workspace unless `--workspace` is specified.
Simple implement + verify loop:
```bash

81
public-docs/mcp.md
View File

@@ -16,31 +16,44 @@ Depending on the provider, Paseo delivers the catalog through its native tool in
The MCP server itself is controlled by `daemon.mcp.enabled`. Existing agents may need a reload.
## Mental model
Workspaces decide where work happens; agent parentage decides who owns the work.
- An agent that calls `create_agent` without a `workspaceId` gets a subagent in its own workspace.
- Passing a `workspaceId` places that subagent in another workspace without detaching it from its parent.
- A top-level MCP caller without a workspace gets a new local workspace.
- Create a workspace first when you need worktree isolation, a specific branch, or a pull request checkout.
MCP does not expose an agent-detach tool. Detaching is a manual user action in the app or CLI.
## Tools
### Agents
| Tool | Function |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| `create_agent` | Create an agent tied to a working directory, optionally with initial settings or a new git worktree. |
| `send_agent_prompt` | Send a task to a running agent. |
| `get_agent_status` | Return the latest snapshot for an agent. |
| `list_agents` | List recent agents as compact metadata. |
| `cancel_agent` | Abort an agent's current run but keep the agent alive. |
| `archive_agent` | Soft-delete an agent and remove it from the active list. |
| `kill_agent` | Terminate an agent session permanently. |
| `update_agent` | Update an agent name, labels, or runtime settings such as mode/model/thinking/features. |
| `get_agent_activity` | Return recent agent timeline entries as a curated summary. |
| `set_agent_mode` | Switch an agent's session mode. |
| Tool | Function |
| -------------------- | --------------------------------------------------------------------------------------- |
| `create_agent` | Create an agent, optionally placing it in an existing workspace with `workspaceId`. |
| `send_agent_prompt` | Send a task to a running agent. |
| `get_agent_status` | Return the latest snapshot for an agent. |
| `list_agents` | List recent agents as compact metadata. |
| `cancel_agent` | Abort an agent's current run but keep the agent alive. |
| `archive_agent` | Soft-delete an agent and remove it from the active list. |
| `kill_agent` | Terminate an agent session permanently. |
| `update_agent` | Update an agent name, labels, or runtime settings such as mode/model/thinking/features. |
| `get_agent_activity` | Return recent agent timeline entries as a curated summary. |
| `set_agent_mode` | Switch an agent's session mode. |
### Workspaces and worktrees
### Workspaces
| 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. |
| Tool | Function |
| ------------------- | ----------------------------------------------------------------------------------------------------- |
| `create_workspace` | Create a local or worktree-isolated workspace. Worktrees can branch off, check out a branch, or a PR. |
| `list_workspaces` | List active workspaces and their directories and isolation. |
| `rename_workspace` | Change the user-visible name of the current or specified workspace. |
| `archive_workspace` | Archive a workspace and the sessions it owns. |
For worktree isolation, `create_workspace` accepts the same useful choices as the app: branch off from a base, check out an existing branch, or check out a pull request. The worktree remains an implementation detail of the workspace lifecycle.
### Terminals
@@ -52,19 +65,25 @@ The MCP server itself is controlled by `daemon.mcp.enabled`. Existing agents may
| `capture_terminal` | Capture plain-text output from a terminal session. |
| `send_terminal_keys` | Send text or special key tokens to a terminal session. |
### Schedules
### Schedules and heartbeats
| 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. |
Both use the same cron engine, but they have deliberately different interfaces.
| Tool | Function |
| ------------------- | ---------------------------------------------------------------------------- |
| `create_schedule` | Create a cron schedule that starts a new agent for each run. |
| `list_schedules` | List new-agent 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 a schedule's cron, prompt, agent settings, limits, or other settings. |
| `schedule_logs` | Return recent runs and output for a schedule. |
| `run_schedule_once` | Start one new-agent schedule run without changing its cron. |
| `delete_schedule` | Delete a new-agent schedule permanently. |
| `create_heartbeat` | Send a recurring cron-backed prompt into the current agent. |
| `delete_heartbeat` | Delete one of the current agent's heartbeats. |
MCP heartbeats are ephemeral: create or delete them. To change one, delete it and create a replacement. Pause, resume, update, inspect, logs, and run-once apply to new-agent schedules only.
### Providers

2
public-docs/metadata-generation.md
View File

@@ -13,7 +13,7 @@ Paseo asks a language model to write short pieces of text for you so you don't h
Paseo generates these kinds of metadata:
- **Workspace titles** — a short, task-shaped label for a workspace, shown in the sidebar.
- **Worktree branch names** — a slug for the branch a new worktree agent runs on.
- **Worktree branch names** — a slug for a new worktree-isolated workspace's branch.
- **Commit messages** — a concise message for the changes you're committing.
- **Pull request title and body** — drafted from the diff when you open a PR.

20
public-docs/orchestration-workflows.md
View File

@@ -16,8 +16,8 @@ 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.
create a worktree-isolated workspace and launch a subagent there. 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.
@@ -36,12 +36,13 @@ Each worker appears in the Subagents track, and the orchestrator can keep workin
## Parallelize edits without collisions
Give each independent implementation its own git worktree:
Give each independent implementation its own worktree-isolated workspace:
```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.
Split these two issues between two Paseo subagents. Create a separate workspace
with worktree isolation 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.
@@ -51,9 +52,10 @@ Use the current workspace for collaboration on the same files. Use worktrees whe
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.
Create a worktree-isolated workspace and launch a worker there to implement this
feature. When it finishes, create a second subagent in the same workspace 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.

20
public-docs/orchestration.md
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:

4
public-docs/schedules-chat.md
View File

@@ -16,6 +16,6 @@ Example prompts:
- "Check the release build every 5 minutes until it passes, and fix the cause if it fails."
- "Keep working on this refactor — wake yourself every 20 minutes and continue where you left off."
The agent picks the cadence, target, and prompt from what you asked, creates the schedule, and reports back. You can manage it the same way — "pause the triage schedule", "make the build check run every 2 minutes instead", "delete it" — or from the [Schedules view](/docs/schedules) and the [CLI](/docs/schedules-cli).
The agent picks the cron cadence, agent settings, and prompt from what you asked, creates the schedule, and reports back. You can manage a new-agent schedule the same way — "pause the triage schedule", "make the build check run every 2 minutes instead", "run it once now", or "delete it" — or from the [Schedules view](/docs/schedules) and the [CLI](/docs/schedules-cli).
An agent scheduling itself to wake up later is a **heartbeat**. See [Paseo MCP](/docs/mcp) for the underlying tools.
An agent scheduling itself to wake up later is a **heartbeat**. Over MCP, an agent can create or delete its heartbeat; changing one means deleting it and creating a replacement. This small surface prevents a heartbeat from silently becoming a different job or agent. See [Paseo MCP](/docs/mcp) for the underlying tools.

28
public-docs/schedules-cli.md
View File

@@ -8,7 +8,7 @@ category: Schedules
# Schedules from the CLI
`paseo schedule` creates and manages [schedules](/docs/schedules) from your terminal, useful for headless boxes and scripts.
`paseo schedule` creates and manages new-agent [schedules](/docs/schedules) from your terminal, useful for headless boxes and scripts. Every run starts a fresh agent.
## Create
@@ -62,16 +62,28 @@ paseo schedule create \
"Review overnight CI failures and summarize anything urgent."
```
Heartbeat the current agent:
## Heartbeats
Inside a running Paseo agent, create a heartbeat for that same conversation:
```bash
paseo schedule create \
--every 20m \
--target self \
paseo heartbeat create \
--cron "*/20 * * * *" \
--name heartbeat \
"Check the current task state and continue with the next useful step."
```
The heartbeat interface is deliberately small:
```bash
paseo heartbeat update <id> --cron "*/10 * * * *"
paseo heartbeat delete <id>
```
Updating a heartbeat changes only its cron cadence and optional time zone. Its target and prompt stay fixed. Heartbeat commands require `PASEO_AGENT_ID`, which Paseo sets inside agent sessions.
Heartbeats require a raw `--cron` expression. The `--every` presets below are available only for new-agent schedules.
## Manage
```bash
@@ -87,8 +99,10 @@ paseo schedule delete <id>
## Cadence
Use `--every <duration>` for intervals and `--cron "<expr>"` for 5-field cron. Cron schedules default to UTC. Pass `--timezone <IANA>` to interpret cron fields in a local wall-clock time zone, for example `--timezone America/New_York`. The persisted `nextRunAt` is still a UTC instant, but it is computed from that local time zone so recurring jobs stay at the same local time across daylight saving time changes.
Use `--cron "<expr>"` for a 5-field cron expression. For common cron-compatible cadences, `--every <duration>` accepts presets such as `5m` or `1h` and compiles them to cron. It does not create a rolling interval anchored to creation time.
Interval schedules run once immediately by default; pass `--no-run-now` to wait for the first interval. Cron schedules wait for the next matching time; pass `--run-now` to fire once immediately.
Schedules default to UTC. Pass `--timezone <IANA>` to interpret cron fields in a local wall-clock time zone, for example `--timezone America/New_York`. The persisted `nextRunAt` is still a UTC instant, but it is computed from that local time zone so recurring jobs stay at the same local time across daylight saving time changes.
Schedules wait for the next matching cron time by default. Pass `--run-now` to start one immediate run on creation.
When targeting a remote daemon with `--host`, pass `--cwd`; your local working directory may not exist on the remote machine.

23
public-docs/schedules.md
View File

@@ -1,6 +1,6 @@
---
title: Schedules
description: Run Paseo agents on a schedule — every few minutes or on a cron.
description: Run fresh agents on cron schedules or wake an existing agent with a heartbeat.
nav: Overview
order: 25
category: Schedules
@@ -8,27 +8,28 @@ category: Schedules
# Schedules
A schedule runs an agent for you on a cadence: at this interval or cron time, run this prompt, in this repo, with this agent.
A schedule starts a new agent for you on a cron cadence: at this time, run this prompt, in this repo, with these agent settings.
The target can be:
Paseo also has **heartbeats**. A heartbeat sends a recurring prompt back into one existing agent so it can reassess and continue the same conversation.
- A new agent each run — fresh daily jobs and long-running watchers.
- An existing agent — when you want continuity.
- The agent that created the schedule — heartbeats from inside an agent.
Both concepts use the same cron engine, but their product surfaces stay separate:
Cadence is either an interval, like every 30 minutes, or a cron expression, like every weekday morning. Every run is recorded, and you can pause, resume, run once, update, or delete a schedule at any time.
- **Schedules** create a new agent each run. You can inspect, pause, resume, run once, update, or delete them.
- **Heartbeats** target one existing agent. They are intentionally lightweight: create or delete them over MCP; from the CLI you can also update only their cron period.
Cron is the canonical cadence. The CLI accepts simple presets such as `5m` or `1h`, but compiles them to cron rather than storing a separate interval type.
## What it's for
- **Overnight refactors:** wake an agent every 30 minutes to continue a scoped refactor, run checks, and leave notes.
- **Heartbeats:** have an agent periodically reassess state and keep moving.
- **Build babysitting:** check CI, EAS, Docker, or release builds until they pass.
- **Fresh recurring jobs:** start a clean agent for daily triage, reports, or maintenance.
- **Heartbeats:** have the current agent periodically reassess state and keep moving.
- **Build babysitting:** keep one agent checking CI, EAS, Docker, or release builds until they pass.
- **Daily triage:** scan issues, PRs, and failing checks every morning.
- **Maintenance sweeps:** refresh dependencies, audit docs, or clean stale branches.
## Ways to create one
- **In the app** — open the Schedules view and create one with an agent, a cadence, a repo, and a prompt. This is the main way to create and manage schedules.
- **In the app** — open the Schedules view and create one with agent settings, a cron cadence, a repo, and a prompt. This is the main way to create and manage schedules.
- **[From chat](/docs/schedules-chat)** — ask the agent in a chat and it sets the schedule up for you.
- **[From the CLI](/docs/schedules-cli)** — `paseo schedule create`, for headless boxes and scripts.
- **[Over MCP](/docs/mcp)** — agents create and manage schedules programmatically.

8
public-docs/skills.md
View File

@@ -23,22 +23,22 @@ When the desktop app finds installed Paseo skills, it keeps the bundled skills u
## `/paseo`, Paseo Reference
The foundational skill. Paseo reference for managing agents and worktrees. Load it when an agent needs to create agents, send them prompts, or manage worktrees.
The foundational skill. Paseo reference for managing agents and workspaces. Load it when an agent needs to create agents, send them prompts, or manage workspace isolation.
Not typically invoked directly by users, it's a reference that other skills depend on.
```
/paseo show me the Paseo CLI surface for creating an agent in a worktree
/paseo show me the Paseo CLI surface for creating an agent in a worktree-isolated workspace
```
## `/paseo-handoff`, Task Handoff
Hands off the current task to another agent with full context. Use it when you say "handoff", "hand off", "hand this to", or want to pass work to another agent.
The receiving agent gets a self-contained briefing with the task, context, relevant files, current state, what's been tried, decisions, acceptance criteria, and constraints. Provider comes from orchestration preferences unless you name one. Supports worktrees when you ask for one.
The receiving agent gets a self-contained briefing with the task, context, relevant files, current state, what's been tried, decisions, acceptance criteria, and constraints. Provider comes from orchestration preferences unless you name one. Supports worktree-isolated workspaces when you ask for one.
```
/paseo-handoff hand off the auth fix to codex in a worktree
/paseo-handoff hand off the auth fix to codex in a worktree-isolated workspace
/paseo-handoff hand this to claude opus for review
```

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.
- [Paseo tools](/docs/orchestration). Agents can drive Paseo themselves: create worktrees, spawn other agents, open terminals, and send prompts.
- [Paseo tools](/docs/orchestration). Agents can drive Paseo themselves: create isolated workspaces, spawn subagents, open terminals, and send prompts.
## What it isn't

20
public-docs/workspaces.md
View File

@@ -1,6 +1,6 @@
---
title: Workspaces
description: Understand Paseo's project, workspace, and session model before setting up agents or git worktrees.
description: Understand how Paseo groups working directories, agents, terminals, and browsers into workspaces.
nav: Workspaces
order: 10
category: Workspaces
@@ -35,14 +35,30 @@ That matters because real development rarely fits into one long chat. You might
In Paseo, the workspace is the stable container. The sessions are what you run inside it.
## Choose the isolation
Every workspace has an isolation mode:
- **Local** uses an existing directory, such as your main checkout. Use it when sessions should share the files already on disk.
- **Worktree** creates or opens a managed git worktree. Use it when a task needs its own directory and branch.
The workspace is the product concept; a git worktree is one way to isolate its files. More than one workspace can refer to the same managed worktree, and Paseo removes that worktree after its last workspace is archived.
## Creating a workspace
When you create a new workspace, Paseo creates a working directory for it. If you are using git, this is an isolated git worktree on its own branch, so agents can work in parallel without touching your main checkout. Paseo names the branch from your first prompt.
You can create a workspace in the app or from the CLI:
```bash
paseo workspace create --isolation local --path ~/dev/my-app --title main
paseo workspace create --isolation worktree --path ~/dev/my-app --base main
```
You can also create a workspace without starting an agent right away. The workspace is still there with its working directory ready; you can open terminals, run services, or browse files, then start an agent later.
Either way, once the workspace exists you can add more sessions to it. Open a terminal alongside an agent, start a second agent to review changes, or open a browser tab to check a local service. Every session lives as a tab inside the same workspace.
Creating an agent and creating a workspace are separate actions. Pass a workspace ID when you want an agent in a specific existing workspace. A bare `paseo run` from a human shell creates a new local workspace; when one agent runs it, Paseo recognizes the caller and creates a subagent in the caller's workspace.
## Worktrees
Every workspace in Paseo is backed by a working directory. When that directory is a git worktree, you get a separate branch and isolated environment for each task.

56
public-docs/worktrees.md
View File

@@ -16,12 +16,12 @@ This page covers the git-specific details: where worktrees live, how branches ar
## Layout and workflow
Worktrees live under `$PASEO_HOME/worktrees/` by default, grouped by a hash of the source checkout path. You can change the base directory with `worktrees.root` in `config.json`. Each worktree gets a random slug; the branch name is chosen when you first launch an agent.
Worktrees live under `$PASEO_HOME/worktrees/` by default, grouped by a hash of the source checkout path. You can change the base directory with `worktrees.root` in `config.json`. Each worktree gets a slug and a branch when its workspace is created.
```
~/.paseo/worktrees/
└── 1vnnm9k3/ # hash of source checkout path
├── tidy-fox/ # worktree slug (branch set on first agent)
├── tidy-fox/ # worktree slug
└── bold-owl/
```
@@ -35,10 +35,46 @@ With a custom root, Paseo keeps the same hashed layout under that directory:
}
```
1. Create a worktree, Paseo runs your setup hooks
2. Launch an agent, a branch is created or assigned
1. Create a workspace with worktree isolation, Paseo creates the worktree and runs your setup hooks
2. Launch one or more agents in that workspace
3. Review the diff against the base branch
4. Merge or archive, archive runs teardown and removes the directory
4. Merge or archive the workspace; after the last workspace using it is archived, Paseo runs teardown and removes the worktree
## Create a worktree-backed workspace
The examples below use the current directory as the source checkout. Pass `--path ~/dev/my-app` to create the workspace from another checkout.
Branch off from a base branch:
```bash
paseo workspace create \
--isolation worktree \
--mode branch-off \
--new-branch feature/auth \
--worktree-slug feature-auth \
--base main
```
Check out an existing branch:
```bash
paseo workspace create \
--isolation worktree \
--mode checkout-branch \
--branch feature/existing \
--worktree-slug existing-copy
```
Or open a pull request in its own workspace:
```bash
paseo workspace create \
--isolation worktree \
--mode checkout-pr \
--pr-number 2186
```
Add `--forge <name>` when Paseo cannot infer the forge from the source checkout.
## paseo.json
@@ -169,10 +205,12 @@ Services additionally get:
- `$PASEO_SERVICE_<NAME>_PORT` / `_URL`, peer service ports and URLs
- `$HOST`, `127.0.0.1` for local-only daemons, `0.0.0.0` when the daemon binds all interfaces
## CLI
## Manage the workspace
```bash
paseo run --worktree feature-auth --base main "implement auth"
paseo worktree ls
paseo worktree archive feature-auth
paseo workspace ls
paseo run --workspace <workspace-id> "implement auth"
paseo workspace archive <workspace-id>
```
For the common case, `paseo run --isolation worktree --base main "implement auth"` creates both the workspace and its first agent.