paseo README

The project's README from github.com/getpaseo/paseo. As one markdown file: README.md.

Paseo logo

Paseo

English · 简体中文 · 日本語 · 한국어

GitHub stars GitHub release X Discord Reddit

One interface for Claude Code, Codex, Copilot, OpenCode, and Pi agents.

Paseo app screenshot

Paseo mobile app

Run agents in parallel on your own machines. Ship from your phone or your desk.

Plugins

Add themes, workspace panels, commands, settings screens, and coding-agent providers with trusted TypeScript plugins. Install from a local directory or Git repository with paseo plugin add <source>.

See the plugin docs for your Paseo version, or start with the 0.8 beta quickstart. Plugins run with access to your daemon machine and inside connected clients; install only code you trust.

Getting Started

Paseo runs a local server called the daemon that manages your coding agents. Clients like the desktop app, mobile app, web app, and CLI connect to it.

Prerequisites

You need at least one agent CLI installed and configured with your credentials:

Download it from paseo.sh/download or the GitHub releases page. Open the app and the daemon starts automatically. Nothing else to install.

To connect from your phone, open Settings → your host → Pair Device.

CLI / headless

Install the CLI and start Paseo:

npm install -g @getpaseo/cli
paseo

Paseo starts locally, then asks whether to enable the end-to-end encrypted relay for device pairing. If you decline, connect directly over TCP, Tailscale, or another VPN. This path is useful for servers and remote machines.

For full setup and configuration, see:

Docker

Run the Paseo daemon and self-hosted web UI in Docker:

docker run -d --name paseo \
  -p 6767:6767 \
  -e PASEO_PASSWORD=change-me \
  -v "$PWD/paseo-home:/home/paseo" \
  -v "$PWD:/workspace" \
  ghcr.io/getpaseo/paseo:latest

Open http://localhost:6767 after it starts. Extend the base image with the agent CLIs you use, then provide credentials through environment variables or the persistent /home/paseo volume. See the Docker documentation for full setup details.

CLI

Everything you can do in the app, you can do from the terminal.

paseo run --provider claude/opus-4.6 "implement user authentication"
paseo run --provider codex/gpt-5.5 --worktree feature-x "implement feature X"

paseo ls                           # list running agents
paseo attach abc123                # stream live output
paseo send abc123 "also add tests" # follow-up task

# run on a remote daemon; --cwd is a path on that host
paseo run --host workstation.local:6767 --cwd /workspace "run the full test suite"

See the full CLI reference for more.

TypeScript SDK

Build issue integrations, dashboards, and orchestration services with @getpaseo/client:

import { createPaseoClient } from "@getpaseo/client";

const client = createPaseoClient({ url: "ws://127.0.0.1:6767/ws" });
await client.connect();

const agent = await client.agents.create({
  config: { provider: "codex/gpt-5.5" },
  cwd: "/Users/me/dev/storefront",
  prompt: "Review the current diff and name the riskiest change.",
});

const result = await agent.waitForFinish();
console.log(result.lastMessage);

await client.close();

See the SDK quickstart, recipes, and API reference.

Skills

Skills teach your agent to use Paseo to orchestrate other agents.

npx skills add getpaseo/paseo

Then use them in any agent conversation:

Development

Quick monorepo package map:

Common commands:

# run all local dev services
npm run dev

# run individual surfaces
npm run dev:server
npm run dev:app
npm run dev:desktop
npm run dev:website

# build the server stack
npm run build:server

# repo-wide checks
npm run typecheck

License

Apache-2.0

paseo (getpaseo/paseo)

ios
Searching Database…

21.2K ·GitHub
What is this?Paseo is an open-source hub for orchestrating coding agents: one interface to run Claude Code, Codex, Copilot, OpenCode, and Pi in parallel on your own machines, controlled from your desk or your phone.
So is this one desktop app, a hosted service, or a library I pull into my code?It's self-hosted software: a local server called the daemon manages your agents, while clients — a desktop app, mobile apps, a web app, and a CLI — connect to it. There's also a TypeScript SDK for building custom integrations.
How do I get it running?Download the desktop app from paseo.sh/download or the GitHub releases page and just open it — the daemon starts automatically, nothing else to install. From there you can pair other devices.
Where does the AI part come from — do I need my own agent CLIs set up first?You bring the agents: at least one agent CLI must already be installed and configured with your credentials — Claude Code, Codex, GitHub Copilot, OpenCode, or Pi. Paseo orchestrates them but ships no models of its own.
Is there anything risky I should know before installing plugins?Plugins run with access to your daemon machine and inside connected clients, so the README warns to install only code you trust. You add them with paseo plugin add from a local directory or Git repository.
Can I really run my agents from my phone, and how do the devices connect?Yes — there are iOS, Android, desktop, web, and CLI clients. Pair a phone from the desktop app via Settings → your host → Pair Device; the CLI path offers an end-to-end encrypted relay for pairing, or you connect directly over TCP, Tailscale, or another VPN.
My agents live on a beefy server — can the daemon run there instead of my laptop?Yes. The CLI/headless mode is built for servers and remote machines, and a Docker image runs the daemon plus a self-hosted web UI — extend the image with the agent CLIs you use and pass credentials via environment variables or the /home/paseo volume.
Does anything I do with it get reported back to the makers?No — Paseo has no telemetry, tracking, or forced log-ins, and agents run on your machine with your full dev environment. The optional relay is end-to-end encrypted, and you can skip it entirely for direct connections.
Can I use it hands-free?Yes — voice mode lets you dictate tasks or talk through problems with your agent instead of typing, which comes in handy when you're away from the keyboard.
What do the bundled skills like /paseo-handoff and /paseo-committee do?They teach your agents to orchestrate each other: /paseo-handoff passes work between agents (plan with Claude, then implement with Codex), /paseo-advisor spins up one agent for a second opinion without delegating, and /paseo-committee convenes two contrasting agents for root-cause analysis and a plan.
Can I build my own tooling on top of it?Yes — the TypeScript SDK @getpaseo/client targets issue integrations, dashboards, and orchestration services, TypeScript plugins add themes, workspace panels, commands, and even new agent providers, and there's a separate VS Code extension (paseo-vscode).
What are similar projects?vicoa, orca, happy, 1code, t3code, hapi, rakazo, superset
Creator
getpaseo
Size
157 MB
Stars
21.2K
Age
1y
Commits · 90 Days