From 5e7a51364dfff963ee68648c6dfded8df616a470 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Sun, 26 Apr 2026 18:38:24 +0700 Subject: [PATCH] docs(skill): rewrite paseo skill MCP-first Replace CLI-only reference with tool-first reference covering worktree, agent, and schedule tools. Add CLI parity section, desktop CLI fallback paths, and ops/debugging notes. --- skills/paseo/SKILL.md | 302 ++++++++++-------------------------------- 1 file changed, 70 insertions(+), 232 deletions(-) diff --git a/skills/paseo/SKILL.md b/skills/paseo/SKILL.md index 115b783a3..eaeb14c87 100644 --- a/skills/paseo/SKILL.md +++ b/skills/paseo/SKILL.md @@ -1,249 +1,87 @@ --- name: paseo -description: Paseo CLI reference for managing agents. Load this skill whenever you need to use paseo commands. +description: Paseo reference for managing agents and worktrees. Load whenever you need to create agents, send them prompts, or manage worktrees. --- -## Agent Commands +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`), `background` (default `false` — blocks until completion or permission), `notifyOnFinish`. Returns `{ agentId, … }`. + +Compose: call `create_worktree` first, then `create_agent` with `cwd` set to the returned `worktreePath`. + +**`send_agent_prompt`** — `{ agentId, prompt }`. Blocks by default; pass `background: true` to fire-and-forget. + +**`list_agents`** — filter by `cwd`, `statuses`, `sinceHours`, `includeArchived`. + +**`archive_agent`** — `{ agentId }`. Interrupts if running, removes from active list. + +## Heartbeats + +**`create_schedule`** — required: `prompt`. Pick one of `cron` or `every` (`"5m"`, `"1h"`). Optional: `name`, `target` (`self` | `new-agent`), `provider`, `maxRuns`, `expiresIn`. Use for periodic checks on long-running work or recurring maintenance. + +## Models + +`claude/sonnet` (default), `claude/opus` (harder reasoning), `codex/gpt-5.4` (frontier coding), `claude/haiku` (tests only). + +## Waiting + +`create_agent` and `send_agent_prompt` block by default — trust them. Real tasks take 10–30+ minutes routinely. Don't poll `list_agents` or `get_agent_status` to "check on" a blocking call. To work in parallel, pass `background: true` and call `wait_for_agent` later. + +## CLI parity + +The `paseo` CLI is a thin wrapper over the same daemon. Same surface: ```bash -# List agents (directory-scoped by default) -paseo ls # Only shows agents for current directory -paseo ls -g # All agents across all projects (global) -paseo ls --json # JSON output for parsing - -# Create and run an agent (blocks until completion by default, no timeout) -paseo run --mode bypassPermissions "" -paseo run --mode bypassPermissions --name "task-name" "" -paseo run --mode bypassPermissions --provider claude/opus "" -paseo run --mode full-access --provider codex/gpt-5.4 "" - -# Wait timeout - limit how long run blocks (default: no limit) -paseo run --wait-timeout 30m "" # Wait up to 30 minutes -paseo run --wait-timeout 1h "" # Wait up to 1 hour - -# Detached mode - runs in background, returns agent ID immediately -paseo run --detach "" -paseo run -d "" # Short form - -# Structured output - agent returns only matching JSON -paseo run --output-schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' "" -# NOTE: --output-schema blocks until completion (cannot be used with --detach) - -# Worktrees - isolated git worktree for parallel feature development -paseo run --worktree feature-x "" - -# Check agent logs/output -paseo logs -paseo logs -f # Follow (stream) -paseo logs --tail 10 # Last 10 entries -paseo logs --filter tools # Only tool calls - -# Wait for agent to complete or need permission -paseo wait -paseo wait --timeout 60 # 60 second timeout - -# Send follow-up prompt to running agent -paseo send "" -paseo send --image screenshot.png "" # With image -paseo send --no-wait "" # Queue without waiting - -# Inspect agent details -paseo inspect - -# Interrupt an agent's current run -paseo stop - -# Archive an agent (soft-delete, removes from UI) -paseo archive -paseo archive --force # Force archive running agent (interrupts first) - -# Hard-delete an agent (interrupts first if needed) -paseo delete - -# Attach to agent output stream (Ctrl+C to detach without stopping) -paseo attach - -# Permissions management -paseo permit ls # List pending permission requests -paseo permit allow # Allow all pending for agent -paseo permit deny --all # Deny all pending - -# Output formats -paseo ls --json # JSON output -paseo ls -q # IDs only (quiet mode, useful for scripting) +paseo run --provider codex/gpt-5.4 --mode full-access --worktree feat/x "" +paseo send "" +paseo ls +paseo worktree ls +paseo schedule create --every 5m "ping main build" ``` -## Loop Commands +Discover with `paseo --help` and `paseo --help`. -Iterative worker loops: launch a worker agent, verify its output, repeat until done. +**If `paseo` isn't on PATH but the desktop app is installed**, the bundled CLI is at: -```bash -# Start a loop -paseo loop run "" [options] - --verify "" # Verifier agent prompt - --verify-check "" # Shell command that must exit 0 (repeatable) - --name # Optional loop name - --sleep # Delay between iterations (30s, 5m) - --max-iterations # Maximum number of iterations - --max-time # Maximum total runtime (1h, 30m) - --provider # Worker agent provider/model (e.g. codex/gpt-5.4) - --verify-provider # Verifier agent provider/model (e.g. claude/opus) - --archive # Archive agents after each iteration +- macOS: `/Applications/Paseo.app/Contents/Resources/bin/paseo` +- Linux: `/resources/bin/paseo` +- Windows: `C:\Program Files\Paseo\resources\bin\paseo.cmd` -# Manage loops -paseo loop ls # List all loops -paseo loop inspect # Show loop details and iterations -paseo loop logs # Stream loop logs -paseo loop stop # Stop a running loop -``` +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. -## Schedule Commands +## Ops and debugging -Recurring time-based execution: run a prompt on a cron or interval schedule. +Daemon-client architecture: the daemon owns agent lifecycle, state, and the WebSocket API. Tools, CLI, mobile, and desktop apps are all clients. -```bash -# Create a schedule -paseo schedule create "" [options] - --every # Fixed interval (5m, 1h) - --cron # Cron expression - --name # Optional schedule name - --target # Run target - --max-runs # Maximum number of runs - --expires-in # Time to live for schedule +| | 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/.json` | +| Worktrees | `$PASEO_HOME/worktrees/` | +| PID file | `$PASEO_HOME/paseo.pid` | +| Health | `GET http://127.0.0.1:6767/api/health` | -# Manage schedules -paseo schedule ls # List schedules -paseo schedule inspect # Inspect a schedule -paseo schedule logs # Show recent run logs -paseo schedule pause # Pause a schedule -paseo schedule resume # Resume a paused schedule -paseo schedule delete # Delete a schedule -``` +Debug order: -## Chat Commands +1. `tail -n 200 ~/.paseo/daemon.log`. +2. `paseo daemon status` for liveness. +3. `curl -s localhost:6767/api/health` if the CLI itself is suspect. -Asynchronous agent coordination through persistent chat rooms. - -```bash -# Create a chat room -paseo chat create --purpose "" - -# List and inspect rooms -paseo chat ls -paseo chat inspect - -# Post a message -paseo chat post "" -paseo chat post "" --reply-to -paseo chat post "@ " -paseo chat post "@everyone " - -# Read messages -paseo chat read -paseo chat read --limit -paseo chat read --since -paseo chat read --agent - -# Wait for new messages -paseo chat wait -paseo chat wait --timeout - -# Delete a room -paseo chat delete -``` - -## Terminal Commands - -Manage workspace terminals: create, inspect, send keystrokes, capture output. - -```bash -# List terminals (scoped to current directory by default) -paseo terminal ls # Terminals in current directory -paseo terminal ls --all # All terminals across all workspaces -paseo terminal ls --cwd ~/dev/myapp # Terminals in a specific directory - -# Create a terminal -paseo terminal create # In current directory -paseo terminal create --cwd ~/dev/myapp # In a specific directory -paseo terminal create --name "build-runner" # With a custom name - -# Kill a terminal (supports short ID prefixes and name matching) -paseo terminal kill -paseo terminal kill abc123 # Short prefix -paseo terminal kill build-runner # By name - -# Capture terminal output as plain text (like tmux capture-pane -p) -paseo terminal capture # Visible pane only, ANSI stripped -paseo terminal capture --scrollback # Full scrollback + visible -paseo terminal capture -S # Short form of --scrollback -paseo terminal capture --start 0 --end 10 # Line range (tmux-style) -paseo terminal capture --start -5 # Last 5 lines -paseo terminal capture --ansi # Preserve ANSI escape codes -paseo terminal capture --json # JSON output with metadata - -# Send keystrokes (like tmux send-keys) -paseo terminal send-keys "ls -la" Enter -paseo terminal send-keys "echo hello" Enter -paseo terminal send-keys C-c # Ctrl+C -paseo terminal send-keys C-d # Ctrl+D -paseo terminal send-keys --literal "raw text" # No special token interpretation -``` - -**Special key tokens** (interpreted by default, use `--literal` to send raw): -`Enter`, `Tab`, `Escape`, `Space`, `BSpace`, `C-c`, `C-d`, `C-z`, `C-l`, `C-a`, `C-e` - -**Common pattern — launch a process and interact with it:** - -```bash -id=$(paseo terminal create --name "my-shell" -q) -paseo terminal send-keys "$id" "claude" Enter -sleep 5 -paseo terminal capture "$id" --scrollback # See what happened -paseo terminal send-keys "$id" "Hello!" Enter -sleep 10 -paseo terminal capture "$id" --scrollback # See the response -paseo terminal send-keys "$id" "/exit" Enter -paseo terminal kill "$id" -``` - -## Available Models - -**Claude (default provider):** - -- `--provider claude/haiku` — Fast/cheap, ONLY for tests (not for real work) -- `--provider claude/sonnet` — Good for most tasks -- `--provider claude/opus` — For harder reasoning, complex debugging - -**Codex:** - -- `--provider codex/gpt-5.4` — Latest frontier agentic coding model (preferred for all engineering tasks) -- `--provider codex/gpt-5.4-mini` — Cheaper, faster, but less capable - -## Permissions - -Always launch agents fully permissioned. Use `--mode bypassPermissions` for Claude and `--mode full-access` for Codex. Always specify the model: `--provider claude/opus`, `--provider codex/gpt-5.4`, etc. Control behavior through **strict prompting**, not permission modes. - -## Waiting for Agents - -Both `paseo run` and `paseo wait` block until the agent completes. Trust them. - -- `paseo run` waits **forever** by default (no timeout). Use `--wait-timeout` to set a limit. -- `paseo wait` also waits forever by default. Use `--timeout` to set a limit. -- Agent tasks can legitimately take 10, 20, or even 30+ minutes. This is normal. -- When a wait times out, **just re-run `paseo wait `** — don't panic, don't start checking logs. -- Do NOT poll with `paseo ls`, `paseo inspect`, or `paseo logs` in a loop to "check on" the agent. -- **Never launch a duplicate agent** because a wait timed out. The original is still running. - -## Composing Agents in Bash - -`paseo run` blocks by default and `--output-schema` returns structured JSON, making it easy to compose agents in bash loops and pipelines. - -**Detach + wait pattern for parallel work:** - -```bash -api_id=$(paseo run -d --name "impl-api" "implement the API" -q) -ui_id=$(paseo run -d --name "impl-ui" "implement the UI" -q) - -paseo wait "$api_id" -paseo wait "$ui_id" -``` +**Never restart the daemon without explicit user approval** — it kills every running agent, including, often, the one asking.