Paseo reference for managing workspaces, workspace scripts, agents, schedules, and heartbeats.
Paseo is a daemon that supervises AI coding agents on your machine. Control it through tools or a CLI.
Workspaces
create_workspace — create a workspace independently of any agent. Required: isolation (local or worktree). Worktree isolation supports mode: "branch-off" | "checkout-branch" | "checkout-pr": use branchName/baseBranch for a new branch, branch for an existing branch, or prNumber plus optional forge/projectPath for a change request. worktreeSlug controls the managed path. Returns the workspace descriptor centered on workspaceId.
list_workspaces — list active workspaces.
archive_workspace — { workspaceId }. Archives the workspace, its agents, and its terminals. Local directories remain; Paseo removes an owned worktree only after its final active workspace reference is archived.
Worktree creation and reference accounting are implementation details of isolation: "worktree".
Workspace scripts
Configured paseo.json scripts use the same supervised lifecycle from tools and the CLI.
list_workspace_scripts — { workspaceId }. Lists configured scripts with lifecycle, service port, proxy URLs, health, exit code, and terminal ID.
start_workspace_script — { workspaceId, scriptName }. Starts one configured script through Paseo's managed workspace-script launcher and returns its status metadata.
stop_workspace_script — { workspaceId, scriptName }. Stops a running script through its supervised terminal and returns the stopped status metadata.
The matching CLI surface accepts either an explicit workspace ID or resolves the current directory:
paseo script ls [--cwd <path> | --workspace <workspace-id>]
paseo script start <name> [--cwd <path> | --workspace <workspace-id>]
paseo script stop <name> [--cwd <path> | --workspace <workspace-id>]
Agents
create_agent — required: title, provider (claude/opus, codex/gpt-5.4, …), initialPrompt. Optional: workspaceId, notifyOnFinish, settings, labels. Returns { agentId, workspaceId, … }.
Initial runtime settings live under settings: modeId, thinkingOptionId, and provider-specific features. For Codex fast mode, pass settings: { features: { "fast_mode": true } } when creating the agent.
Agent-scoped creation always creates your subagent. Omit workspaceId to use your current workspace; pass a workspace returned by create_workspace for isolated delegation. Placement never changes parentage.
Detach is an explicit user action in the subagents track, not an agent tool. A cross-workspace child remains your subagent even though it also appears as a normal tab in its workspace.
Agent-scoped create_agent defaults notifyOnFinish to true. Set it to false only for truly fire-and-forget agents.
send_agent_prompt — { agentId, prompt }. Use for follow-ups to an existing agent. Agent-scoped prompt calls default to background: true and notifyOnFinish: true; top-level calls default to blocking with no callback. For a synchronous follow-up, pass background: false and use the returned result.
update_agent — { agentId, name?, labels?, settings? }. Use settings for runtime changes on an existing agent: modeId, model, thinkingOptionId, and provider-specific features. For Codex fast mode, pass settings: { features: { "fast_mode": true } }.
list_agents — filter by cwd, statuses, sinceHours, includeArchived.
archive_agent — { agentId }. Interrupts if running, removes from active list.
Provider discovery
list_providers — compact provider availability and modes.
list_models — full model list for one provider. Use only when you need model IDs or thinking options; the list can be large.
inspect_provider — compact provider capability and feature inspection. Required: provider; pass cwd when you are not in an agent-scoped session. Optional: settings with draft model, modeId, thinkingOptionId, and features.
Only set feature IDs returned by inspect_provider. For Codex fast mode, look for fast_mode and pass settings: { features: { "fast_mode": true } } to create_agent or update_agent.
Schedules and heartbeats
create_schedule — starts a new agent on a cron cadence. Required: prompt, cron, provider. Optional: timezone, name, cwd, maxRuns, expiresIn. Use when the recurring work should live in fresh agents.
create_heartbeat — sends you a prompt on a cron cadence. Required: prompt, cron. Optional: timezone, name, maxRuns, expiresIn. Use for reminders, PR/build babysitting, and status checks that should return to this conversation.
delete_heartbeat stops it. MCP intentionally exposes no heartbeat update tool; delete and recreate when its task or cadence changes.
Schedules have the full list/inspect/update/pause/resume/run-once/log/delete surface. Heartbeats deliberately do not.
Orchestration preferences
User-specific configuration at ~/.paseo/orchestration-preferences.json. Before any Paseo skill chooses a provider or creates an agent, it must read this file. Reading means an actual file read, not relying on these examples or defaults. Never hardcode a provider string in another skill — resolve through this file.
Two parts:
providers— map of role categories to provider strings. Pass straight tocreate_agent'sproviderfield.preferences— freeform string array. Read on startup; weave into agent prompts contextually.
Categories: impl, ui, research, planning, audit. Skills pick the category that matches the role they're launching.
{
"providers": {
"impl": "codex/gpt-5.4",
"ui": "claude/opus",
"research": "codex/gpt-5.4",
"planning": "codex/gpt-5.4",
"audit": "codex/gpt-5.4"
},
"preferences": [
"Claude Opus is the right choice for anything artistic or human-skill-oriented: copywriting, naming, UX copy, visual design, styling. Codex is the workhorse for mechanical work."
]
}
If the file is missing, use sensible defaults and tell the user once.
All providers shown in this document are examples, you must resolve real providers either found in the preferences or by calling Paseo provider tooling to find a valid provider.
Waiting
Agents take time — 10–30+ minutes is routine. Favor asynchronous workflows.
For agent-scoped create_agent and background send_agent_prompt, leave notifyOnFinish omitted or set it to true unless the work is truly fire-and-forget. You will get notified when the target agent finishes, errors, or needs permission. Move on to other work. The notification arrives on its own.
Don't poll list_agents or get_agent_status to "check on" a running agent. The notification will tell you.
CLI semantics
The CLI and tools use the same ownership semantics even where their syntax differs:
paseo workspace create --isolation worktree --mode branch-off --new-branch fix-x --base main
paseo workspace create --isolation worktree --mode checkout-branch --branch existing-work
paseo workspace create --isolation worktree --mode checkout-pr --pr-number 42
paseo run --provider codex/gpt-5.4 --mode full-access --workspace <workspace-id> "<prompt>"
paseo run --provider codex/gpt-5.4 --mode full-access --new-workspace worktree --worktree-mode branch-off --new-branch fix-x --base main "<prompt>"
paseo send <agent-id> "<follow-up>"
paseo ls
paseo schedule create --cron "*/15 * * * *" "ping main build"
paseo heartbeat create --cron "*/15 * * * *" "check the build"
Discover with paseo --help and paseo <cmd> --help.
If paseo isn't on PATH but the desktop app is installed, the bundled CLI is at:
- macOS:
/Applications/Paseo.app/Contents/Resources/bin/paseo - Linux:
<install-dir>/resources/bin/paseo - Windows:
C:\Program Files\Paseo\resources\bin\paseo.cmd
The desktop app's first-run hook (installCli) symlinks this to ~/.local/bin/paseo (macOS/Linux) or drops a .cmd trampoline (Windows) and adds ~/.local/bin to PATH via shell rc files. If that didn't take, offer to symlink it — don't do it silently.
Ops and debugging
Daemon-client architecture: the daemon owns agent lifecycle, state, and the WebSocket API. Tools, CLI, mobile, and desktop apps are all clients.
| Default | |
|---|---|
| Listen address | 127.0.0.1:6767 (override PASEO_LISTEN) |
| Home | ~/.paseo (override PASEO_HOME) |
| Daemon log | $PASEO_HOME/daemon.log |
| Agent state | $PASEO_HOME/agents/<id>.json |
| Worktrees | $PASEO_HOME/worktrees/ (or worktrees.root in config.json) |
| PID file | $PASEO_HOME/paseo.pid |
| Health | GET http://127.0.0.1:6767/api/health |
Debug order:
tail -n 200 ~/.paseo/daemon.log.paseo daemon statusfor liveness.curl -s localhost:6767/api/healthif the CLI itself is suspect.
Never restart the daemon without explicit user approval — it kills every running agent, including, often, the one asking.
