paseo

Paseo is a local-first agent orchestration daemon that lets developers run multiple AI coding agents simultaneously across any device. A local Node.js server (the daemon) spawns and manages agent processes on your machine, streaming real-time output over WebSocket to whichever client you prefer — the iOS/Android app, the Electron desktop app, the web client, or the CLI.

Rather than lock you into a single AI provider, Paseo treats Claude Code, Codex, GitHub Copilot, OpenCode, and Pi as interchangeable providers. You dispatch tasks to whichever model fits the job, run them in parallel across worktrees, attach to live output, and send follow-up prompts without leaving your workflow. Voice control lets you dictate tasks hands-free or talk through a problem while the agent implements it.

The daemon exposes an MCP server that agents themselves can use to spawn sub-agents, creating fully autonomous multi-agent pipelines. Structured loop mode lets you define acceptance criteria and have an agent iterate until it passes — optionally with a separate verifier agent evaluating each attempt. Everything runs entirely on your machine with no telemetry, no forced sign-in, and no code leaving your environment.

Paseo ships as a desktop app that bundles and manages the daemon automatically, making setup a single download. For servers and headless environments the CLI installs via npm and presents a QR code that any mobile client can scan to connect remotely over an optional encrypted relay.

What You Get

• Local daemon that spawns, monitors, and streams output from multiple AI coding agents simultaneously across all your devices
• Cross-platform clients: iOS app, Android app, Electron desktop app, web client, and a full-featured CLI — all sharing the same WebSocket protocol
• Multi-provider support: Claude Code, Codex, GitHub Copilot, OpenCode, and Pi through a unified interface with per-task provider selection
• Voice control for dictating tasks, giving follow-up instructions, or talking through problems hands-free using local or cloud speech processing
• Worktree-aware agent dispatch so parallel agents work on isolated branches without conflicting with each other
• Loop mode with configurable acceptance criteria and optional verifier agent, enabling autonomous retry cycles until the task passes
• Built-in MCP server that agents can use to spawn sub-agents, enabling fully autonomous multi-agent orchestration pipelines
• Remote access via an optional encrypted relay so you can connect from your phone to agents running on a workstation behind a firewall

Common Use Cases

• Parallel feature development — dispatch separate agents to different worktrees so frontend, backend, and test work happen simultaneously without merge conflicts
• Cross-provider experimentation — run the same prompt on Claude Code and Codex side-by-side to compare output quality and cost before committing to one approach
• Hands-free coding on mobile — dictate implementation tasks to an agent via voice while commuting, then review and approve the diff from your phone
• Automated loop workflows — configure an agent to implement a feature and loop until CI passes, with a verifier agent evaluating each attempt
• Remote machine management — install the daemon headlessly on a powerful workstation and connect from a laptop or phone via the encrypted relay
• Multi-agent committee review — use the built-in skills to spin up two contrasting agents to do root cause analysis and produce a plan before implementation

Under The Hood

Architecture Paseo follows a strict client-server separation built around a local daemon process that acts as the central authority for all agent state. The daemon uses a layered architecture: a WebSocket server handles connection management and binary frame routing, sessions encapsulate per-client subscriptions and terminal state, and an agent manager runs a well-defined lifecycle state machine tracking every agent from creation through archival. Agent output is modeled as an append-only timeline of typed events rather than a raw log, which decouples producers (the agent processes) from consumers (any number of simultaneously connected clients). Workspace management introduces a parallel layer of abstractions for git worktrees, workspace registries, and workspace-scoped script runtimes, each with clearly bounded responsibilities. The loop service and schedule service sit above the agent manager as higher-order orchestrators that compose the core agent lifecycle primitives. This layered, event-driven design means adding a new client surface or agent provider requires touching only the relevant adapter layer, leaving the core state machine stable.

