paseo

Paseo is a remote daemon that manages coding agents, terminals. Control it through MCP tools or the CLI.

Projects

Manage the daemon's project registry through the CLI:

paseo project create [path]
paseo project ls
paseo project rename <project-id> <name>
paseo project rename <project-id> --reset
paseo project delete <project-id>

For a local daemon, project create defaults to the current directory and resolves relative paths on the CLI machine. With --host or PASEO_HOST, always provide a path; the target daemon interprets it on its own machine. Deleting a project archives its active workspaces and removes the project from Paseo without deleting the project directory.

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 for a change request. Use path for a local directory or source checkout and projectId for the owning project; when no path is supplied, a worktree may resolve its source from projectId. worktreeSlug controls the managed path. Returns the workspace descriptor centered on workspaceId.

background: true hides a workspace from default lists and the sidebar while its contents remain durable and accessible; omit background to inherit your current workspace’s value (false without a caller), and override it only when the user explicitly asks.

Choose baseBranch explicitly: origin/main selects the remote-tracking branch; refs/heads/main selects local main. Bare main prefers local main when it exists, otherwise origin/main. Paseo retains the resolved ref for workspace comparisons, even after rebasing the branch or changing its PR target.

list_workspaces — list active workspaces, excluding background workspaces unless includeBackground: true.

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.

rename_workspace — { workspaceId, name }. Rename workspace.

Workspace scripts

Configured paseo.json scripts use the same supervised lifecycle from tools and the CLI.