paseo - Moses Yebei

The Problem

Running coding agents (Claude Code, Codex, OpenCode) across multiple machines typically means juggling separate terminals, SSH sessions, and provider-specific CLIs. There is no unified way to start, monitor, and steer agents from a phone, desktop, or CI script without coupling yourself to one vendor's tooling.

What This Does

Paseo is a self-hosted orchestration layer. A local daemon (packages/server) manages agent processes. Clients—desktop (packages/desktop), mobile (packages/app, Expo/React Native), web, and CLI (packages/cli)—connect to it over WebSocket. The same agent can be controlled from any client, and multiple agents run in parallel on your own hardware.

The CLI (packages/cli/src) exposes run, ls, attach, and send commands for headless or scripted use. The app includes voice input (two-way audio via packages/expo-two-way-audio) and attachment handling (packages/app/src/attachments).

How It Is Wired

Execution starts in the mobile app at packages/app/src/app/_layout.tsx (init, reaches 76 functions) or packages/app/src/runtime/host-runtime.ts (bootstrap, reaches 70). The desktop host (packages/app/src/desktop/host.ts) bridges to Electron. The server's bootstrap in packages/server/src/server/bootstrap is the daemon's entry point.

The critical hub is packages/server/src/server/agent/agent-sdk-types.ts — 106 modules import it, making it the highest-blast-radius file in the repo. packages/server/src/server/messages.ts (38 importers) and packages/cli/src/output/index.ts (62 importers) are also central. All three participate in circular import cycles, which complicates refactoring.

The internal call graph shows set (108 call sites) and trimNonEmpty (55) as the most-touched functions. packages/app/src/runtime/host-runtime.ts is the app's workhorse: 95 functions, called from 49 files. Only one function makes an outbound network call; two touch the filesystem, so the daemon's side effects are concentrated and testable.

How To Use It

Setup:

npm install -g @getpaseo/cli
paseo

Configuration: Requires at least one agent CLI (Claude Code, Codex, or OpenCode) installed and authenticated. The daemon auto-starts with the desktop app; mobile connects via QR code from Settings.

Running: The daemon runs locally; clients connect to it. The CLI is the headless path:

paseo run --provider claude/opus-4.6 "implement user authentication"
paseo ls
paseo attach abc123

Real-World Use

A developer plans a feature with Claude on a workstation, then hands off implementation to Codex in a worktree via /paseo-handoff (an experimental skill in skills/). They check progress from their phone during commute and run the full test suite via paseo --host workstation.local:6767 run from a CI job. One daemon, multiple clients, no vendor lock-in.

Code Health & Issues

Static analysis (not opinion) found 232 issues: 84 high, 148 medium. Key findings:

High – Import cycles: agent-sdk-types.ts, messages.ts, agent-manager.ts participate in circular dependencies. Fix: extract shared types.
High – Oversized files: agent-manager.ts is 2,571 lines. Fix: split by responsibility.
High – Hub modules: agent-sdk-types.ts has 106 dependents; churn here is high-blast-radius.
Medium – High branching density in packages/cli/src/utils/client.ts (68 branches / 239 lines).

SDLC observations: CI exists (GitHub Actions), tests are present (516 files), license and lockfile are committed. No secrets found. The repo lacks Dependabot, a dependency vulnerability scan, and pins GitHub Actions to tags (e.g., expo/expo-github-action@v8) instead of commit SHAs — a supply-chain risk. One 6.5MB binary (hero-bg.jpg) is in the repo.

The Bottom Line

Paseo is a serious, well-structured orchestration tool with a real architecture and good test coverage. The hub/cycle issues in the server are the main refactoring risk; pinning CI actions and adding dependency scanning should be done before production use. Best for teams already running multiple agent CLIs who want a unified control plane.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,647 files

TypeScript1166
TSX214
Markdown55
JSON37
YAML36
JavaScript12

ReactExpressONNX

Module dependencies

The 10 most depended-upon modules of 1,408, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_server_agent_agent_sdk_types["agent-sdk-types"] n1_ackages_cli_src_output_index["index"] n2_s_server_src_server_messages["messages"] n3_c_server_agent_agent_manager["agent-manager"] n4_ackages_cli_src_utils_client["client"] n5__src_server_test_utils_index["index"] n6_r_src_test_utils_test_logger["test-logger"] n7_s_server_src_shared_messages["messages"] n8_ver_daemon_e2e_agent_configs["agent-configs"] n9_c_server_agent_agent_storage["agent-storage"] n3_c_server_agent_agent_manager --> n0_server_agent_agent_sdk_types n3_c_server_agent_agent_manager --> n9_c_server_agent_agent_storage n0_server_agent_agent_sdk_types --> n7_s_server_src_shared_messages n9_c_server_agent_agent_storage --> n2_s_server_src_server_messages n9_c_server_agent_agent_storage --> n3_c_server_agent_agent_manager n9_c_server_agent_agent_storage --> n0_server_agent_agent_sdk_types n2_s_server_src_server_messages --> n3_c_server_agent_agent_manager n2_s_server_src_server_messages --> n0_server_agent_agent_sdk_types n2_s_server_src_server_messages --> n7_s_server_src_shared_messages n7_s_server_src_shared_messages --> n0_server_agent_agent_sdk_types classDef cyc stroke:#ef4444,stroke-width:2px; class n0_server_agent_agent_sdk_types,n2_s_server_src_server_messages,n3_c_server_agent_agent_manager,n7_s_server_src_shared_messages,n9_c_server_agent_agent_storage cyc;

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium6

low2

Pin third-party GitHub Actions to a commit SHAhigh

.github/workflows

expo/expo-github-action@v8

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

9 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium

packages/website/public/hero-bg.jpg

1 blobs over 5MB: hero-bg.jpg 6.5MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/android-apk-release.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Review the install lifecycle script and disable scripts in CImedium

package.json

postinstall

Install scripts are the execution vector for every npm compromise from event-stream onward, and a postinstall that fetches a binary makes the build depend on a URL nobody reviews.

Fix: Move the work into an explicit build step, or set ignore-scripts in CI and run it by name.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/android-apk-release.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.