Tech Stack The daemon and CLI are written in TypeScript running on Node.js, with the WebSocket layer implemented using the ws library and structured around a custom binary frame protocol for efficient streaming. Agent provider adapters wrap the Anthropic Claude Agent SDK, OpenAI Codex Server, GitHub Copilot ACP, and others behind a shared provider interface defined in the protocol package. Zod handles runtime schema validation throughout the server, and Ajv validates structured JSON generation output from agents. The mobile and web client are built with Expo (React Native) targeting iOS, Android, and web from a single codebase. The Electron desktop app wraps the Expo web export and bundles the daemon as a managed subprocess. Vitest drives unit and end-to-end testing with Playwright covering browser-based e2e scenarios. Tooling uses oxlint for linting and oxfmt for formatting, both significantly faster than their ESLint and Prettier equivalents.

Code Quality The codebase demonstrates a strong commitment to correctness through extensive testing: the server package alone contains over 300 test files, including unit tests, integration tests, and dedicated end-to-end test suites covering daemon client behavior, workspace lifecycle edge cases, worktree operations, and relay reconnection scenarios. Error handling follows explicit typed patterns throughout — custom error classes like StructuredAgentResponseError and StructuredAgentFallbackError carry structured context rather than relying on generic error messages, and Zod schemas enforce the shape of all externally-consumed data. TypeScript strict mode is enabled across all packages. The monorepo uses lefthook for pre-commit hooks and oxlint for lint enforcement. The protocol package serves as a shared source of truth for wire types, preventing the drift between client and server type definitions that commonly plagues WebSocket applications. Naming and module boundaries are consistent and self-documenting, with thorough inline documentation in complex areas like the agent manager lifecycle and binary frame codec.

What Makes It Unique Paseo’s most technically distinctive contribution is treating the AI coding agent as a first-class managed process rather than a one-shot CLI invocation. The daemon’s timeline model — an append-only, typed event stream per agent — enables arbitrary numbers of clients to subscribe to the same agent’s live output without any client being “the” terminal. The built-in MCP server that agents themselves can call to spawn sub-agents is a particularly novel design: it means orchestration logic can live inside an agent’s own reasoning loop rather than requiring external scripting. The loop service’s combination of a shell-command verifier and an optional verifier agent provides a pragmatic bridge between deterministic CI-style acceptance criteria and AI-evaluated qualitative criteria, something few orchestration tools expose as a first-class primitive. Finally, the encrypted relay architecture — where neither the relay server nor any intermediate node can decrypt the agent stream — sets a privacy bar rarely seen in developer tooling that involves remote access.

Self-Hosting

Paseo is released under the GNU Affero General Public License v3 (AGPL-3.0). In plain terms this means you can use, modify, and self-host the software freely, but if you distribute a modified version or run it as a network service others access, you must also publish your modifications under the same license. For most teams self-hosting an internal instance, this has no practical impact. Commercial use on a private internal server is permitted. The AGPL obligation only triggers if you expose a modified Paseo to external users as a service.

Running Paseo yourself is straightforward for the desktop scenario — the app bundles the daemon and manages it automatically. For headless or server deployments you install the CLI via npm, point it at a home directory, and it starts listening. You are responsible for keeping the daemon process running (a process supervisor like systemd or PM2), for applying updates as new releases ship (the project averages multiple releases per week), and for securing the WebSocket port if exposed beyond localhost. The relay package is available for remote access without exposing ports directly, and a community-maintained self-hosted relay in Go exists for teams who want to run their own relay infrastructure.

At the moment Paseo has no commercial or cloud-hosted tier — the project is fully open source with no paid add-ons. This means there is no managed hosting, no enterprise SLA, no cloud-backed agent history, and no vendor support. All of these responsibilities fall on you. The trade-off is complete privacy: no telemetry, no forced sign-in, no code or prompts leaving your infrastructure. For teams comfortable running their own Node.js services, the operational burden is modest; for teams expecting a managed SaaS experience, Paseo currently requires self-sufficiency.