Paseo
Spin up isolated git worktrees and supervised Claude or Codex agents through the Paseo daemon without juggling manual CLI setup.
Overview
Paseo is an agent skill for the Build phase that documents how to create git worktrees and supervised coding agents via the Paseo daemon tools.
Install
npx skills add https://github.com/getpaseo/paseo --skill paseoWhat is this skill?
- create_worktree supports PR checkout, branch-off, and ref checkout with branchName and worktreePath returned
- create_agent wires title, provider (claude/opus, codex/gpt-5.4), initialPrompt, cwd, notifyOnFinish, and Codex fast_mode
- Compose flow: create_worktree then create_agent with cwd set to worktreePath
- Subagent model: detached false by default for advisors, planners, implementers, and auditors
- list_worktrees and archive_worktree manage repo-scoped isolation and cleanup
- Three create_worktree modes: PR, branch-off, and checkout ref
Adoption & trust: 1.2k installs on skills.sh; 8k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want parallel agent runs on separate branches without manually managing worktrees, providers, and agent lifecycles on your machine.
Who is it for?
Solo builders running multiple Claude or Codex agents against different branches or PRs on one repo.
Skip if: Teams that only need a single-agent chat in one checkout with no git isolation or local daemon.
When should I use this skill?
You need to create agents, send them prompts, or manage worktrees with Paseo.
What do I get? / Deliverables
You can create an isolated worktree, start a configured agent on that path, and archive finished worktrees with consistent tool parameters.
- Isolated worktree path and branch name
- Running agent session with agentId
- Archived worktree and removed branch when done
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Agent orchestration and parallel worktrees are core to how solo builders scale coding with multiple agents during implementation. Paseo is reference documentation for daemon tools that create worktrees and agents—the canonical shelf is agent-tooling, not a single app layer.
Where it fits
Branch off main into fix/foo, spawn an implementer agent on the returned worktreePath, and keep a planner as a subagent.
Checkout a GitHub PR into a worktree and run an auditor agent with notifyOnFinish before you merge.
List active worktrees and archive_worktree by slug after agents complete follow-up fixes.
How it compares
Local agent supervisor with worktree primitives—not a hosted CI runner or a generic MCP catalog entry.
Common Questions / FAQ
Who is paseo for?
Indie and solo developers who orchestrate Claude Code or Codex agents locally and want documented Paseo tool calls for worktrees and agent creation.
When should I use paseo?
During Build when implementing features in parallel worktrees, during Ship when agents fix PR feedback in isolated checkouts, and during Operate when you list or archive stale agent worktrees.
Is paseo safe to install?
Review the Security Audits panel on this Prism page and treat any daemon with filesystem and git access as high-trust before enabling it on sensitive repos.
SKILL.md
READMESKILL.md - Paseo
Paseo is a daemon that supervises AI coding agents on your machine. Control it through tools or a CLI. ## Worktrees **`create_worktree`** — three modes: - From a PR: `{ githubPrNumber: 503 }`. - Branch off a base: `{ action: "branch-off", branchName: "fix/foo", baseBranch: "main" }`. - Checkout an existing ref: `{ action: "checkout", refName: "feat/bar" }`. Returns `{ branchName, worktreePath }`. Pass `cwd` to target a specific repo. **`list_worktrees`** — current repo (or pass `cwd`). **`archive_worktree`** — `{ worktreePath }` or `{ worktreeSlug }`. Removes worktree and branch. ## Agents **`create_agent`** — required: `title`, `provider` (`claude/opus`, `codex/gpt-5.4`, …), `initialPrompt`. Common: `cwd` (often a `worktreePath`), `notifyOnFinish`, `settings`, `detached`. Returns `{ agentId, … }`. 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. Compose: call `create_worktree` first, then `create_agent` with `cwd` set to the returned `worktreePath`. ### Agent relationships Agents you create default to **your subagents**: omit `detached` or pass `detached: false`. Use this for advisors, committee members, planners, implementers, auditors, loop workers, and any agent whose lifetime belongs to your task. Subagents appear under you and are archived with you. Pass `detached: true` only when the agent you create should stand on its own, not help you finish your task. Use this for handoffs and fire-and-forget delegations the user may continue after you are archived. Detached agents do not appear in your subagent track and are not archived with you. For subagents, leave `notifyOnFinish` omitted or set it to `true`. You will get notified when the created agent finishes, errors, or needs permission. Set `notifyOnFinish: false` only when the created agent is truly fire-and-forget and you do not need to follow up. **`send_agent_prompt`** — `{ agentId, prompt }`. Use for follow-ups to an existing agent. **`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. ## Models `claude/sonnet` (default), `claude/opus` (harder reasoning), `codex/gpt-5.4` (frontier coding), `claude/haiku` (tests only). ## Orch