paseo/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Paseo is a mobile app for monitoring and controlling your local AI coding agents from anywhere. Your dev environment, in your pocket.

Key features:

• Real-time streaming of agent output
• Voice commands for hands-free interaction
• Push notifications when tasks complete
• Multi-agent orchestration across projects

Not a cloud sandbox - Paseo connects directly to your actual development environment. Your code stays on your machine.

Supported agents: Claude Code, Codex, and OpenCode.

Monorepo Structure

This is an npm workspace monorepo:

• packages/server: The Paseo daemon that runs on your machine. Manages agent processes, provides WebSocket API for real-time streaming, and exposes an MCP server for agent control.
• packages/app: Cross-platform client (Expo). Connects to one or more servers, displays agent output, handles voice input, and sends push notifications.
• packages/website: Marketing site at paseo.dev (TanStack Router + Cloudflare Workers).

Environment overrides

• PASEO_HOME – path for runtime state such as agents.json. Defaults to ~/.paseo; set this to a unique directory (e.g., ~/.paseo-blue) when running a secondary server instance.
• PASEO_PORT – preferred voice server + MCP port. Overrides PORT and defaults to 6767. Use distinct ports (e.g., 7777) for blue/green testing.

Example blue/green launch:

PASEO_HOME=~/.paseo-blue PASEO_PORT=7777 npm run dev

Running and checking logs

Both the server and Expo app are running in a Tmux session. See CLAUDE.local.md for system-specific session details.

Android

Take screenshots like this: adb exec-out screencap -p > screenshot.png

Testing with Playwright MCP

CRITICAL: When asked to test the app, you MUST use the Playwright MCP connecting to Metro at http://localhost:8081.

Use the Playwright MCP to test the app in Metro web. Navigate to http://localhost:8081 to interact with the app UI.

Important: Do NOT use browser history (back/forward). Always navigate by clicking UI elements or using browser_navigate with the full URL. The app uses client-side routing and browser history navigation breaks the state.

Expo troubleshooting

Run npx expo-doctor to diagnose version mismatches and native module issues.

Orchestrator Mode

• When agent control tool calls fail, make sure you list agents before trying to launch another one. It could just be a wait timeout.
• Always prefix agent titles so we can tell which ones are running under you (e.g., "🎭 Feature Implementation", "🎭 Design Discussion").
• Launch agents in the most permissive mode: Use full access or bypass permissions mode.
• Set cwd to the repository root - The agent's working directory should usually be the repo root

CRITICAL: ALWAYS RUN TYPECHECK AFTER EVERY CHANGE.

Agent Authentication

All agent providers (Claude, Codex, OpenCode) handle their own authentication outside of environment variables. They are authenticated without providing any extra configuration—Paseo does not manage API keys or tokens for agents.

Do not add auth checks to tests. If auth fails for whatever reason, let the user know instead of patching the code or adding conditional skips.

NEVER DO THESE THINGS

• NEVER restart the Paseo daemon/server - The daemon is running in Tmux and managed by the user. Restarting it disrupts active sessions, loses state, and breaks workflows. If there's a connectivity issue, investigate the cause - do not restart.
• NEVER kill or restart processes in Tmux without explicit user permission
• NEVER assume a timeout means the service needs restarting - Timeouts can be transient network issues, not service failures
• NEVER add authentication checks to tests - Agent providers handle their own auth. If tests fail due to auth issues, report it rather than adding conditional skips or env var checks