paseo

A reference for Paseo, a daemon that supervises AI coding agents on your machine and is controlled either through its tools or an equivalent CLI. It is meant to be loaded whenever you need to create agents, send them prompts, or manage git worktrees, and it documents the full surface for doing so.

Worktree operations include creating a worktree from a pull request, by branching off a base, or by checking out an existing branch, plus listing and archiving worktrees. Agent operations cover creating an agent with a relationship, workspace, title, provider, and initial prompt; sending follow-up prompts; updating runtime settings such as mode, model, and provider features; listing; and archiving. Relationship controls parentage (subagent versus detached) while workspace controls placement (current, existing, or a newly created directory or worktree). Provider discovery tools report available providers, models, and capabilities, and supported models include claude/sonnet as the default, claude/opus for harder reasoning, codex/gpt-5.4, and claude/haiku for tests.

The skill also documents schedules that start fresh agents on a cron cadence, heartbeats that send recurring prompts back to the conversation, and orchestration preferences stored at ~/.paseo/orchestration-preferences.json. It stresses that any skill must read that preferences file to resolve a provider rather than hardcoding one, and that agents run for a long time so asynchronous workflows are preferred: leave notify-on-finish enabled and wait for the notification instead of polling or calling wait_for_agent. A CLI mirrors the same surface for scripted use. Use it as the operational manual for orchestrating multiple coding agents and their worktrees.