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/mcp.md
+50 -31
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