Paseo Guide: Run Multiple AI Coding Agents in One Workspace
Run Claude Code, Codex, and OpenCode in parallel with Git worktrees, mobile relay, CLI, and orchestration using Paseo (paseo.sh). Full setup guide.
Table of Contents
- 1. What Is Paseo & Prerequisites
- 2. Three Ways to Install
- 3. Three Essential Terms: Project, Workspace & Session
- 4. Parallel Worktrees & paseo.json Setup
- 5. Reviewing Diffs, Mobile Relay & 7 Core CLI Commands
- 6. Multi-Agent Orchestration, Skills & Plugins
- 7. Troubleshooting Explorer
- 8. Frequently Asked Questions & Glossary
1. What Is Paseo & Prerequisites
Modern coding agents like Claude Code, Codex, OpenCode, and Gemini CLI edit files, run commands, and execute tests—but usually live trapped in isolated terminal windows. Run two tasks at once and it quickly becomes hard to track which branch, server, or output belongs where.
- Important: Paseo is not an AI model. It wraps the CLIs you already installed and logged into—preserving your existing subscriptions, MCP servers, and skills.
Prerequisites
| Requirement | Why You Need It |
|---|---|
| 1+ AI Coding CLI | Install and sign in to Claude Code, Codex, OpenCode, Pi, Antigravity, or Muse Code (claude or codex should work in your terminal first) |
| Git + Project Folder | Parallel execution relies on Git worktrees, making Git practically essential |
GitHub CLI (gh, recommended) | Enables PR-aware workspaces and PR workflows |
| Node.js (CLI install only) | Not required if using the Desktop app |
2. Three Ways to Install
Desktop App (★☆☆)100% recommended for beginners — daemon built in
“Download, open, and go”
- Install
- Download from paseo.sh/download or GitHub Releases
- Advantage
- Includes the background daemon—nothing extra to configure
- Mobile Pairing
- Settings → My Host → Pair Device → scan QR code
Server / CLI (★★☆)Headless servers & terminal-first workflows
“npm install -g @getpaseo/cli”
- Install
- Global npm install, then run paseo (data stored in ~/.paseo)
- Remote Access
- Encrypted QR relay, Tailscale, VPN, or SSH
- Optional Web UI
- Enable via paseo daemon config set features.webUi.enabled true
Docker / Self-Hosted (★★★)Always-on NAS & home servers
“ghcr.io/getpaseo/paseo:latest”
- Caveat
- Official image does not bundle AI CLIs—add your preferred CLIs
- Security
- Change PASEO_PASSWORD and put HTTPS (Caddy/Nginx) in front before exposing
- First Check
- Verify http://localhost:6767 works locally before configuring proxies
npm install -g @getpaseo/cli
paseo3. Three Essential Terms: Project, Workspace & Session
Paseo's sidebar is a list of places, not a list of chats. Remember Project > Workspace > Session (School → Classroom → Student):
- Project = School: Registers an existing Git repo or folder without copying it. Removing a project never deletes your local code.
- Workspace = Classroom (Room): A working folder where tasks happen. Starting a new chat keeps the room intact, and you can open terminals/browsers before inviting any AI.
- Session = Student (Tab): One running unit inside a workspace (AI chat, terminal, or browser tab). Sessions in the same room share files, not chat memory.
| Common Misconception | Reality |
|---|---|
| 1 Workspace = 1 Chat | False. A workspace is a room that can host multiple AI chats, terminals, and browser tabs simultaneously. |
| Archiving deletes my code | Local workspaces stay on disk. However, archiving the last worktree workspace cleans up its worktree folder—check uncommitted changes first. |
| New session inherits previous chat | It sees the same files, but starts with fresh context. Paste a summary or stay in the existing session to continue. |
4. Parallel Worktrees & paseo.json Setup
Suppose you want to build product sorting (sort-products) and login polish (login-polish) simultaneously in my-app:
- 1Create your first worktree workspace
New workspace → Isolation: New worktree → Base: origin/main → pick an agent (e.g., Claude Code). Your original main branch stays untouched.
- 2Give a clear goal + verification step
Prompt both what to build and how to verify (e.g., 'Add price/name sorting and run related tests').
- 3Spin up a second room for an unrelated task
Click my-app again to create login-polish with non-overlapping files (you can even pick a different AI model).
- 4Avoid port 3000 collisions with paseo.json
Define type: service using $PASEO_PORT so Paseo assigns free ports automatically and exposes clean URLs like web--sort-products--my-app.localhost:6767.
{
"worktree": {
"setup": "npm ci",
"teardown": "rm -rf .cache || true"
},
"scripts": {
"test": { "command": "npm test" },
"web": {
"command": "npm run dev -- --port $PASEO_PORT",
"type": "service"
}
}
}5. Reviewing Diffs, Mobile Relay & 7 Core CLI Commands
Verify Before Merging
- Inspect color-coded diffs in Changes (green = added, red = removed) and request tweaks inline.
- Add a second reviewer in the same room via New agent ("Review this diff without editing files"). Remember: a reviewer AI's approval is still an opinion—run
npm testin Terminal and verify visually in the built-in Browser tab before committing. - Use
Cmd+K(Ctrl+K) for Command Center and split-pane layout (chat left, code right).
Continue From Your Phone or Remote SSH
One daemon (default port 6767) backs every client:
- Mobile Relay: On desktop, open Settings → My Host → Pair a device → Enable relay and scan the QR code. Traffic is end-to-end encrypted with no VPN or port forwarding needed; close the app and your home PC keeps working.
- Tailscale / SSH: If relay is blocked, connect over Tailscale (
tailscale ip -4+ port6767) or attach to a remote server already running Paseo viassh://user@host.
7 Core Paseo CLI Commands
Services, Providers & Remote SSH
6. Multi-Agent Orchestration, Skills & Plugins
Let One AI Delegate to Another
- Enable Settings → My Host → Agents → Enable Paseo tools (off by default).
- Start a fresh session so the agent receives the tools.
- Ask your lead agent to spawn a reviewer subagent ("Spawn a second AI via Paseo to review this branch without editing files"). Save reusable Agent Profiles (model + effort + mode) so orchestrators pick the right worker automatically, or automate via Schedules and Heartbeats.
Four Built-In Orchestration Skills
Install via Settings → My Host → Agents → Orchestration skills or npx skills add getpaseo/paseo:
| Skill | When to Use |
|---|---|
/paseo | Core reference explaining how to control agents, workspaces, schedules, and heartbeats |
/paseo-handoff | Hands off work with files, progress, decisions, constraints, and done criteria |
/paseo-committee | Has two distinct AIs analyze a tough problem independently, then synthesizes |
/paseo-advisor | Gets a read-only second opinion on a plan or diff without touching files |
7. Troubleshooting Explorer
Always narrow down issues in this order: ① Is the daemon running? → ② Am I connected to the right daemon? → ③ Proxy & network.
- AI list is empty after installing Paseo· Setup · AI Detection
Paseo wraps existing CLIs. Run claude or codex once in your terminal to finish login, then reopen Paseo.
Quick Fix:Install & log in to CLI firstCategory:Setup - Diagnostics says 'command not found'· Setup · AI Detection
Check Settings → Host → Providers → Diagnostic and set agents.providers.<name>.command to the full binary path.
Quick Fix:Set absolute path in config.jsonCategory:Setup - 'Port already in use' in second workspace· Parallel · Ports · .env
Pass --port 3002 manually or define type: service with $PASEO_PORT in paseo.json for automatic port assignment.
Quick Fix:$PASEO_PORT + type: serviceCategory:Worktree - Dev server fails in new worktree (missing .env)· Parallel · Ports · .env
Add .env to .worktreeinclude in your repo root and commit it (ensure the built-in worktree-include plugin is enabled).
Quick Fix:Commit .worktreeincludeCategory:Worktree - Scanning QR code does nothing· Mobile · Tailscale · SSH
Relay is off by default. Enable it under Settings → My Host → Pair a device → Enable relay (CLI: paseo daemon pair).
Quick Fix:Turn on Enable relayCategory:Remote - Tailscale timeout or SSH refused by Paseo· Mobile · Tailscale · SSH
Verify Tailscale is active on both devices and use the daemon host IP. SSH never auto-starts the daemon—run paseo daemon start on the remote host first.
Quick Fix:tailscale ip -4 / paseo daemon startCategory:Remote - Blank/404 Web UI or page loads without connecting· Web UI · Proxy · Plugins
Enable features.webUi.enabled and restart the daemon. In Nginx, forward Upgrade/Connection headers, preserve Host, set proxy_buffering off, and raise timeouts (Caddy handles this by default).
Quick Fix:webUi.enabled + WebSocket headersCategory:Server - 403 Invalid Host header or HTTPS mixed content block· Web UI · Proxy · Plugins
Add your domain to daemon.hostnames (DNS rebinding protection), forward X-Forwarded-Proto: https, and configure daemon.trustedProxies if behind a non-loopback proxy.
Quick Fix:daemon.hostnames / X-Forwarded-ProtoCategory:Server - Config changes ignored or plugin missing from sidebar· Web UI · Proxy · Plugins
Restart the daemon after editing daemon.listen. For plugins, verify Enable plugins, running state, and check paseo plugin logs <name>.
Quick Fix:paseo reload / plugin logsCategory:Server
8. Frequently Asked Questions & Glossary
Q1. Does Paseo include Claude or Codex subscriptions?
Q2. Why don't my existing skills (like /grill-me) appear in Paseo's Orchestration skills card?
Q3. I created paseo.json, so why isn't worktree setup running?
Q4. What are the essential security rules for self-hosting Paseo?
Q5. Are Paseo plugins sandboxed?
Quick Glossary
| Term | Plain-English Meaning |
|---|---|
| Agent | An AI coding tool that edits files and runs terminal commands autonomously |
| Provider | Adapter rules connecting Paseo to a specific AI CLI |
| Daemon | Background engine (default port 6767) shared by Desktop, Mobile, and CLI |
| Worktree | Git feature creating an isolated folder and branch from the same repo |
| ACP / MCP | ACP standardizes AI client communication; MCP connects tools like subagent delegation |
| Orchestration | Coordinating multiple AIs on subtasks and synthesizing their results |
Validate paseo.json & config.json Locally with Hafuture
Format and syntax-check your Paseo worktree scripts and daemon JSON configs 100% locally in your browser with zero uploads.