Paseo: Parallel AI Agent Orchestration via Git Worktrees

Why Paseo: One Agent Is Not Enough

Paseo addresses the problem of running multiple AI coding agents simultaneously. Using separate terminal windows for each agent causes conflicts: agents overwrite each other's changes, and merge conflicts must be resolved manually. Paseo assigns each task an independent workspace backed by a separate git branch via git worktrees, enabling parallel execution without interference.

Comparison: Direct Agent CLI vs. Paseo

Simultaneous agents : Direct CLI supports 1; Paseo supports multiple in parallel.

Multi-provider switching : Direct CLI requires memorizing multiple command sets; Paseo provides a unified interface.

Task directory isolation : Direct CLI requires manual git branch creation; Paseo uses automatic worktree isolation.

Mobile progress viewing : Direct CLI not possible; Paseo offers iOS and Android apps.

Scheduled tasks : Direct CLI needs custom cron scripts; Paseo has built-in schedules.

The ability to run multiple agents in parallel is Paseo's core purpose; all other features orbit this capability.

What Is Paseo

Paseo is an open-source, self-hosted agentic development environment for running, orchestrating, and monitoring multiple AI programming agents in full parallelism. The official repository is getpaseo/paseo on GitHub ( https://github.com/getpaseo/paseo) and the website is paseo.sh ( https://paseo.sh). It provides four interfaces: desktop, web, mobile, and CLI.

Key Concepts

daemon : A persistent background process on the local machine listening on port 6767. Agents stay alive and ready to accept tasks at any time.

workspace : Organized around projects, not chats. Hierarchy: project → workspace → session.

worktree : Each task gets an independent git worktree and branch, enabling parallel execution without stepping on each other.

Multi-provider : Supports Claude Code, Codex CLI, Copilot, OpenCode, Pi, Muse, and others through a unified interface.

Cross-device : Mobile apps connect via an encrypted relay to view progress and approve actions.

Automation : Built-in schedules for timed tasks, MCP server, browser tools, and a plugin ecosystem.

The web UI shows a workspace list on the left and three entry points on the right: add project, import session, configure providers.

First Trial: Two Agents in Parallel

The author created a command-line calculator demo. Two agents worked in parallel: one implemented addition and multiplication, the other implemented division. Each operated in its own worktree with its own tests and reporting.

Results: both completed successfully (multiplication returned 42, division returned 5). The first merge was clean; the second produced a conflict that was resolved, verified, and archived. Worktrees were cleaned up automatically. The entire process required no window switching—the daemon stayed resident, agents ran in parallel, and the user only reviewed results and made decisions.

Behind the Hype: Iteration Velocity

Release Timeline

2025-10-13: Repository created.

2026-02-11: First public release v0.1.2.

2026-04: 46 releases in a single month (peak).

2026-06 ~ 08: 23-24 releases per month.

2026-10-09: v0.11.2 (current latest).

Eight months, roughly 200 releases. A cadence of 20+ releases per month signals an active author, living community, and evolving protocol—arguably the most important indicator when choosing a tool.

Mobile Connection

Agents run on your machine; you can command them from any device. Paseo's connection model involves three roles: daemon (local persistent service), client (desktop, mobile, browser, CLI), and relay (relay server).

When the phone is outside and the daemon is at home, the relay bridges the gap. The daemon initiates an outbound connection to the relay server—no inbound ports need to be opened. Traffic is end-to-end encrypted; the relay sees only IP addresses, timing, and message sizes, never content.

Pairing Process

Pairing is the critical step: paseo daemon pair The terminal prints a QR code. Scanning it with the mobile app establishes the trust relationship.

Under the hood, the daemon generates a persistent ECDH key pair. The QR code delivers the daemon's public key to the phone. Before the handshake completes, the daemon accepts no commands. Both sides use Curve25519 for the encrypted channel, with payloads protected by XSalsa20-Poly1305.

The official relay server is open source, designed with a "relay is untrusted" threat model—it cannot decrypt content.

Note : The pairing QR code is the trust anchor. Official documentation states: treat it like a password; do not share publicly. Anyone with the QR code can pair with your daemon.

Alternative Connection Methods

relay : No open port required; end-to-end encryption; best for user away from machine.

SSH : No open port required; SSH encryption; best for machines accessible via SSH.

Tailscale : No open port required; WireGuard encryption; best for multiple devices at home.

Getting Started

npm install -g @getpaseo/cli

First, install and log in to an agent CLI (Claude Code, Codex, or OpenCode). Then start the daemon: paseo daemon start Run the first task:

paseo run --provider claude "Reply with exactly one line: paseo-smoke-ok"

The author has compiled the full learning path into a 10-chapter guide, Paseo Introduction (Chinese: 《Paseo 入门"), covering installation through automation, all hands-on tested. The PDF is available at

https://github.com/smallnest/ebooks/blob/2cebe755ea1eac02b030cca7405250b7b84c80f2/paseo.pdf

.

References

getpaseo/paseo: https://github.com/getpaseo/paseo paseo.sh: https://paseo.sh Paseo Introduction :

https://github.com/smallnest/ebooks/blob/2cebe755ea1eac02b030cca7405250b7b84c80f2/paseo.pdf