hafuture

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.

PaseoAI Coding AgentsClaude CodeCodexGit WorktreeOrchestrationDeveloper Tools

Table of Contents


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

RequirementWhy You Need It
1+ AI Coding CLIInstall and sign in to Claude Code, Codex, OpenCode, Pi, Antigravity, or Muse Code (claude or codex should work in your terminal first)
Git + Project FolderParallel 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

Choose Your Paseo Installation Method
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
bash
npm install -g @getpaseo/cli
paseo
Starts the daemon and asks whether to enable the encrypted relay (QR pairing). Local data lives under PASEO_HOME (default ~/.paseo).

3. 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 MisconceptionReality
1 Workspace = 1 ChatFalse. A workspace is a room that can host multiple AI chats, terminals, and browser tabs simultaneously.
Archiving deletes my codeLocal workspaces stay on disk. However, archiving the last worktree workspace cleans up its worktree folder—check uncommitted changes first.
New session inherits previous chatIt 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:

  1. 1
    Create 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.

  2. 2
    Give a clear goal + verification step

    Prompt both what to build and how to verify (e.g., 'Add price/name sorting and run related tests').

  3. 3
    Spin 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).

  4. 4
    Avoid 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.

json
{
  "worktree": {
    "setup": "npm ci",
    "teardown": "rm -rf .cache || true"
  },
  "scripts": {
    "test": { "command": "npm test" },
    "web": {
      "command": "npm run dev -- --port $PASEO_PORT",
      "type": "service"
    }
  }
}
Paseo reads paseo.json committed on your base branch (origin/main). Omit hardcoded port numbers and use $PASEO_PORT for automatic allocation.

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 test in 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 + port 6767) or attach to a remote server already running Paseo via ssh://user@host.
Click any Paseo CLI command to copy

7 Core Paseo CLI Commands

Services, Providers & Remote SSH


6. Multi-Agent Orchestration, Skills & Plugins

Let One AI Delegate to Another

  1. Enable Settings → My Host → Agents → Enable Paseo tools (off by default).
  2. Start a fresh session so the agent receives the tools.
  3. 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:

SkillWhen to Use
/paseoCore reference explaining how to control agents, workspaces, schedules, and heartbeats
/paseo-handoffHands off work with files, progress, decisions, constraints, and done criteria
/paseo-committeeHas two distinct AIs analyze a tough problem independently, then synthesizes
/paseo-advisorGets 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.

Paseo Troubleshooting Reference9 items
  • 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?
No. Paseo is a workspace shell that runs the AI coding CLIs you already installed and authenticated. Your existing subscriptions, API keys, MCP servers, and skills remain unchanged.
Q2. Why don't my existing skills (like /grill-me) appear in Paseo's Orchestration skills card?
That's expected. Paseo's card only manages its 4 built-in /paseo skills. Existing Claude Code skills stay managed by Claude Code (~/.claude/skills/) and work automatically whenever you pick Claude Code as your workspace provider.
Q3. I created paseo.json, so why isn't worktree setup running?
In 90% of cases, paseo.json hasn't been committed yet. Paseo reads paseo.json and .worktreeinclude from the committed base branch (usually origin/main).
Q4. What are the essential security rules for self-hosting Paseo?
Always set a password via paseo daemon set-password (or PASEO_PASSWORD) before binding beyond localhost, and place an HTTPS reverse proxy (Caddy/Nginx) plus daemon.hostnames allowlist in front when exposing over untrusted networks.
Q5. Are Paseo plugins sandboxed?
No—plugins execute unisolated with daemon account privileges and full app UI access. Install only plugins from sources you trust completely.

Quick Glossary

TermPlain-English Meaning
AgentAn AI coding tool that edits files and runs terminal commands autonomously
ProviderAdapter rules connecting Paseo to a specific AI CLI
DaemonBackground engine (default port 6767) shared by Desktop, Mobile, and CLI
WorktreeGit feature creating an isolated folder and branch from the same repo
ACP / MCPACP standardizes AI client communication; MCP connects tools like subagent delegation
OrchestrationCoordinating 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.

Open JSON Formatter