Technical Documentation: getpaseo/paseo

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

Paseo

Paseo is an open source agentic development environment for desktop, mobile, web, and CLI. Open the desktop app and work: agents, editor, terminals, diffs, pull requests, and a browser in one window. Run many agents at once, each in its own worktree, on one machine or several. The mobile app is the full app, native on iOS and Android.

Parallel agents: Run many agents at once, each in its own worktree.
Built-in orchestration: Agents in Paseo can create worktrees, launch other agents, and talk to them, across providers.
Complete development workflow: Edit files, review diffs, open pull requests, and run terminals, in split panes you arrange how you want.
Self-hosted: Agents run on your machine with your full dev environment. Use your tools, your configs, and your skills.
Multi-provider: Claude Code, Codex, Copilot, OpenCode, Pi, Antigravity, and Muse Code through the same interface. Pick the right model for each job.
Voice control: Dictate tasks or talk through problems in voice mode. Hands-free when you need it.
Cross-device: iOS, Android, desktop, web, and CLI. Start work at your desk, check in from your phone, script it from the terminal.
Privacy-first: Paseo doesn't have any telemetry, tracking, or forced log-ins.

Run parallel tasks in Paseo: start agents in separate worktrees, review their diffs, run each app, and check it in the built-in browser.

Plugins

Plugins run on the daemon and show up in every client you connect, with the same UI on desktop, web,
iOS, and Android. Write a plugin once and it is on your phone.

UI: screens, sidebar items, workspace panels, Command Center items, slash commands, composer pills, attachment sources, timeline items, themes.
Agent lifecycle: change configuration, environment, and MCP servers, answer permissions, follow up when a turn ends.
Providers: add a coding agent as a provider.

Install from the registry with paseo plugin add owner/slug, or from Git or a local directory.

Browse plugins · Plugin docs

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:

Desktop app (recommended)

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.

Server

For a server, a VM, or any machine without the desktop app. Install the CLI and start the daemon:

bash

npm install @getpaseo/cli
paseo

Paseo starts, 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. The desktop, mobile, and web apps connect to this daemon like any other host.

For full setup and configuration, see:

Docker

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

bash

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.

bash

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.

bash

npx skills add getpaseo/paseo

Then use them in any agent conversation:

/paseo-handoff — hand off work between agents. I use this to plan with Claude and then handoff to Codex to implement.
/paseo-advisor — spin up a single agent as an advisor for a second opinion, without delegating the work itself.
/paseo-committee — form a committee of two contrasting agents to step back, do root cause analysis, and produce a plan.

Development

Quick monorepo package map:

packages/server: Paseo daemon (agent process orchestration, WebSocket API, MCP server)
packages/app: Expo client (iOS, Android, web)
packages/cli: paseo CLI for daemon and agent workflows
packages/desktop: Electron desktop app
packages/relay: Relay transport and encryption used by the daemon and clients
packages/website: Marketing site and documentation (paseo.sh)

Common commands:

bash

# 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

Support Paseo

Paseo is an independent project used by tens of thousands of developers daily, built by one person and funded by the people who use it. Support the work on GitHub Sponsors. Companies can sponsor Paseo monthly and have their logo shown at the top of this README and on the paseo.sh homepage and docs.

getpaseo/paseo-relay — official distributed relay, written in Elixir
paseo-vscode — VS Code extension

License

Apache-2.0

Overview (`docker/README.md`)

Paseo Docker Image

This directory contains the official Paseo daemon image.

The image runs the daemon headless and serves the bundled web UI from the same
HTTP origin. Start it, then open the daemon URL in a browser.

bash

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

Then open http://localhost:6767.

The base image intentionally does not bundle agent CLIs. Extend it with the
agents you use:

dockerfile

FROM ghcr.io/getpaseo/paseo:latest

USER root
RUN npm install @openai/codex @anthropic-ai/claude-code

See docs/docker.md for Compose, reverse proxy, security,
agent auth, and troubleshooting notes.

Overview (`packages/app/README.md`)

Welcome to your Expo app 👋

This is an Expo project created with create-expo-app.

Get started

Install dependencies
bash
```
npm install
```
Start the app
bash
```
npx expo start
```

In the output, you'll find options to open the app in a

development build
Android emulator
iOS simulator
Expo Go, a limited sandbox for trying out app development with Expo

You can start developing by editing the files inside the app directory. This project uses file-based routing.

Get a fresh project

When you're ready, run:

bash

npm run reset-project

This command will move the starter code to the app-example directory and create a blank app directory where you can start developing.

Learn more

To learn more about developing your project with Expo, look at the following resources:

Expo documentation: Learn fundamentals, or go into advanced topics with our guides.
Learn Expo tutorial: Follow a step-by-step tutorial where you'll create a project that runs on Android, iOS, and the web.

Join the community

Join our community of developers creating universal apps.

Expo on GitHub: View our open source platform and contribute.
Discord community: Chat with Expo users and ask questions.

Dictation debugging

Set EXPO_PUBLIC_ENABLE_AUDIO_DEBUG=1 before running npx expo start to render the in-app audio debug card. Pair it with the server-side STT_DEBUG_AUDIO_DIR flag so every dictation includes a copyable path to the saved raw audio file.

Overview (`packages/client/README.md`)

@getpaseo/client

TypeScript SDK for building integrations on top of a Paseo daemon.

bash

npm install @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();

The public API is the package root. Imports under @getpaseo/client/internal/* are unsupported implementation details used by Paseo's own packages.

Read the SDK documentation for agents, workspaces, terminals, provider discovery, events, recipes, and the API reference. Runnable TypeScript patterns also live in examples/.

Runtime

The client needs a WebSocket implementation. Modern browsers and Node.js 22 provide one globally.

Use a WebSocket URL ending in /ws, such as ws://127.0.0.1:6767/ws. Pass password when the daemon requires authentication.

The client advertises its supported protocol capabilities by default. Optional capabilities
overrides extend or override that declaration; browser hosting must be supplied by the caller.
Connecting alone does not subscribe to agent timelines or catalog events. See the
event guide for subscription lifetimes and timeline replacements.

Stability

The high-level API exported from @getpaseo/client is the supported SDK surface. The SDK and daemon remain protocol-compatible across versions, but newly added capabilities can require a newer daemon.

Overview (`packages/expo-two-way-audio/README.md`)

Speechmatics Two Way Audio

Expo module for capturing and playing pcm audio data in react-native apps (iOS and Android).

The aim of the module is to facilitate creating real-time conversational apps. The following features are provided:

Request audio recording permissions
Get clean (applying Acoustic Echo Cancelling) microphone samples in PCM format (1 channel 16 bit at 16kHz)
Play audio samples in PCM format (1 channel 16 bit at 16kHz). Playback happens through main speaker unless external audio sources are connected.
Provide volume level both for the input and output samples. Float between 0 and 1.
[iOS only] Get microphone mode and prompt user to select a microphone mode.

Check out our examples/ to see the module in action.

Installation

text

npm i @speechmatics/expo-two-way-audio

Usage

Please check out our examples/ to get full sample code.

Request permissions for recording audio

jsx

import {useMicrophonePermissions} from "@speechmatics/expo-two-way-audio";

const [micPermission, requestMicPermission] = useMicrophonePermissions();
console.log(micPermission);

Initialize the module before calling any audio functionality.

jsx

useEffect(() => {
    const initializeAudio = async () => {
        await initialize();
    };
    initializeAudio();
}, []);

Play audio

[!NOTE]
The sample below uses the buffer module:
npm install buffer

jsx

import { Buffer } from "buffer";

 // As an example, let's play pcm data hardcoded in a variable.
 // The examples/basic-usage does this. Check it out for real base64 data.
 const audioChunk = "SOME PCM DATA BASE64 ENCODED HERE"
 const buffer = Buffer.from(audioChunk, "base64");
 const pcmData = new Uint8Array(buffer);
 playPCMData(pcmData);

Get microphone samples

jsx

// Set up a function to deal with microphone sample events.
// In this case just print the data in the console.
useExpoTwoWayAudioEventListener(
    "onMicrophoneData",
    useCallback<MicrophoneDataCallback>((event) => {
        console.log(`MIC DATA: ${event.data}`);
    }, []),
);

// Unmute the microphone to get microphone data events
toggleRecording(true);

Notes

Some audio features of expo-two-way-audio like Acoustic Echo Cancelling, noise reduction or microphone modes (iOS) don't work on simulator. Run the example on a real device to test these features.

bash

# iOS
npx expo run:ios --device --configuration Release

# Android
npx expo run:android --device --variant release

For Android, the following permissions are needed: RECORD_AUDIO, MODIFY_AUDIO_SETTINGS. In Expo apps they can be added in your app.json file:

javascript

expo.android.permissions: ["RECORD_AUDIO", "MODIFY_AUDIO_SETTINGS"]

Overview (`packages/protocol/README.md`)

@getpaseo/protocol

Shared Paseo protocol schemas, codecs, and wire types.

Stability

This package is public so Paseo's published packages can depend on it cleanly.
It is not a stable public API yet.

Schemas, exports, wire helpers, and types may change or disappear in any release
without advance notice. Use it outside Paseo at your own risk until the package
is explicitly documented as stable.

Overview (`packages/server/README.md`)

Voice Assistant

A voice-controlled terminal assistant that runs as a single local service.

Quick Start

bash

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env
# Edit .env and add your API keys (OpenAI, Deepgram)

# Run development servers
npm run dev

# Open browser to http://localhost:5173

Architecture

Express Server (port 3000) - Serves API and built UI in production
Vite Dev Server (port 5173) - Hot-reload React UI in development
WebSocket (/ws) - Real-time bidirectional communication
Agent - STT → LLM → TTS pipeline with terminal control
Daemon - tmux-based terminal management (in-process)

Development

bash

# Run both servers (recommended)
npm run dev

# Or run separately:
npm run dev:server  # Express on port 3000
npm run dev:ui      # Vite on port 5173

# Type checking
npm run typecheck

# Build for production
npm run build

# Start production server
npm start

Project Status

✅ Completed (Phases 1-2):

Package setup and configuration
Express server with WebSocket
React UI with Vite
WebSocket client with ping/pong testing

⏳ In Progress (Phase 3):

Terminal control (tmux integration)

📋 Planned (Phases 4-9):

LLM integration (OpenAI GPT-4)
Agent orchestrator
Speech-to-Text (Deepgram)
Text-to-Speech (OpenAI)
Audio streaming
UI polish

See IMPLEMENTATION_PLAN.md for complete details.

Environment Variables

bash

OPENAI_API_KEY=your-openai-key-here      # GPT-4 and TTS
DEEPGRAM_API_KEY=your-deepgram-key-here  # Streaming STT
STT_MODEL=whisper-1        # Optional: override to gpt-4o-transcribe, etc.
STT_CONFIDENCE_THRESHOLD=-3.0  # Optional: reject low-confidence clips
STT_DEBUG_AUDIO_DIR=.stt-debug # Optional: persist raw dictation audio for debugging
PASEO_HOME=~/.paseo        # Runtime state directory (agents/, etc.)
PASEO_LISTEN=127.0.0.1:6767  # Listen address (host:port or /path/to/socket)

PASEO_HOME defaults to ~/.paseo and isolates runtime artifacts like agents/. PASEO_LISTEN controls the daemon listen address. For blue/green testing you can run a parallel server without touching production state:

bash

PASEO_HOME=~/.paseo-blue PASEO_LISTEN=127.0.0.1:7777 npm run dev

Tech Stack

Server: Express, TypeScript, ws (WebSocket)
Client: React 18, Vite, TypeScript
Terminal: tmux (via child_process)
AI: OpenAI (LLM + TTS), Deepgram (STT)

Testing

Currently manual testing via:

Start servers: npm run dev
Open http://localhost:5173
Test WebSocket connection (green status indicator)
Click "Send Ping" button to test communication

More testing guidance as features are implemented.

License

MIT

Overview (`packages/website/README.md`)

Paseo website

Plugin install counts

Clients report an install by resolving a plugin with X-Paseo-Install: 1 or
?intent=install, using /api/plugins/resolve/<owner>/<slug> or
/plugins/<owner>/<slug>.json. Ordinary resolves do not count. These numbers
measure install intent, not successful artifact installation or npm downloads.

The worker requires Cloudflare's CF-Connecting-IP header to count a report.
It stores the plugin ID plus a SHA-256 hash of the IP in a WEBSITE_CACHE KV key
with a one hour TTL, never the raw IP. An existing key skips the count; repeats
do not extend the hour. Missing or empty IP headers do not count.

Accepted reports increment the existing all-time total and UTC daily buckets in
WEBSITE_CACHE. Daily buckets retain 60 days and supply the website's seven-day
and thirty-day rankings. /api/plugins/installs still returns plugin IDs mapped
to all-time totals. The registry build
reads that endpoint into the published plugin details and index; the website
reads windowed counts from KV through its five-minute cache. Existing counts
remain intact. The KV guard is advisory: concurrent requests and KV propagation
are not serialized.

Overview (`plugin-examples/agent-configuration/README.md`)

Agent configuration

Changes new Codex agents through server.before("agent.create", ...):

Sets config.providerOptions.sandbox_mode to workspace-write.
Sets config.providerOptions.approval_policy to on-request.
Adds the company server to config.mcpServers.
Preserves other configuration, provider options, MCP servers, and environment overrides.

Replace https://tools.example.com/mcp in index.server.ts with your MCP server URL before using
this example. The URL is a placeholder. The company entry replaces an existing server with that name.

Install on a daemon with plugins enabled:

bash

paseo plugin install /absolute/path/to/plugin-examples/agent-configuration

The callback receives the request after earlier plugins have transformed it. The nested spreads
preserve their settings; the explicit values replace only the named fields. Paseo validates and saves
the resulting configuration before starting the agent. Existing agents are unchanged.

See the lifecycle reference for ordering
and callback shapes. Lifecycle actions demonstrates provider switching and
environment injection. Its provider-switch callback clears provider options when changing Codex to
Claude, so use these examples separately when trying the Codex-specific settings.

Overview (`plugin-examples/buttons/README.md`)

Header buttons and composer pills

Install this directory as a plugin, open an agent, and choose Button examples: action in the
Command Center. One header button and one composer pill appear. Choose another mode to update
those same registrations. Switching agents moves the example to that agent's workspace and composer.

Command Center command	Header	Composer	Try
Button examples: action	Refresh icon only	Refresh icon and label	Refresh reads the workspace from the daemon and updates the label and tooltip. Paseo owns pending and error feedback.
Button examples: menu	Wrench, Tools, chevron	Wrench and Tools	Refresh, a separator, custom details, a Display submenu, and a disabled item.
Button examples: popover	Reactive status dot, Details, chevron	Reactive status dot and Details	Workspace data updates through `useWorkspace`; Done closes the surface.
Button examples: hide / show	Hide or restore the button	Hide or restore the pill	Visibility changes through `registration.update({ visible })`.
Button examples: disable / enable	Disable or enable the button	Disable or enable the pill	Disabled state changes through `registration.update({ disabled })`.

On compact layouts the header button is borderless and icon-only. Menus and custom content open
bottom sheets. Composer pills keep their icon and label, without a chevron, on every layout.

The example contributes one header button at a time. Additional actions live under the named
Tools button; the example does not add a three-dot control or trigger plugin overflow.

Action	Menu	Custom content	Compact sheet

The client entry owns the active example. client/examples.tsx contains the
descriptors, updates, and React content. Return .remove() cleanup when the example moves or stops.
See the button reference and
composer migration.

From the repository root, npm run typecheck --workspace=@getpaseo/plugin checks this example
against the SDK. Existing plugin projects must update @getpaseo/plugin before running their own
npm run typecheck to detect the old Component/onPress pill shape and callable cleanup handle.

The browser regression installs this exact directory in an isolated daemon and exercises both
layouts, updates, and cleanup:

npm run test:e2e --workspace=@getpaseo/app -- e2e/browser/plugin-button-example.spec.ts

The captures use Chromium at desktop and phone widths; native iOS and Android were not exercised.

Overview (`plugin-examples/catppuccin/README.md`)

Catppuccin plugin example

This example adds Catppuccin Mocha to Settings → Appearance. Paseo ships Catppuccin as a
syntax-highlight theme; this contributes it as an app theme.

A theme is client data, so the whole plugin is one addTheme call in index.client.ts and has no
server entry or subprocess.

json

{
  "pluginsEnabled": true,
  "plugins": {
    "catppuccin": {
      "source": "directory",
      "path": "/absolute/path/to/paseo/plugin-examples/catppuccin"
    }
  }
}

Then run paseo reload and pick Catppuccin Mocha in Settings → Appearance.

The colors come straight from the Catppuccin Mocha palette:
base, text, surface0, surface1, mauve, subtext0, and overlay0. Paseo expands them
into the full token set, so accent (mauve) drives buttons and selection while border
(surface1, shared with control) stays the border and raised-surface tint.

Overview (`plugin-examples/inline-thinking/README.md`)

Inline thinking timeline example

This plugin replaces reasoning rows from the first streaming delta and renders the paced text
inline. Install the directory as inline-thinking, then run an agent that streams reasoning.
index.client.tsx wires the transformer and renderer to the component in client/thinking.tsx.

Overview (`plugin-examples/lifecycle-actions/README.md`)

Lifecycle actions

Small callbacks using the existing SDK:

Send Try again. when the latest output contains out of credits.
Decline a shell request matching rm -rf; approve exactly git status; leave other requests alone.
Inject PASEO_HOOK_CREATE_EXAMPLE=created on creation and PASEO_HOOK_OPEN_EXAMPLE=opened on each session opening.
Change requested Codex agents to Claude Haiku before creation.
Create a worktree when a directory creation request is titled Isolated lifecycle example.

This is a demonstration plugin: installing it enables all these behaviors on its host. Install it
alongside lifecycle-logger on a test daemon with plugins enabled:

bash

paseo plugin install /absolute/path/to/plugin-examples/lifecycle-actions
paseo plugin install /absolute/path/to/plugin-examples/lifecycle-logger
paseo plugin logs lifecycle-logger

Outside the Paseo repository, server/inspect.ts needs @getpaseo/protocol installed for its
type imports. Add it to your plugin development dependencies at the same version as
@getpaseo/plugin before installing this example.

Copy the callbacks you need into your own plugin. The follow-up example sends a new message; it does
not replay attachments or undo previous tool effects. If the provider keeps returning the matching
phrase, it keeps sending follow-ups. Add limits or delay in your plugin when your workflow needs them.
The command regex illustrates a policy; it does not parse shell syntax or cover every deletion command.

server/inspect.ts joins provider text chunks and excludes earlier turns and the current user prompt
from the phrase match. The failing-first regression test records the split text observed with a real
Claude agent.

See agent configuration for a focused example that injects MCP servers and
changes Codex sandbox and approval options while preserving other settings.

See the lifecycle reference for the API.

Overview (`plugin-examples/lifecycle-logger/README.md`)

Lifecycle logger

Registers all eleven server lifecycle hooks and logs their data as JSON. It observes agent creation,
session opening, turns, permissions, archive, and workspace creation/archive. Before hooks return
the request unchanged. Environment values are redacted; prompts and timeline content are logged.

Install it on a daemon where plugins are enabled:

bash

paseo plugin install /absolute/path/to/plugin-examples/lifecycle-logger
paseo plugin logs lifecycle-logger

The same entries appear in the target daemon's daemon.log. The plugin log viewer retains a bounded
tail; use the daemon log for longer captures. Log lines are capped at 16 KiB, so a large timeline can
be truncated.

See the lifecycle reference for callback
shapes and delivery rules. The real-provider test in
packages/server/src/server/plugins/lifecycle.real.e2e.test.ts runs both examples on an isolated daemon
and saves evidence under .dev/lifecycle-proof/.

Run it from packages/server on Linux with Claude configured:

bash

npx vitest run src/server/plugins/lifecycle.real.e2e.test.ts --bail=1

The test uses real provider calls and a temporary daemon home. Its failure check uses Linux /proc
to identify and terminate only its own Claude subprocess. The credits check asks the real agent to
emit the matching phrase; it does not exhaust an account's credits.

Overview (`plugin-examples/linear/README.md`)

Linear plugin example

This example adds Attach Linear issue to the composer. Search by issue identifier
or title, then send a stable issue snapshot to the agent.

Set a personal API key in the daemon environment:

bash

export LINEAR_API_KEY="lin_api_..."

Start your daemon with that environment variable set. Then turn on Enable plugins in
Settings → Plugins and install the example:

bash

paseo plugin add /absolute/path/to/paseo/plugin-examples/linear
paseo plugin ls linear

Use paseo plugin reload linear after source edits. Changing the API key requires restarting the
daemon with the new environment; installing or reloading plugin source does not.

The split entry point demonstrates the complete attachment-source pattern:

define the validated search RPC and attachment metadata in shared/issues.ts;
handle it in the daemon subprocess from server/issues.ts and index.server.ts;
register the attachment source from index.client.ts;
keep credentials and vendor API calls out of the client bundle.

Overview (`plugin-examples/markdown-panel/README.md`)

Markdown file panel example

Requires Paseo 0.13.0 or later. Install the editor dependencies, then install this directory:

cd plugin-examples/markdown-panel
npm install
paseo plugin install "$PWD"

Open a .md or .markdown file in Files. Choose Rich Markdown — markdown-panel in the
picker. Check Don't ask me again to remember the choice on this device.

The panel is a CodeMirror editor with Markdown highlighting, line numbers, undo, redo, and line
wrapping. It reads the file once with readText, saves 500 ms after the last edit with
writeText, and reports unsaved edits with tab.setModified. When the file changes on disk with
nothing unsaved, it reads again; with unsaved edits, or when a write rejects with
PluginFileConflictError, it offers Reload and Overwrite. Open with… in the tab menu
switches the tab back to Paseo's Markdown panel. Native shows selectable, read-only text through
useFileText.

Paseo bundles the editor dependencies into this plugin. They are loaded only on web; the native
path uses React Native primitives. DOM integration lives in client/web.ts.

See the file panel reference.

Install on a Paseo host with npm source installation support and npm available:

paseo plugin install npm:@getpaseo/[email protected]

In host Settings → Plugins, paste the same npm: identifier into Plugin source.
Enable plugins, then open Modal examples from the sidebar or a workspace tab.
Choose Open Form, type into Paste here, and watch the Input: text update.
The installed plugin ID is modal-ui-example. Host Settings shows the package identity and
installed version. With reviewed-update support, run paseo plugin update modal-ui-example --check
to check for a newer version, then paseo plugin update modal-ui-example to review and approve it.
An explicit install version selects the initial content; later updates still check the latest release.

The package ships the existing TypeScript entry and client sources. Paseo compiles them through
its directory plugin loader; no package build or preparation command is required. React,
React Native, and @getpaseo/plugin are peer contracts supplied by the host. npm is needed for
installation, not loading or reloading. You can also install this directory while developing.
See the source reference
for supported identifiers and preparation rules.

The examples demonstrate default and custom padding, a full-width body, author-owned ScrollView and
FlatList scrolling, horizontal tabs, and clipboard actions with a keyboard-aware input. See the
host UI reference for the API contract.

The browser regression installs this exact example in an isolated daemon:

cd packages/app
npx playwright test e2e/browser/plugin-modal-body.spec.ts --project=browser --workers=1

On Android, open each example and drag up on its content to expand the sheet, then scroll the list.
In FlatList, expand before using Jump to last row; row 100 should be visible. At the top of either
list, drag down on a row to dismiss the sheet. In Form,
press Copy text, long-press the input, and choose Paste. The input should contain
“Copied from Paseo”. With the system keyboard enabled, focusing the input should keep it visible.

Run the native sheet regression to check body
dismissal, list scrolling and horizontal tabs together.

These captures show Android copy/paste and custom padding on browser and wide native layouts.
Android API 35 and Chromium were exercised; iOS and Electron were not tested.

Android copy/paste	Browser custom padding	Wide Android custom padding

Overview (`plugin-examples/pdf-panel/README.md`)

PDF file panel example

Requires Paseo 0.13.0 or later. Install this directory with
paseo plugin install /absolute/path/to/plugin-examples/pdf-panel, then open a .pdf in Files.

The panel resolves the file's local URL with useFileUrl, shows Loading until it does, and passes
it to DocumentFrame. Where a platform cannot show a PDF inline (Android), DocumentFrame says so.
The plugin does not construct daemon URLs.

See the file panel reference.

Inline PDF rendering needs a daemon from Paseo 0.13.0 or later; see the
DocumentFrame reference.

Overview (`plugin-examples/provider-acp-transformer/README.md`)

ACP provider transformer example

This server plugin registers an ACP command through runAcpProvider(). The helper owns ACP process
and SDK details behind Paseo's callback-based provider connection.

server/vendor-edit.ts shows the intended extension seam: a focused transformer converts one
vendor tool payload into Paseo's ordinary file-edit shape. It does not translate the whole event
stream.

Replace the placeholder example-acp --stdio command with an installed ACP agent before enabling
the plugin.

Overview (`plugin-examples/provider-direct/README.md`)

Direct provider example

This plugin implements ProviderRegistration directly. It demonstrates connection negotiation,
catalog and session listing, session creation, prompt and command disposition, settings,
persistence and replay, archive actions, and an ordinary child session.

The provider emits versioned provider-result timeline items for its root and child sessions.
index.client.tsx registers the Zod schema and React Native renderer for those items. The server
and client share only the item kind and schema under shared/.

The provider receives Paseo host tools through config.mcpServers; it does not receive a second
callback tool API.

Overview (`plugin-examples/settings/README.md`)

Settings example

Install this directory with paseo plugin install /absolute/path/to/plugin-examples/settings.
Open Settings → Plugins → settings-example → Display, or run Configure agent monitor in Command Center.

The select and switch save immediately. The title editor keeps a draft and its original revision,
so another client's save produces a conflict instead of overwriting its changes. Close and reopen
the editor to discard the draft and use the latest settings.

Every UI component is a plain named import. The custom preview shares the same values without
using a form wrapper. Values are shared by clients connected to the same host.

The same screen on Android, Electron,
and compact web.

Overview (`plugin-examples/timeline-items/README.md`)

Pi tasks timeline plugin example

This example recognizes Pi todo tool calls from both @juicesharp/rpiv-todo and Pi's
examples/extensions/todo.ts, replaces the tool-call entry with a versioned pi-task-list item,
and renders the current task snapshot with a native React Native component. It transforms both
running and completed calls.

The rpiv shape preserves pending, in_progress, and completed; deleted tombstones are omitted.
Pi's example shape maps done to completed or pending. Malformed results and unrelated tool
calls return undefined, leaving Paseo's original timeline entry unchanged.

The transformer is a pure client contribution. It receives each source item and its streaming phase
while Paseo builds the render model, then returns plain plugin item objects. The renderer validates
data before Paseo mounts the component.

index.client.tsx wires the transformer from shared/pi-tasks.ts and renderer from
client/pi-tasks.tsx. The plugin has no server entry or subprocess.

Overview (`packages/app/maestro/README.md`)

Maestro Flows

This directory contains local mobile UI flows. Keep flows small enough that a
failure screenshot proves the intended behavior, not just that the app launched.

ios-sidebar-close-regression.yaml exercises close swipes over a semantic header
and the nested workspace list without activating the content below the swipe.
Start the sh.paseo.debug dev client against the intended Metro server first;
the flow preserves that running connection.

bash

maestro test packages/app/maestro/ios-sidebar-close-regression.yaml --udid <simulator-udid>

test-sidebar-drag-cancellation-ios.sh creates three temporary projects and
uses real native slow swipes to cover successful reorder, a second touch during
the drop spring, horizontal close cancellation, outer-list scroll recovery, and
a subsequent reorder. The harness removes its daemon projects and local fixture
directories on exit.

Start the debug dev client against the intended Metro server, then run:

bash

bash packages/app/maestro/test-sidebar-drag-cancellation-ios.sh

New Workspace Android Flow

Use these files when debugging or extending workspace creation on Android:

test-workspace-create-android-crash.sh runs the full regression harness.
workspace-create-android-crash.yaml is the full Maestro flow used by the
harness.
record-workspace-create-android-focus.sh records only the focused repro
window after setup.
workspace-create-android-ready-sidebar.yaml stages the app with the Android
sidebar open and a prepared project visible.
workspace-create-android-create-focused.yaml starts from that staged sidebar
and performs the actual workspace creation.

The reusable pieces live in flows/:

flows/android-dev-client.yaml handles Expo dev launcher/dev menu screens.
flows/connect-direct-if-welcome.yaml connects to the local daemon only when
the welcome screen is visible.
flows/open-prepared-project-sidebar.yaml waits for the home screen, opens
the compact Android sidebar, and waits for the prepared project.
flows/new-workspace-open-from-sidebar.yaml taps the project row's
new-workspace action and waits for /new.
flows/new-workspace-select-codex-gpt54.yaml selects a real provider/model.
flows/new-workspace-submit-and-assert-created.yaml taps Create and proves
the app landed on the created workspace.

Compose new workspace scenarios out of these primitives instead of copying the
old full flow. The shell scripts render the top-level flows and every flows/*.yaml
file into the same temp directory, so nested runFlow: flows/... paths keep
working with ${PASEO_MAESTRO_*} placeholders.

The flow is intentionally strict. It must:

Open a prepared project from the daemon.
Tap the project row's new-workspace action.
Select an actual provider/model before tapping Create.
Tap Create.
Assert the app lands on a workspace header and the draft composer.
Assert New workspace, Select a model, and the Android redbox text are not
visible.
For the shell harness, grep logcat for failed to insert view and
specified child already has a parent.

Do not weaken this flow to only wait for message-input-root. That can pass on
the wrong route. The header assertion and the New workspace negative assertion
are what prove the redirect actually completed.

The scripts assume a development build with package id sh.paseo.debug, an
already-running local daemon on 127.0.0.1:6767, and a connected Android device
or emulator. They call adb reverse tcp:6767 tcp:6767; they do not restart the
daemon.

bash

bash packages/app/maestro/test-workspace-create-android-crash.sh
bash packages/app/maestro/record-workspace-create-android-focus.sh

Optional environment:

bash

PASEO_MAESTRO_APP_ID=sh.paseo.debug
PASEO_MAESTRO_DIRECT_ENDPOINT=127.0.0.1:6767
PASEO_MAESTRO_DAEMON_WS_URL=ws://127.0.0.1:6767/ws
PASEO_MAESTRO_PROJECT_PATH=/path/to/git/repo

Overview (`packages/client/examples/README.md`)

Paseo Client SDK Examples

These examples use only the public SDK root:

import { createPaseoClient, type PaseoClient } from "@getpaseo/client";

Each example takes the daemon WebSocket URL as an argument. In worktree dev, read it
from the portless banner or portless get daemon; for the desktop-managed daemon,
use the URL for that daemon.

quickstart.ts runs one agent and prints its reply. It is a standalone script with the URL at the top; the rest export functions.
workspaces.ts covers creating a fresh workspace, opening by directory, refreshing, and archiving.
agents-and-providers.ts covers provider discovery, creating agents, and waiting for turns.
events-and-timeline.ts covers subscribing to workspace, agent, and timeline events, plus refetching a timeline page.
issue-to-agent.ts turns an issue record into a visible Paseo workspace and agent.
parallel-review.ts launches several reviewers concurrently and cleans them up.
provider-settings.ts covers provider settings that are currently daemon config-backed.

Provider profiles, provider env vars, custom binaries, and additional models are still raw daemon config behavior. The SDK exposes them through client.config.get() and client.config.patch() until first-class provider settings RPCs exist.

Overview (`packages/protocol/codegen/README.md`)

Protocol Validator Codegen

This directory is build-time only. The generator writes generated/ws-outbound.compile.ts, the zod-aot discovery entry for the inbound WebSocket validators: one for the envelope and one per session message type.

The discovery entry and the generated runtime files under ../src/generated/validation/ are not committed. The protocol package owns every generation trigger through its npm lifecycle scripts.

zod-aot is exact-pinned, and the protocol generator applies the small compiler patches it requires before generation. Treat changes to those patches like compiler changes: regenerate, inspect the output, and run the protocol validation regression tests before shipping.

Overview (`packages/app/modules/paseo-diff-prototype/README.md`)

Native diff layout experiment

Android-only Expo module for evaluating background wrapped-text layout. The normal
diff surface does not call this module; it still uses the JavaScript model and
renderer. This is a checkpoint of the layout experiment, not a replacement renderer.

The C++ core owns cell text and wrapped grapheme geometry. Kotlin/JNI supplies the
Android font manager and dispatches preparation through Expo's background queue.
It links the Skia libraries shipped by the installed React Native Skia package.
An iOS binding, renderer integration, and shipping library ownership are unfinished.

Diagnostic interface

Access the module through expo.modules.PaseoDiffPrototype in a development build:

create() returns a numeric handle.
prepare(handle, texts, widths, family, fontSize) asynchronously builds geometry
and returns counts, copy/layout timings, and a partial geometry allocation estimate.
Text and width arrays must have matching lengths. Input is copied; it is not zero-copy.
read(handle, startCell, count) synchronously returns packed numerical geometry
for at most 256 cells. This exists for parity checks, not whole-model transfer.
release(handle) cancels pending work and releases ownership. Release handles
after success or failure; module destruction also cancels and releases all handles.

Each packed cell begins with its index and fragment count. Each fragment contains
UTF-16 start/end offsets, width, and grapheme count, followed by each grapheme's
UTF-16 start/end offsets and width. The caller retains source text.

The experiment accepts normalized cell inputs. It does not parse wire payloads,
construct file/header/review models, apply highlighting, or draw pixels. A renderer
integration must preserve native ownership and request bounded visible data rather
than reconstructing the entire JavaScript graph.

Grapheme property ranges are generated at build time from the installed JavaScript
dependency so segmentation uses the same data as the reference implementation.

Overview (`packages/expo-two-way-audio/examples/basic-usage/README.md`)

Expo Two-Way-Audio Using Flow API

This example showcases the basic functions of the expo-two-way-audio module:

Capture input raw pcm data
Play raw pcm data (from a hardcoded base64 string)
Display volume level for both input and output
In iOS: show/set microphone mode while recording.

Requirements

Node.js
Expo CLI
iOS and/or Android dev environment setup.

Run the app

In the examples/basic-usage directory:

Install dependencies:
sh
```
npm install
```

Run the app:

# Run iOS
npm run ios

# Run Android
npm run android

Notes

Some audio features of expo-two-way-audio like Acoustic Echo Cancelling, noise reduction or microphone modes (iOS) don't work on simulator. Run the example on a real device to test these features.

bash

# iOS
npx expo run:ios --device --configuration Release

# Android
npx expo run:android --device --variant release

Overview (`packages/expo-two-way-audio/examples/flow-api/README.md`)

Expo Two-Way-Audio Using Flow API

This example shows how expo-two-way-audio can be used to communicate with Speechmatics Flow API

Flow is a conversational AI API and therefore, we need to send audio data in real time and play back the audio responses that we'll get from the API.

Requirements

Node.js
Expo CLI
iOS and/or Android dev environment setup.
Speechmatics Flow Client (React)
event-target-polyfill package, or any other polyfill for the EventTarget class

A Speechmatics API key is also needed in order to run the example. The key is injected into the app via environment variable. It can be passed by creating a .env file in the same directory as the example with the following content:

text

EXPO_PUBLIC_SPEECHMATICS_API_KEY='YOUR-API-KEY-HERE'

An API key can be obtained from the Speechmatics Portal

[!WARNING]

The example uses the API key to request a temporary token (needed for communicating with flow).
In a real-world scenario, you should not expose your API key in your client-side code.
Instead, you should create a server-side endpoint that generates the temporary token (JWT) for you.

Run the app

In the examples/flow-api directory:

Install dependencies:
sh
```
npm install
```

Run the app:

# Run iOS
npm run ios

# Run Android
npm run android

Notes

Some audio features of expo-two-way-audio like Acoustic Echo Cancelling, noise reduction or microphone modes (iOS) don't work on simulator. Run the example on a real device to test these features.

bash

# iOS
npx expo run:ios --device --configuration Release

# Android
npx expo run:android --device --variant release

Overview (`packages/app/e2e/mobile/composer-overlay/README.md`)

Late composer pill clearance

This regression opens a completed conversation, relaunches the Android app, and
registers a composer pill five seconds after the client plugin loads. It checks
that the completed turn's Copy and Fork buttons remain fully above the pill.
The daemon, plugin API, native app, layout, and accessibility bounds are real;
no provider calls are needed during the test.

Prerequisites:

Build the server and app dependencies with npm run build:server and
npm run build --workspace=@getpaseo/expo-two-way-audio.
Run an isolated development daemon on a non-default port.
Run this checkout's Metro server and open the connected Android dev client
with agent-device. The app must already know the isolated daemon.
Open a completed conversation on a compact portrait Android emulator, at the
latest turn, with no other composer tracks visible. Keep the software keyboard
closed. Note the workspace and agent IDs from the daemon.

Set WORKSPACE_ID and AGENT_ID to that conversation, then run from the
repository root, substituting the session and ports:

PASEO_OVERLAY_ARTIFACTS_DIR=.dev/composer-overlay-evidence \
  node packages/app/e2e/mobile/composer-overlay/android.mjs \
  composer-overlay ws://127.0.0.1:6843/ws "$WORKSPACE_ID" "$AGENT_ID" sh.paseo.debug 8193

The runner installs and removes its delayed plugin and leaves the conversation
intact. It preserves the daemon's previous plugins-enabled setting. The evidence directory
contains the cold-reopen screenshot and raw accessibility snapshot. Without an
explicit directory, temporary evidence is removed with the fixture.

To check an existing capture independently:

node packages/app/e2e/mobile/composer-overlay/assert-footer-clear.mjs \
  .dev/composer-overlay-evidence/cold-reopen.json 'Overlay regression pill'

On the failing baseline, the Copy button extends below the pill's top edge. With
the correction, both actions are clear before the composer receives focus.

Additional checks on the same conversation: opening the keyboard keeps the footer
clear; after scrolling up, a newly registered pill must not jump back to the latest
turn. Native iOS uses a different keyboard implementation and needs its own device
verification.

Overview (`packages/app/e2e/mobile/diff-tree/README.md`)

Mobile diff tree appearance

Reproduce the row shadow

Use an Android emulator with a workspace containing 80 modified text files,
named file-000.txt through file-079.txt. Each file changes before to after.

Open the workspace's Changes sidebar, then Jump to file.
Swipe upward through the tree until file-079.txt is visible.
Inspect the row where the scroll gesture started. It must remain flat.
Swipe back to the first file, then return to the last file and select it.
The sheet should close and show that file's diff.

Recorded verification

Android API 35, 1080×1920. The baseline produced a raised gray shadow around
file-074.txt after scrolling. The fixed build reached the same last row without
the shadow. Baseline scrolling in both directions and selection of the last file
passed; the fixed build also reached the last row and closed the sheet on selection.
The fixed-build assertion for the selected diff header did not match, so it does
not establish the final jump position.

Before	After

Light	Dark

The shadow check is visual; the existing header-interaction unit test does not
test Android rendering. iOS, browser web, and Electron were not manually exercised.

Compact sheet gestures

Use an Android emulator at 1080×1920, density 420, with the checkout's native app bundle loaded.
Connect the app to an isolated daemon, enable plugins, and install plugin-examples/modal-ui there.
Set SHEET_QA_SERVER_ID to that host's server ID, then run from the repository root:

agent-device test packages/app/e2e/mobile/modal-sheet/gestures.android.ad \
  --env EXAMPLES_URL="paseo://h/${SHEET_QA_SERVER_ID}/plugin/modal-ui-example/surface/main" \
  --record-video --artifacts-dir .dev/sheet-qa/plugin

agent-device test packages/app/e2e/mobile/modal-sheet/model.android.ad \
  --env FORM_URL="paseo://new?serverId=${SHEET_QA_SERVER_ID}" \
  --record-video --artifacts-dir .dev/sheet-qa/model

The plugin journey checks body dismissal, reopening, expansion and last-row reachability with SDK
ScrollView and FlatList, programmatic scrolling after expansion, downward list scrolling, and
horizontal tab selection. The model journey checks body dismissal and the nested sheet's return to
its parent without selecting a model or submitting a prompt. It does not assert catalog contents.

These scripts live outside the default mobile suite because they require the installed example and
an explicit connected host. See mobile testing for device setup.

Recorded verification

Android API 35, 1080×1920 at density 420, development binary 0.7.2 with this checkout's JavaScript.
Plugin tests used an isolated daemon. Recordings show the same body drag
before and after the fix.
The browser recording covers the existing plugin modal journey at wide and
compact sizes.

text

Baseline dismissal regression:
failed at step 6: wait timed out for selector: label="Open ScrollView"
Current surface: Bottom sheet handle, Bottom Sheet, Close, Row 1.

Fixed dismissal regression: 1 passed (6.47s)
Full plugin gesture journey: 1 passed (44.3s)
Model sheet dismissal/reopen journey: 1 passed (13.7s)
Browser plugin-modal-body.spec.ts: 1 passed (33.4s)
Root typecheck, lint and format: passed

The model form's catalog stayed on “Loading…” in the debug app even though the isolated daemon's
provider API returned models. Its sheet dismissal/reopen was exercised; populated model selection
was not. iOS and Electron were not exercised.

Tablet model selection

model-tablet.android.ad exercises the New workspace popover. model-tablet-agent.android.ad
exercises the modal used by an existing agent's narrow composer on a wide device. Both drill into
a populated provider, select a real model, assert the updated trigger, reopen, and dismiss with
Android Back. New workspace also pans beyond the short list viewport and flings back without
selecting a row or dismissing the popover. They do not submit a prompt.

Use an English-language Android tablet at 1600×2560, density 320 (800dp), with this checkout's
JavaScript and a connected isolated daemon. On a Pixel Tablet AVD, rotate to portrait explicitly;
its natural landscape orientation letterboxes this portrait-locked app into the compact layout:

adb -s "$ANDROID_SERIAL" shell settings put system accelerometer_rotation 0
adb -s "$ANDROID_SERIAL" shell settings put system user_rotation 1
adb -s "$ANDROID_SERIAL" shell wm density 320

Prepare an idle agent through the daemon's public createAgent API with a real provider/model and
no initial prompt. Set MODEL_QA_AGENT_ID and MODEL_QA_AGENT_TITLE to that agent. In New workspace,
remember a model first (the phone layout works on the broken baseline), then close the picker.
Choose a model visible on the provider's first page and set its catalog ID and displayed label.
Set MODEL_QA_LAST_MODEL_ID to its initially offscreen last model; use a short overflowing catalog
(six rows during this verification) for the coordinate-based pan/fling regression:

agent-device test packages/app/e2e/mobile/modal-sheet/model-tablet.android.ad \
  packages/app/e2e/mobile/modal-sheet/model-tablet-agent.android.ad \
  --serial "$ANDROID_SERIAL" --metro-port "$MODEL_QA_METRO_PORT" \
  --env FORM_URL="paseo://new?serverId=${SHEET_QA_SERVER_ID}" \
  --env AGENT_URL="paseo://h/${SHEET_QA_SERVER_ID}/agent/${MODEL_QA_AGENT_ID}" \
  --env AGENT_TITLE="$MODEL_QA_AGENT_TITLE" \
  --env PROVIDER_ID=codex --env MODEL_ID="$MODEL_QA_MODEL_ID" \
  --env MODEL_LABEL="$MODEL_QA_MODEL_LABEL" --env LAST_MODEL_ID="$MODEL_QA_LAST_MODEL_ID" \
  --artifacts-dir /tmp/paseo-model-tablet-qa

The existing-agent journey needs the sidebar pinned so its composer stays narrow. Start each run with no modal open;
a failed provider tap leaves its modal open, so dismiss it before the next run. These host-dependent
journeys remain outside the default mobile suite, alongside the compact sheet journeys above.

Keep generated screenshots, recordings, and run logs outside the repository.

Stacked adaptive sheets

stacked-pairing.ad opens the welcome screen's pairing sheet and then the root-mounted host
confirmation. It first types without tapping the input to verify autofocus, then cancels the
confirmation, closes and reopens the underlying sheet, confirms again,
and completes the password retry. stacked-settings.ad checks the same return and retry through
Settings → add host → Direct connection → Advanced. Run both on phones and tablets so both the
bottom sheet and centered dialog are exercised.

These integration journeys require the host-confirmation flow in the test app. Include both the
sheet fix and that flow in the QA checkout when verifying them; the production sheet component
has no dependency on the host-confirmation feature.

Use a fresh English app with notification permission granted and first-use keyboard prompts
already dismissed. Load this checkout from an isolated Metro. Start an isolated password-protected
daemon and a local Wrangler relay with --var 'PASEO_RELAY_UPSTREAM:'; the checked-in upstream
setting otherwise forwards traffic to the hosted relay, which drops password rejection replies.
Set PAIRING_LINK to the daemon's relay:// URI with an intentionally incorrect password query
parameter, and PASSWORD to its correct password. This exercises password retry even while the
daemon accepts relay connections with no credential.

agent-device replay packages/app/e2e/mobile/modal-sheet/stacked-pairing.ad \
  --state-dir "$SHEET_QA_DEVICE_STATE" --session stacked-ipad --platform ios \
  --udid "$SHEET_QA_IOS_UDID" \
  --env PAIRING_LINK="$SHEET_QA_LINK" --env PASSWORD="$SHEET_QA_PASSWORD" \
  --env OUT="$SHEET_QA_OUTPUT"

For Settings, first open Settings with Add host visible. With a saved host, open Switch host
first. Use a second loopback spelling
(localhost instead of 127.0.0.1) for the same local relay so the saved host asks for confirmation
of its changed connection. Pass that link to stacked-settings.ad with the same arguments.
For an app with no saved hosts, use the original link; Add host is visible directly in Settings.

Android uses the same journeys: copy each script outside the repository, change its context's
platform=ios to platform=android, and pass --serial instead of --udid. Reverse both Metro
(including the port advertised by its manifest) and the local relay ports. Keep driver state,
artifacts, and sessions separate from other runs. These host-dependent journeys remain outside the
default mobile suite, alongside the existing modal-sheet scripts.

On iPhone, bulk replacement or bulk keyboard entry of the advanced URI field triggers a
repeated-update error with both the parent and stacked-sheet implementations. Entering the complete
URI one character at a time passed with both implementations; faster typing remains unverified.
On iPad, replacing the field a second time appends text. For this Settings journey, use the
native clipboard Paste menu, then continue the assertions manually. Dismiss the password keyboard
with Done to submit when the Connect button is below the keyboard. The welcome pairing regression
runs end to end without these adjustments.

Overview (`packages/app/e2e/mobile/status-ring/README.md`)

Native retained status-ring regression

This runs the production native ring and clock inside real retained panels with
Reanimated on Android. A probe consumes the same public rotation hook and counts
UI-runtime value changes. No Reanimated mocks or provider processes are used.

Use an Android development client compatible with the checkout's native dependencies.
In a disposable checkout, temporarily replace packages/app/index.ts with:

tsx

import "./src/polyfills/install-early";
import "./src/styles/unistyles";
import { registerRootComponent } from "expo";
import NativeRingRegression from "./e2e/mobile/status-ring/native";
registerRootComponent(NativeRingRegression);

Start Metro in packages/app:

APP_VARIANT=development npx expo start --localhost --port 8096

With one Android emulator running, open that bundle:

agent-device open sh.paseo.debug 'exp+voice-mobile://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8096' --platform android --session status-ring --metro-port 8096

From the repository root:

node packages/app/e2e/mobile/status-ring/android.mjs status-ring http://127.0.0.1:8096

The test checks visible rotation, hidden-panel inactivity while another ring is
visible, inactivity with both panels hidden, and synchronized resumption. Each
sample reads counters on the UI runtime; elapsed time includes device-command
latency. The baseline fails at the first hidden-panel assertion.

Restore the original packages/app/index.ts, close the agent-device session,
and stop Metro afterward. The fixture substitutes running rings for a live agent
and toggles retained panels directly; it does not exercise workspace navigation
or measure whole-app CPU usage. It is excluded from routine unit tests because
it requires a native runtime.

Overview (`packages/protocol/src/generated/validation/README.md`)

Generated protocol validators

ws-outbound.aot.ts is generated by zod-aot from packages/protocol/codegen/generated/ws-outbound.compile.ts, which the generator writes along with ws-outbound-schema-metadata.ts.

Run:

bash

npm run generate:validators --workspace=@getpaseo/protocol

The generated TypeScript is intentionally gitignored. zod-aot is exact-pinned because this is a young solo-maintainer project; keep the generated validator behind protocol regression tests when upgrading it.

Ad Hoc Daemon Testing (`docs/ad-hoc-daemon-testing.md`)

Ad-hoc daemon testing

Spin up an isolated in-process daemon test harness without touching the main daemon on port 6767.

This is for test code only. Executable daemon processes must start through
scripts/supervisor-entrypoint.ts or dist/scripts/supervisor-entrypoint.js;
do not use createPaseoDaemon as a product launch path.

Quick start

text

/* Detailed source-code truncated for AI context efficiency. */

Run with:

bash

npx tsx packages/server/src/server/your-script.ts

Using the test helper

For simpler cases, createTestPaseoDaemon + DaemonClient handles temp dirs and port selection:

typescript

import { createTestPaseoDaemon } from "./test-utils/paseo-daemon.js";
import { DaemonClient } from "./test-utils/daemon-client.js";

const daemon = await createTestPaseoDaemon();
const client = new DaemonClient({
  url: `ws://127.0.0.1:${daemon.port}/ws`,
  appVersion: "0.1.70",
});
await client.connect();
await client.fetchAgents({ subscribe: {} });

// ... test ...

await client.close();
await daemon.close(); // stops daemon + cleans up temp dirs

The test helper does not expose providerOverrides. In test harnesses, use createPaseoDaemon directly when you need it (see quick start above).

Common client methods

typescript

// Provider discovery
const snapshot = await client.getProvidersSnapshot({ cwd: "/tmp" });
const models = await client.listProviderModels("claude");
const modes = await client.listProviderModes("claude");

// Agent lifecycle
const agent = await client.createAgent({ provider: "claude", cwd: "/tmp" });
await client.sendMessage(agent.id, "Hello");
const updated = await client.waitForAgentUpsert(agent.id, (s) => s.status === "idle");

Gotchas

1. appVersion gates provider visibility

The daemon hides non-legacy providers (anything other than claude, codex, opencode) from clients that don't send an appVersion >= 0.1.45. The DaemonClient sends no version by default, so custom providers like ACP-based ones will be invisible in snapshot responses.

Always pass appVersion:

typescript

const client = new DaemonClient({
  url: `ws://127.0.0.1:${port}/ws`,
  appVersion: "0.1.70",
});

2. Provider snapshots are async

After the daemon starts, providers are probed in the background. The first getProvidersSnapshot() call will likely return status: "loading" for most providers. Poll until the provider you care about is no longer loading:

typescript

let snapshot = await client.getProvidersSnapshot({ cwd: "/tmp" });
for (let i = 0; i < 20; i++) {
  const entry = snapshot.entries.find((e) => e.provider === "gemini");
  if (entry && entry.status !== "loading") break;
  await new Promise((r) => setTimeout(r, 2_000));
  snapshot = await client.getProvidersSnapshot({ cwd: "/tmp" });
}

3. fetchAgents is required before most operations

Call client.fetchAgents() after connecting. The daemon session expects this handshake before it processes other requests — without it, messages like get_providers_snapshot_request will silently hang.

4. listen: "127.0.0.1:0" for port allocation

Always use port 0 so the OS picks a free port. Never hardcode a port — it will collide with the main daemon or other test runs.

5. Script must live inside packages/server

The test utilities use relative imports through the TypeScript project. Place your script somewhere under packages/server/src/ and import from there. Scripts outside the repo will fail with module resolution errors.

6. Cleanup on failure

Wrap your test logic in try/finally to ensure the daemon stops and temp dirs are cleaned up, even if an assertion fails:

typescript

try {
  // ... test logic ...
} finally {
  await client.close();
  await daemon.stop().catch(() => undefined);
  await rm(paseoHomeRoot, { recursive: true, force: true });
}

7. ACP providers spawn real processes

When testing ACP providers (e.g., Gemini with extends: "acp"), the daemon will spawn real processes to probe for models and modes. The binary must be installed and on PATH. Probing can take 5-15 seconds depending on the provider.

Agent Lifecycle (`docs/agent-lifecycle.md`)

Agent lifecycle

How an agent is created, runs, becomes a subagent, gets archived, and disappears from the UI. The model spans the daemon (lifecycle, archive) and the client (tabs, the subagents track).

States

text

initializing → idle → running → idle (or error → closed)
                 ↑        │
                 └────────┘  (agent completes a turn, awaits next prompt)

Each live agent in AgentManager carries a lastStatus of initializing, idle, running, or error. closed is the persisted, resumable state for an agent record that has no live provider runtime. State transitions persist to disk and stream to subscribed clients via WebSocket.

Runtime residency

An unarchived agent may be closed without being deleted or archived. Closing releases its provider
processes and subscriptions while retaining its Paseo identity, persistence handle, timeline,
workspace, labels, title, usage, attention, timestamps, and parent relationship. Opening or prompting
the agent runs through ensureAgentLoaded(), which resumes the durable provider session under the
same Paseo agent ID. Provider history is not appended again when the canonical timeline is already
primed.

Reload releases the old runtime before resuming its durable session: an idle provider process can
still own an exclusive writer. A close failure retains that runtime for cleanup and blocks the
replacement. Once closure succeeds, a failed resume leaves the durable agent closed and retryable.

Idle agents remain resident indefinitely. Runtime closure happens only through an explicit lifecycle
action such as archive, replacement, reload, workspace teardown, or daemon shutdown.

A provider runtime can still die on its own — crash, OOM kill, host suspend. Work the agent parked
inside that process dies with it: Claude Code's background Bash shells, Monitor watches, and
workflows all live in the CLI process, and the completion notification that would have woken the
agent never arrives. A runtime that dies mid-turn is reported by whatever is draining its stream, but
between turns nothing is watching, so the agent sits at idle looking healthy while its background
work is gone. Report that exit as a turn failure so the agent lands in error with a timeline entry.
Claude and OMP report exits between turns. OMP relaunches from its session file on the next prompt;
the unfinished turn is lost.

Cancellation

Provider interruption is idempotent at the AgentSession boundary. It resolves when the prior
foreground turn can no longer run, including when the provider reports that it is already idle. It
rejects only when the provider may still own the turn. Provider adapters translate native errors
into that contract; lifecycle callers do not interpret provider-specific errors.

After an acknowledged interrupt, the manager settles the captured run even when no terminal event
arrives or the run was still waiting for its provider turn id. The captured run token prevents an
older cancellation from settling a newer turn. If interruption is rejected or times out, the agent
keeps its active foreground turn and replacement, reload, rewind, and Stop report the failure.
Accepting new work after an ambiguous interruption would create a split-brain session.

Relationships

Agents can launch other agents via the agent-scoped create_agent MCP tool. Agent-scoped creation is always asynchronous and always stamps paseo.parent-agent-id, pointing back at the caller. Omit workspaceId to use the caller's workspace, or pass an existing workspace ID returned by create_workspace. Placement never changes parentage.

Subagents — exist as part of the creating agent's work, appear in that agent's subagent track, and are archived with it.
Detached agents — stand on their own after an explicit detach transition, do not appear in the former parent's subagent track, and are not archived with it.

Parent archive detaches a subagent instead of archiving it when either condition holds:

The child belongs to another workspace.
The child is currently open in an agent tab.

All other children archive with the parent. After the workspace layout hydrates, the client marks
every managed subagent present in its tabs with paseo.open-agent-tab.<client-id>=true through the
generic agent metadata update. This includes background and restored tabs; navigation does not own
the marker. Closing a tab sets that client's label to false. Any true client label keeps the child
open. Detach clears the parent and every open-tab label. The surviving child therefore becomes a
normal root agent immediately, and closing its still-open tab archives it.

Runtime ownership is resolved from explicit workspace ID and caller context, never from cwd. Workspace creation is a separate operation with local | worktree isolation; agent creation reuses that workspace unless a new workspace is explicitly requested.

Setup belongs to the workspace, including combined workspace-plus-agent creation and the supported agent worktree request. Run setup through the workspace workflow before launching configured terminals or scripts. Setup output is read in the Setup panel from per-command snapshots; never produce setup chat timeline rows or concatenate command logs. Legacy agent git/worktreeName inputs and hidden MCP worktree placement are rejected with workspace-creation guidance. Existing wire schemas retain an empty combined-log string for parsing compatibility.

Users can also detach an existing subagent from the subagents track. Detach is deliberately a manual lifecycle gesture, not an agent-facing MCP tool. It removes the parent and open-tab lifecycle labels: it does not stop, archive, move, or restart the agent. The agent keeps its current cwd and workspaceId, leaves the former parent's track, and behaves like a root agent for tab close, workspace activity, and future parent archive.

notifyOnFinish defaults to true for agent-scoped creation and prompt follow-ups because most delegated work needs to report back to the creating agent. Set it to false for explicit reporting or no completion callback.

Agent-originated messages and automatic notifications share a recipient-daemon delivery module. A queued receipt acknowledges admission before provider dispatch, allowing a child to report and finish in the same two-second quiet window. Human prompts dispatch directly. Conflicting explicit interruption or session-mode choices retain separate ordered dispatches.

The pending window is in memory. Clean shutdown flushes it before closing agents; an abrupt crash can lose it. A durable send receipt remains pending until actual dispatch acknowledgment, so a lost window never becomes a completed receipt. Completion waits cover queued admission within their original timeout and cancellation scope.

Permission requests are notification checkpoints, not the end of that subscription. The caller is notified again after a permission response when the child finishes, errors, or requests another permission.
The permission notification includes the normalized request plus the child and request IDs, so the caller can inspect it and respond without fetching agent status.
A watched child that closes before its finish event also notifies the caller so delegated work cannot disappear silently during archive or workspace teardown.

Provider-managed child agents

Some providers can create their own child sessions inside one provider runtime. OMP's task tool reports these with child_session events; AgentManager imports the live provider handle, stamps paseo.parent-agent-id, and surfaces the result as a normal subagent in the parent's subagents track.

The provider still owns the underlying runtime. Paseo keeps an agent record so the child can be opened, tracked, archived, and cascaded with the parent, but prompts and history hydration route through the provider adapter for that native child handle.

Background workspaces

workspace.background controls discovery only. Background workspaces contain ordinary durable
agents and terminals: provider history, plugin hooks, parentage, archive, and restart recovery
keep their normal behavior. Visibility is creation-only; selecting an existing workspace cannot
change it. New workspaces default to false, inherit the caller workspace's value when an agent
creates one without an override, and accept explicit true or false.

The daemon derives agent discovery from workspace ownership. Default workspace and agent lists,
including History requests, exclude background work; filter.includeBackground includes it.
Exact-ID operations bypass discovery filtering. The app replicates both kinds and filters only
its sidebar with Show background, so direct navigation and restored tabs remain available.

Sequenced directories keep complete canonical collections. A filtered read must never replace
those collections with its subset. Inclusive and default observations have distinct cursor
scopes, so changing scope requires a fresh snapshot rather than reusing an incomplete cache.
Clients gate creation and inclusive discovery on features.backgroundWorkspaces.

Private daemon helpers

Branch-name and commit-message generators still use private disposable internal runtimes.
AgentManager does not persist them or their provider sessions, excludes them from public
discovery and plugin hooks, and drops their timelines on archive. An archived helper retains
its exact-ID result briefly to cover completion before a waiter attaches. This internal
lifecycle is separate from public workspace visibility and is not a public creation option.

Tabs vs archive

These are two distinct concepts that used to be conflated:

Concept	Scope	Triggers
Tab (workspace layout)	Per-client	User opens/closes a view
Archive (lifecycle)	Global	Explicit lifecycle gesture

Closing a tab on a root agent still archives — the tab is the agent's home, so closing it means "I'm done with this agent." A confirm dialog protects against archiving a running agent by accident.

Closing a tab on a subagent (any agent with parentAgentId) is layout-only. The app clears the current client's open-tab label before removing the tab. Another client's open tab remains protected. The agent stays unarchived and stays in its parent's track, so a later parent archive cascades to it when no client still has it open. The user can re-open the tab from the track at any time. Single and bulk tab close apply the same policy.

The asymmetry is intentional: a subagent's persistent relationship lives in the parent's track. Same-workspace subagents are not auto-opened as tabs; the user opens one from that track when needed. A cross-workspace subagent is also auto-opened as a tab in its own workspace so opening that workspace does not appear empty. It remains in the parent's track until it is actually detached.

Workspace activity

Agent lifecycle status stays literal: a parent agent is idle when its own turn is idle, even if a child is running.

Workspace status is an aggregate activity signal computed per workspaceId. Ownership is never derived from cwd — many workspaces may share one directory, and same-cwd siblings do not clump under one status. Root agents and cross-workspace subagents contribute their normal state bucket to their own workspace. Same-workspace descendants contribute running to the nearest ancestor in that workspace; their non-running attention, permission, and error states stay in the parent's subagents track. This makes a cross-workspace subagent behave like a detached agent for workspace visibility and status without removing its parent relationship.

Running provider-native subagents contribute running to the workspace owned by their parent agent. Their completed, failed, and canceled states stay in the parent's subagents track.

A finished workspace can be marked unread after it has been reviewed. The daemon restores
finished attention on its newest eligible workspace-root agent without sending a new completion
notification. Opening the workspace clears that attention through the normal focus flow.

Attention is set by the agent finishing or failing and cleared by the client's
workspace.clear_attention, which fires when the user reads the chat. Loading an agent's runtime is
neither, so resuming carries the stored attention and the stored last-activity time through
untouched. Forging either makes a background resume look like the user read a workspace and like the
agent worked in it just now, which rewrites the sidebar timestamp permanently — persisted
updatedAt is what workspace statusEnteredAt is re-derived from on the next daemon start.

The subagents track

The track is a pill at the foot of an agent's pane (packages/app/src/subagents/track.tsx): a count you can read at a glance, and a panel behind it — a popover on wide screens, a sheet on compact ones — holding the rows. It floats over the transcript rather than sitting in a band above the composer, so the timeline scrolls underneath it; packages/app/src/panels/agent-tracks.tsx owns that placement, and the pill frame is shared with the task list in packages/app/src/composer/tracks.tsx.

The rows combine two kinds of children:

Paseo subagents are full managed agents. Their membership rule (packages/app/src/subagents/select.ts) is:

text

parentAgentId === thisAgent.id  AND  !archivedAt

Provider subagents are child executions owned by Claude, Codex, or OpenCode. They are not inserted into AgentManager as managed agents. Providers emit a separate descriptor and timeline stream through agent.provider_subagents.*; the client keeps that state outside the normal agent store and merges only the presentation rows into the track. A descriptor's optional parentSubagentId identifies its direct provider-subagent parent; an absent value identifies a direct child of the managed agent.

Clicking either kind opens a workspace tab. On compact layouts it opens in a sheet over the subagents list instead; the sheet hides the composer and shows the agent's model and thinking as one line in its place (PaneSubtitle, the row provider subagents already use), and a Paseo subagent's sheet offers Open as tab (the full-screen glyph in the header) to get the composer back. A Paseo subagent tab is a normal interactive agent pane. A provider subagent tab is a read-only timeline pane with no composer, archive, detach, rewind, or fork actions. It shows its own direct children in a subagents track. Both panes use AgentStreamView, so message, reasoning, tool-call, and layout rendering stay identical.

Provider timelines use the same structural timeline item format but deliberately have a separate lifecycle and transport. A provider thread/session identifier is not a Paseo agent identifier, and closing its tab is always layout-only.

Provider descriptors may include one compact subtitle. The provider owns its contents and formatting; clients display and truncate it without interpreting provider-specific model, thinking, or usage fields.

Claude provider subagents: the task protocol

Claude Code announces subagent lifecycle on the SDK stream (task_started / task_updated / task_notification / task_progress), and Paseo reads those announcements rather than reconstructing them from sidechain frames. The live source (subagents/live-source.ts) and the replay source (subagents/replay-source.ts) both translate into one observation vocabulary (subagents/observation.ts), so a fact is derived once for both paths instead of once per path. Gotchas that are not obvious from the SDK types:

Not every announced task belongs in the track. Task subagents announce as local_agent and workflows as local_workflow; a backgrounded shell announces as local_bash with the same tool_use_id shape, and ambient housekeeping sets skip_transcript. The Claude provider normalizes a workflow to a generic provider-subagent descriptor titled Workflow, using Claude's summary as its description and timeline opener. Shared storage, protocol, and UI do not distinguish it from another provider subagent.
A task that was never declared gets no descriptor, by any route. Filtered tasks still emit task_notifications carrying a tool_use_id, and still emit frames carrying parent_tool_use_id. Attributing either produces a descriptor with no identity and a defaulted running status — a nameless row that never finishes. Status, presentation updates, and sidechain frames all route through the declaration table.
Task ids are session-scoped, not turn-scoped. Cancelling a turn must not clear the routing table: a backgrounded child settles after the interrupt and needs its descriptor to still exist. Cancellation instead terminalizes the declared children that were running in the foreground, and a later task_notification is free to correct that guess. Backgrounded children are identified by is_backgrounded on task_started (set at spawn; a resumed subagent is always background) or, when moved there later, on task_updated.patch.
A resumed task can be announced again with a new tool_use_id. The first Task tool id remains the canonical descriptor and later ids are routing aliases for the same session-scoped task. The resumed prompt is added to that child timeline.
Effort is only reachable through hooks. It appears nowhere on the message stream at any depth, and the level Paseo requests is not necessarily the level that runs — a model that does not support it is silently downgraded. A hook firing inside a subagent reports the active post-downgrade level next to its agent_id, which is the same id task_started calls task_id.
Backgrounded subagents emit no frames carrying parent_tool_use_id at all. Everything keyed off that field sees nothing for one; they are visible only because the task protocol announces them.
Only system/init and result bracket a main-session turn. Background subagents emit neither on the main stream, while their task frames, their own background jobs' task_notification, and rate_limit_event arrive with no parent_tool_use_id, the same shape as main-session work. session_state_changed stays running for as long as any background subagent lives (Claude Code 2.1.280), so it cannot open a turn; its idle can close one.
Nested ownership comes from the launching sidechain, not spawn_depth alone. A sidechain's Agent or Bash tool call records the direct owner of that tool_use_id; the following task_started inherits it. This routes a grandchild descriptor and child-owned background notifications without relying on labels or flattening them into the managed parent.
On replay, <session>/subagents/ holds every descendant beside the root. Resolve the tree one proven generation at a time: the root transcript admits direct children, then each admitted sidechain transcript admits its children by toolUseId. spawnDepth orders candidates but does not establish ownership. Unresolved sidecars remain excluded as ambient or unrelated work.
Replay totalTokens is a context-size reading, not cumulative spend. Claude Code finalizes a subagent by summing the last assistant message's usage block and shipping that as usage.total_tokens. Summing per-entry usage instead multiplies the cached prefix by the turn count and reports a number several times larger than the live path.

Archived Paseo subagents disappear from the track, by design. To remove one from the track without closing its tab, use the archive button on the row — it opens a confirm dialog and archives the subagent on confirm. Provider-owned rows have no individual Paseo lifecycle controls.

The Archive finished row at the foot of the panel covers every finished row. It archives idle or errored managed Paseo subagents one at a time, and hides completed, failed, or canceled provider-owned rows in the current app session. Native sessions and timelines are untouched. Running and initializing children remain in the track. If a hidden provider child starts running again, the app brings it back to the track.

To keep the agent alive but remove it from the parent's track, use detach. The daemon clears the relationship lifecycle labels, emits the normal agent update, and every client reclassifies the agent from subagent to root/sibling from that updated snapshot.

Why this shape

The decision was to decouple "close tab" from "archive" only for subagents, rather than universally:

Closing a tab on a root agent still archives — preserves the existing UX users are trained on
Closing a tab on a subagent is layout-only — fixes the lossy "click to read, close to dismiss view, lose the row" flow
Archive button on track rows — gives subagents an explicit lifecycle gesture in their home surface
Detach button on track rows — lets a subagent continue independently without killing its work
Cascade archive on parent — keeps subagents from leaking when the parent is archived

We considered universal decoupling (no tab close ever archives, archive is always explicit) but rejected it: it changes a behavior root-agent users rely on.

Limitations

Subagent accumulation under long-lived parents

A parent that spawns many subagents will see the panel's list grow; the pill only counts them. Managed Paseo subagents can be archived individually or with Archive finished. That action hides finished provider-owned rows locally; this presentation state resets when the app restarts.

Cross-client tab dismissal

Closing a subagent's tab on one client doesn't affect other clients' layouts. This is the expected behavior of decoupled tabs and is consistent with how layouts have always worked. Archive remains the global gesture for cross-client cleanup.

Storage

text

$PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json

{cwd-with-dashes} is derived from the agent's filesystem cwd. It is not the workspace id; agent storage stays cwd-keyed while workspace identity is the opaque workspace id.

Each agent is a single JSON file. Fields relevant to this doc:

Field	Type	Meaning
`id`	`string`	Stable identifier
`archivedAt`	`string?`	Soft-delete timestamp (ISO 8601)
`labels["paseo.parent-agent-id"]`	`string?`	Parent agent ID, set automatically for agent-scoped creation and removed by detach
`labels["paseo.open-agent-tab.<client-id>"]`	`string?`	`"true"` protects an open tab on that client; detach clears every matching label
`lastStatus`	`AgentStatus`	`initializing` / `idle` / `running` / `error` / `closed`

See docs/data-model.md for the full agent record.

Agent Stream Performance (`docs/agent-stream-performance.md`)

Agent stream performance

How assistant text gets from a provider to the screen, and why it is paced on the way. Read this before changing packages/server/src/server/agent/agent-stream-coalescer.ts, the reducer queue in packages/app/src/timeline/session-stream-reducers.ts, or the reveal in packages/app/src/hooks/use-revealed-text.ts.

For terminal output, which is a separate pipeline with separate budgets, see terminal-performance.md.

The pipeline

text

provider deltas (every provider streams incrementally)
  → AgentStreamCoalescer (daemon, leading + trailing, ≤1 message per 60ms per agent)
  → recordTimeline: one canonical row per flushed item
  → agent_stream ws message
  → reducer queue (app, one commit per frame) → session store
  → source-item plugin transforms → Markdown presentation / tool grouping
  → paced reveal (app, per displayed item) → paint

Every provider delivers incremental text, so there is no provider that needs special handling: Claude via includePartialMessages, Codex via agent_message_delta, ACP agents via agent_message_chunk, Pi and OMP via text_delta.

Why the reveal is paced

Arrival is lumpy and there is no fixing that at the source. A 60ms coalescing window carries however many characters the model produced in those 60ms, which swings by an order of magnitude within a single turn. Painting each delta as it lands makes the size of those lumps visible, and that is what reads as jagged.

So arrival sets a target and the reveal rate is derived from the backlog instead. A burst makes the text catch up faster; it does not make the text jump. Shrinking the coalescing window does not fix this — it makes the lumps smaller and more frequent, at the cost of message rate on a daemon loop that already contends with terminal frames and per-message relay encryption.

Invariants

The coalescer is leading + trailing. The first delta after an idle window flushes synchronously; only the rest of the burst waits for the trailing timer. Reverting to trailing-only adds a full window to the first character of every turn. Same shape and the same reason as TerminalOutputCoalescer.
The leading flush adds a canonical row, and that is fine. A burst's first chunk lands as its own timeline row. mergeAssistantChunks / mergeReasoningChunks in timeline-projection.ts join contiguous same-turn rows, and clients read the projected timeline, so history is unaffected. Tests that assert on raw rows have to account for the extra row; tests that assert on what a client sees do not.
The store holds the full text; only the rendered slice is paced. Copy, selection, the chat outline, and scroll geometry all read the same string the user can see. Pacing the store instead would leave the bottom anchor chasing a content height that is ahead of the reveal.
One source assistant message is one display row. Presentation projects plugin output and caches unchanged history. The shared Markdown renderer owns rendering on every platform. Chat paces the visible source and applies a 32,000-character render cap on web; native keeps the complete message. The native renderer keeps closed blocks in a stable head and sends the paced suffix to a separate tail view during streaming; completion reunites them for selection. This stays inside the renderer, without promoting blocks into timeline history.
Message identity survives completion. Assistant row ids are source message ids. Plugin rows can replace a source, so find, scroll-to-message and history reveal still use getStreamItemMessageId. Width-specific measurements describe whole rendered messages.
First sight of a text is revealed whole. Only growth is paced. This is what makes history hydration, timeline replay, a virtualized row remounting on scroll, and an already-finished message all render complete on first paint without a special case for each.
Leaving phase: "streaming" snaps the reveal. A completed turn must never be left holding characters. layoutStream sets the phase, so anything outside the live head with an active turn is already complete.
The reducer queue commits on a frame, with a timer as the ceiling. A frame callback never fires in a hidden tab, so a timer races it and wins when nothing is painting — the store has to keep advancing either way.
A history row re-renders only when its item or layout item identity changes. The inverted
FlatList hands every mounted cell a new index and ref whenever a row is prepended, so without a
memo boundary each coalesced tick re-rendered every mounted row (about 50 on a phone, 100–250 ms of
JS per tick). layoutStream keeps a layout item's identity when nothing about it changed,
useRevisedHistoryRows hands a fresh item identity to rows whose tool-call group, expanded state,
or breakpoint changed, and StreamRow memoizes on both. Every viewport runs its history
through that hook; the web viewport once skipped it and history hosts of a live tool group went
stale. A new field on StreamLayoutItem must be added to areLayoutItemsEquivalent, or sharing
silently stops.
Streaming cost must not grow with revealed history. Reading older messages must not
make the next reply progressively more expensive to display. Reuse unchanged history work
while text arrives, and release obsolete window caches as the reader reveals more history;
window caches must stay bounded while their source timeline remains loaded.

Native parsing cost

The native library reparses and measures its entire markdown prop on each update. During streaming, the renderer splits source at an mdast block boundary and memoizes the head, so per-frame updates parse only the tail. Boundary discovery runs when a source line completes, rather than on every reveal frame. The unfinished line and final parsed block stay in the tail, preserving list continuation, setext headings, tables and open fences. Reference-dependent source and HTML retain a larger tail because later source can change their meaning. A single long block therefore still carries its full parsing cost.

Completion restores one native text view per Mermaid-delimited segment, so selection crosses prose paragraphs again. The head retains its trailing block margin while split. JS reveal remains the pacing source; native opacity animation stays disabled.

Measuring

Smoothness (user-perceived): packages/app/e2e/browser/agent-stream-smoothness.spec.ts, gated behind PASEO_AGENT_STREAM_PERF_E2E=1. Drives the mock provider's bursty-stream model and reports coefficient of variation of characters painted per frame (smoothness) plus p95 gap between visible updates (stalls). Both numbers are needed: a stalled stream is perfectly smooth.
Reproducing bursty arrival: the bursty-stream model in mock-load-test-agent.ts emits uneven runs of tokens separated by idle gaps. Burst sizes come from a seeded generator, so a run repeats exactly.
Rate policy in isolation: computeRevealStep in packages/app/src/agent-stream/text-reveal.ts is pure; text-reveal.test.ts covers convergence and burst flattening without a renderer.
Per-delta cost on a long timeline: npx vitest bench --project unit src/agent-stream/stream-tick.bench.ts from packages/app replays 200 deltas over a 2,000-item timeline through the pure model and layout pipeline, with the default mounted window and with history fully revealed. It measures the JS work per delta, not paint.

Healthy numbers (2026-08, Expo web against a local dev daemon, real Claude Haiku agent, ~8.5s samples during active streaming). Setting TEXT_REVEAL_HORIZON_MS to 0 makes the reveal paint on arrival, which is how the baseline column was taken:

	paint on arrival	paced
frames that advanced the text	6%	87%
chars-per-frame CV	4.11	1.86
gap between visible updates, p50	317ms	17ms
gap between visible updates, p95	383ms	17ms

Total characters painted is roughly the same either way — the reveal changes when they land, not how many arrive.

Measure the total length across every assistant-message element, not the last one. A turn emits many assistant messages, so the tail element keeps changing identity and its length is not monotonic; sampling only the tail reads those handovers as resets and reports almost no growth. sampleStreamFrames does this correctly.

Android (`docs/android.md`)

Android

App variants

Controlled by APP_VARIANT in packages/app/app.config.js (vanilla Expo, no custom Gradle plugin):

Variant	App name	Package ID
`production`	Paseo	`sh.paseo`
`development`	Paseo Debug	`sh.paseo.debug`

EAS profiles: development, production, and production-apk in packages/app/eas.json.

development uses Android debug.

Version codes

packages/app/native-release-version.js is the single definition of native and F-Droid version-code math. Do not re-derive these numbers anywhere else — a drifted copy produces changelog files that match no published APK, and nothing fails loudly.

The base version code comes from the package version:

text

major * 1_000_000 + minor * 1_000 + patch

Prerelease metadata is ignored, so 0.1.102-beta.1 and 0.1.102 both produce 1102. The same value is used as the iOS buildNumber because packages/app/eas.json uses EAS's local app version source. Do not re-enable EAS remote version counters or Android autoIncrement; F-Droid and other source-based builders need the native build number to be visible in the repo.

The formula reserves three digits each for minor and patch. If either reaches 1000, change the formula before cutting that release.

Prerequisites (local dev)

Local Android builds run on macOS (or Linux) and need the Android toolchain, pinned in .tool-versions (java 21, android-sdk 21.0) and wired up by .mise.toml (which derives ANDROID_HOME and the command-line tool paths from the android-sdk entry). With mise:

bash

mise install        # java 21 + android-sdk 21.0 command-line tools

Pin a real android-sdk version, not latest. The mise android-sdk plugin's latest resolved to the ancient 1.0 bundle, whose sdkmanager (3.6.0) predates the emulator package and fails with Failed to find package emulator. 21.0 ships a current sdkmanager. If you bump it, update only the version in .tool-versions; .mise.toml derives its paths from that tool entry.

mise install only lays down the command-line tools. Install the rest and create an emulator. On Apple Silicon:

bash

sdkmanager --licenses
sdkmanager "platform-tools" "emulator" "platforms;android-35" "build-tools;35.0.0" \
           "system-images;android-35;google_apis;arm64-v8a"
avdmanager create avd -n paseo -k "system-images;android-35;google_apis;arm64-v8a" -d pixel_7
emulator @paseo     # start it; leave running

On an Intel Mac, use the x86_64 system image:

bash

sdkmanager --licenses
sdkmanager "platform-tools" "emulator" "platforms;android-35" "build-tools;35.0.0" \
           "system-images;android-35;google_apis;x86_64"
avdmanager create avd -n paseo -k "system-images;android-35;google_apis;x86_64" -d pixel_7
emulator @paseo     # start it; leave running

Gradle auto-fetches the platform/build-tools it needs once licenses are accepted, so adjust android-35 only if it asks for a different level.

Local build + install

The locked [email protected] needs the patch installed by npm install.
It backports
Expo's Activity-result launcher fix: changing
font size or another unhandled configuration can otherwise disable image selection
until the app process restarts. Rebuild the native app after changing this patch;
a Metro reload cannot update it. Remove the patch when the installed
expo-modules-core includes the fix.

Run its native regression tests from packages/app/android after prebuild:

bash

./gradlew :expo-modules-core:testDebugUnitTest \
  --tests expo.modules.kotlin.activityresult.AppContextActivityResultRegistryRecreationTest \
  --no-daemon --max-workers=1 -Dorg.gradle.parallel=false

From repo root:

bash

npm run build:apk       # Universal dogfood APK: 32/64-bit ARM and x86
npm run build:apk:arm64 # Smaller dogfood APK for ARM64 phones
npm run dev:android     # Build/install the debug app and start development
npm run dev:ios         # Build/install the iOS development app

build:apk writes artifacts/paseo-dogfood-universal.apk; build:apk:arm64 writes
artifacts/paseo-dogfood-arm64.apk. Neither command launches or installs on a device. Both enable
PASEO_WATCHDOG_BUILD=1, the production React profiling renderer, and Android's shell-profileable
flag. These builds keep the production package ID (sh.paseo) and release optimizations. Use this APK for
personal dogfooding. Android system-trace spans require the separate PASEO_PROFILE_BUILD=1 flag;
watchdog recording does not send duplicate spans to that sink by default. Normal store/release
workflows leave diagnostics disabled.

The older android, android:development, and ios commands remain aliases for development.
android:production still builds and installs a release through Expo; use build:apk when you
need an artifact. android:clear removes the generated Android project.

Run npm run test:android --workspace=@getpaseo/app to prebuild Android and run native module unit tests. The app CI job runs this command with the Android toolchain.

Diagnostic logs without ADB

In a dogfood build, open Android's Files app → Downloads → Paseo diagnostics and share all
retained .jsonl files. No app screen, storage permission, or attached debugger is required.
The recorder retains eight files of about 5 MiB each across reconnects and app restarts. Rotation
replaces the oldest files, so collect them soon after reproducing a freeze. Uninstall/reinstall
can leave older Downloads files that the new installation cannot manage.

Each file identifies its build and session. Events include application-transport frame sizes and
message/request IDs, connection transitions, parse/validation/dispatch spans, named React subtree
render timings, and foreground JS heartbeat gaps. Payloads, passwords, and message contents
are excluded; connection identifiers include host addresses. Each size has a unit: bytes when
already available, otherwise UTF-16 code units for text. These are
client transport observations, after relay decryption where applicable, not packet arrival times.

The native recorder flags a heartbeat overdue by more than 500 ms (250 ms expected interval).
A heartbeat gap bounds the unresponsive interval; it is not an exact blocked-stack duration.
Backgrounding suspends detection. js.stall.started can be written while JS remains blocked;
js.stall.recovered records the gap when JS resumes. Recovery can appear without a start event
when JS resumes before the next native sampling tick. Process death leaves earlier files intact,
but queued/unflushed records can be lost. A missing recovery event alone does not prove a crash.

react.render.slow records subtree rendering taking at least 16 ms; one-second summaries include
faster renders. Nested profiler timings overlap: don't add parent and child times. React's render
measurements do not measure native layout/paint or the complete commit phase. recorder.dropped
means the bounded queue overflowed; missing events in that interval must not be treated as absence
of activity. Storage failure stops recording rather than blocking the app.

For an ordinary release APK with system trace markers only:

bash

PASEO_PROFILE_BUILD=1 npm run android:production

Those markers emit only while a system trace records sh.paseo (perfetto -a sh.paseo ...);
they do not produce Downloads files.

Running on an emulator against a worktree daemon

npm run android builds and installs the dev client, but two connections have to reach your Mac from inside the emulator — Metro (the JS bundle) and the Paseo daemon — and the emulator does not share the host's loopback: localhost inside the emulator is the emulator itself. Reach the host at 10.0.2.2 (the standard AVD's host alias) for both:

bash

REACT_NATIVE_PACKAGER_HOSTNAME=10.0.2.2 \
  EXPO_PUBLIC_LOCAL_DAEMON=10.0.2.2:$PASEO_SERVICE_DAEMON_PORT \
  npm run android

REACT_NATIVE_PACKAGER_HOSTNAME=10.0.2.2 — without it, Expo bakes your Mac's LAN IP into the dev client's Metro URL, which the emulator can't route to, and the app dies with Failed to connect to /<lan-ip>:8081 before any JS loads.
EXPO_PUBLIC_LOCAL_DAEMON=10.0.2.2: — the client's daemon endpoint (packages/app/src/runtime/host-runtime.ts); when unset it defaults to localhost:6767, the production daemon. Use $PASEO_SERVICE_DAEMON_PORT for a worktree daemon running as a Paseo service, or 6768 for a standalone npm run dev:server. It is inlined into the JS bundle at Metro bundle time, so set it on the build command and clear the Metro cache (npx expo start -c) if a change doesn't take.

Alternative — adb reverse + localhost (if 10.0.2.2 misbehaves):

bash

adb reverse tcp:8081 tcp:8081
adb reverse tcp:$PASEO_SERVICE_DAEMON_PORT tcp:$PASEO_SERVICE_DAEMON_PORT
REACT_NATIVE_PACKAGER_HOSTNAME=localhost \
  EXPO_PUBLIC_LOCAL_DAEMON=localhost:$PASEO_SERVICE_DAEMON_PORT \
  npm run android

This is the Android counterpart of the iOS local-simulator flow in development.md: on iOS the simulator shares the Mac's loopback so localhost: works directly; on Android you need 10.0.2.2 or adb reverse.

Inverted timeline selection

Android focus and selection visibility requests must not reposition inverted timelines. The
modules/paseo-scroll package keeps React Native's scroll manager interface and returns zero for
child-reveal scroll calculations when the view's transform matrix inverts the vertical axis. React
Native's Android list uses scale: -1, which decomposes into a 180-degree rotation with positive
scaleY; checking the scale property alone misses it. Dragging and explicit scroll
commands still work; non-inverted scroll views keep Android's default behavior.

Register this package before React Native's core package through its Expo config plugin. Normal
Android builds use the prebuilt react-android library, so patching Java under node_modules does
not change the shipped scroll view. Keep this behavior in the app's compiled native module.

F-Droid / source-only Android builds

F-Droid builds should set PASEO_FDROID_BUILD=1 when running Expo prebuild:

bash

cd packages/app
PASEO_FDROID_BUILD=1 APP_VARIANT=production npx expo prebuild --platform android --clean --non-interactive
cd android
PASEO_FDROID_BUILD=1 ./gradlew assembleRelease --no-daemon --max-workers=1 -Dorg.gradle.parallel=false

The flag must be present for both prebuild and Gradle because Gradle starts Metro for the release bundle. Keep the source build serial and daemon-free as shown above: compiling every Expo module can exhaust memory when Gradle workers run in parallel. The profile enables source-built Expo modules, excludes the proprietary camera, Firebase notification, and Expo development-client native modules, disables Gradle dependency metadata, and substitutes JavaScript stubs for camera and notifications. The resulting app supports direct and pasted-link pairing but not QR scanning or push notifications.

For a single-ABI APK, pass React Native's architecture property to Gradle:

bash

PASEO_FDROID_BUILD=1 ./gradlew assembleRelease \
  -PreactNativeArchitectures=arm64-v8a \
  --no-daemon --max-workers=1 -Dorg.gradle.parallel=false

Supported values are armeabi-v7a, arm64-v8a, x86, and x86_64. The F-Droid profile filters native libraries to that ABI and changes the APK version code to baseVersionCode * 10 + abiSuffix, where the suffixes are ordered 1 through 4 in that same sequence. F-Droid metadata should use four build blocks with VercodeOperation entries 10 * %c + 1 through 10 * %c + 4 and pass the matching reactNativeArchitectures value in each build command. Builds without a single architecture keep the base version code.

Keep the excluded npm packages installed. Normal builds use them, while the F-Droid profile removes only their Android native modules and config plugins. Paseo always applies expo-gradle-jvmargs with -Xmx4096m and -XX:MaxMetaspaceSize=1024m so local Expo prebuilds have enough Gradle heap whether they use precompiled AARs or source-built Expo modules.

The EAS production-apk profile uses the large Android resource class. Release builds compile the native ABIs and run Hermes bundling in the same Gradle invocation; the default worker can exhaust its remaining memory and kill Hermes with exit code 137 even when Gradle's own heap is correctly sized.

F-Droid store metadata

F-Droid reads the store listing from fastlane/metadata/android/<locale>/ at the repo root. This location provides the best compatibility with the F-Droid release process.

text

fastlane/metadata/android/
├── en-US/                      (F-Droid fallback locale, mandatory)
│   ├── title.txt               (<=50 chars)
│   ├── short_description.txt   (<=80 chars)
│   ├── full_description.txt    (<=4000 chars, limited HTML)
│   ├── images/
│   │   ├── icon.png            (512x512)
│   │   ├── featureGraphic.png  (1024x500)
│   │   └── phoneScreenshots/   (1.png, 2.png, ...)
│   └── changelogs/             (generated — see below)
├── ja/
└── zh-CN/

Locale directories generally match packages/app/src/i18n/locales.ts, but note that en becomes en-US.

F-Droid changelogs are generated from CHANGELOG.md. Run npm run fdroid:changelogs; npm run fdroid:changelogs:check verifies without writing. It is wired into the npm version lifecycle, so a release picks it up automatically and git add -A stages the result.

One changelog must be generated per-ABI-split, so each version will create four identical version-coded entries. F-Droid caps changelogs at 500 characters, so the generator strips some content and adds a link to the full notes.

Stable sync fails loudly if CHANGELOG.md has no entry for the version being cut. That is intentional — the release checklist requires the entry to be committed first, so an abort here means the checklist was skipped.

Because the generator runs off the version in package.json, it must run before the tag is created: fdroidserver only reads metadata from the tag it builds, so the file for version N has to exist in the commit N points at.

Beta releases are an explicit no-op: they do not create or rewrite F-Droid changelog files. Stable releases and promotions generate the four ABI entries from their final changelog.

React version lockstep

Keep react and react-dom pinned to the React version embedded by the current react-native release. React Native 0.81.x embeds react-native-renderer 19.1.0, so packages/app must use React 19.1.0. Bumping React to a newer patch can build successfully but crash at JS startup on Android with Incompatible React versions, leaving the app on the native splash screen.

Screenshots

bash

adb exec-out screencap -p > screenshot.png

Cloud build + submit (EAS)

Stable tag pushes like v0.1.0 trigger:

The EAS GitHub app on Expo servers, using packages/app/.eas/workflows/release-mobile.yml (iOS + Android production builds and distribution).
.github/workflows/android-apk-release.yml on GitHub Actions (APK asset on GitHub Release).

iOS distributes the same build to external TestFlight testers and App Store review; see Mobile builds (EAS) for the review paths. Android auto-submits to the Play Store via EAS-managed credentials.

Beta tags like v0.1.1-beta.1 trigger the GitHub APK workflow and EAS Release iOS Beta. They publish a GitHub prerelease APK and distribute iOS through TestFlight without submitting to production stores.

android-v* tags also trigger only the GitHub APK workflow — useful when you want to ship an APK without going through stores. The GitHub APK workflow supports workflow_dispatch with an existing tag input so you can rebuild without cutting a new tag.

Useful commands

bash

cd packages/app

# Recent builds
npx eas build:list --limit 10 --non-interactive --json | jq '.[] | {platform, status, appVersion, gitCommitHash}'

# Inspect a build (the printed `Logs` URL opens the build's Expo dashboard page,
# which has a Submissions section showing the auto-submit to the Play Store).
npx eas build:view <build-id>

The Play Console (Internal testing → Production tracks) is the final confirmation that the binary reached the store.

See docs/release.md for the full mobile-build babysitting flow.

Architecture (`docs/architecture.md`)

Architecture

Paseo is a client-server system for monitoring and controlling local AI coding agents. The daemon runs on your machine, manages agent processes, and streams their output in real time over WebSocket. Clients (mobile app, CLI, desktop app) connect to the daemon to observe and interact with agents.

Your code never leaves your machine. Paseo is local-first.

Daemon-owned outbound connections and routed API scope ownership are described in
Connected hosts.

System overview

text

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Mobile App  │    │     CLI     │    │ Desktop App │
│   (Expo)     │    │ (Commander) │    │ (Electron)  │
└──────┬───────┘    └──────┬──────┘    └──────┬──────┘
       │                   │                  │
       │    WebSocket      │    WebSocket     │    Managed subprocess
       │    (direct or     │    (direct)      │    + WebSocket
       │     via relay)    │                  │
       └───────────┬───────┴──────────────────┘
                   │
            ┌──────▼──────┐
            │   Daemon    │
            │  (Node.js)  │
            └──────┬──────┘
                   │
      ┌────────────┼────────────┬────────────┬────────────┐
      │            │            │            │            │
┌─────▼─────┐ ┌───▼────┐ ┌──────▼─────┐ ┌────▼─────┐ ┌────▼────┐
│  Claude   │ │ Codex  │ │  Copilot   │ │ OpenCode │ │   Pi    │
│  Agent    │ │ Agent  │ │   Agent    │ │  Agent   │ │ Agent   │
│  SDK      │ │ Server │ │    ACP     │ │          │ │         │
└───────────┘ └────────┘ └────────────┘ └──────────┘ └─────────┘

Components at a glance

Daemon: Local server that spawns and manages agent processes and exposes the WebSocket API.
App: Cross-platform Expo client for iOS, Android, web, and the shared UI used by desktop.
CLI: Terminal interface for agent workflows that can also start and manage the daemon.
Desktop app: Electron wrapper around the web app that bundles and auto-manages its own daemon.
Relay: Optional encrypted bridge for remote access without opening ports directly.

Packages

`packages/server` — The daemon

The heart of Paseo. A Node.js process that:

Listens for WebSocket connections from clients
Manages agent lifecycle (create, run, stop, resume, archive)
Streams agent output in real time via a timeline model
Provides agent-to-agent tools through a transport-neutral tool catalog, with MCP as one adapter
Optionally connects outbound to a relay for remote access
Optionally serves the browser web client from the same HTTP server (self-hosting guide: public-docs/web-ui.md)

All paths are under packages/server/src/.

Desktop and CLI import server capabilities through explicit package subpaths such as
@getpaseo/server/daemon-control, /configuration, and /process. The root export
loads daemon bootstrap eagerly, even when a caller only uses a path or process helper.
Keep process-management and configuration dependencies independent of bootstrap and
WebSocket message schemas. Shared configuration schemas belong in protocol leaf modules;
messages imports and re-exports them. This prevents every supervising process from
retaining the daemon's runtime and wire-schema allocations. The server export tests guard
these dependency trees with tree-shaking disabled to match unbundled production imports.

Project identity is daemon-global rather than session-owned. After registry bootstrap, the daemon's
project Git observer keeps one non-recursive watch on each lexically equivalent active project root
and listens only for the root .git entry, with a slow rescan as a missed-event fallback. It runs
for empty projects and without connected clients, then fans metadata changes through the WebSocket
server to capability-aware sessions. It deliberately does not use the broad recursive working-tree
watcher or the per-session Git observer: those are checkout/status mechanisms and intentionally do
not retain non-Git directories.

Workspace git and forge runtime data belongs to one daemon-level, directory-keyed store.
Workspace descriptors, checkout diff subscriptions, and script metadata read the last known
snapshot from that store, so reconnecting clients receive it before refresh completes.
Refcounted git watches feed the store through snapshot-updated events; their lifetime controls
refresh only. Session cleanup and workspace archive retain the data. Removing the final active
workspace for a directory clears it. The store lives in memory and resets on daemon restart.

Key modules:

Module	Responsibility
`server/bootstrap.ts`	Daemon initialization: HTTP server, WS server, agent manager, storage, relay
`server/websocket-server.ts`	WebSocket connection management, hello handshake, binary frame routing
`server/session.ts`	Per-client session state, timeline subscriptions, terminal operations
`server/directory-sync/`	Daemon-global latest-state sequences for projects, workspaces, and agents
`server/workspace-labels/`	Host-local label catalog, assignment mutations, and explicit subscriptions
`server/agent/agent-manager.ts`	Agent lifecycle state machine, timeline tracking, subscriber management
`server/agent/agent-storage.ts`	File-backed JSON persistence at `$PASEO_HOME/agents/`
`server/agent/tools/`	Transport-neutral catalog for workspaces, agents, permissions, and automation
`server/agent/mcp-server.ts`	Thin MCP adapter that registers the Paseo tool catalog with the MCP SDK
`server/agent/providers/`	Provider adapters (see "Agent providers" below)
`server/orchestration-skills/`	Bundled catalog, host selection, convergence, and skill-directory transactions
`server/relay-transport.ts`	Outbound relay connection with E2E encryption
`server/schedule/`	Cron-based scheduled agents

`packages/protocol` — Wire schemas and shared protocol types

The source of truth for WebSocket messages, binary frame codecs, endpoint parsing,
agent timeline types, provider config schemas, and other values shared by daemon
and clients. Server, app, CLI, and @getpaseo/client all depend on this package;
it does not depend on the server.

`packages/client` — Daemon client library and SDK facade

Owns the low-level daemon WebSocket driver plus the higher-level PaseoClient
facade. App and CLI may import the low-level driver from
@getpaseo/client/internal/daemon-client during migration, while new SDK-shaped
code imports from @getpaseo/client.

PaseoApi is the capability-only boundary over workspaces, agents, terminals, providers, and config.
PaseoClient adds connection lifecycle. App plugin surfaces borrow an API over their selected
host's client; plugin subprocesses use the same facade over a host-owned IPC transport. Protocol capability ownership and subscription lifetimes follow
the client contract.

`packages/app` — Mobile + web client (Expo)

Cross-platform React Native app that connects to one or more daemons.

Expo Router navigation (/h/[serverId]/workspace/[workspaceId], /h/[serverId]/agent/[agentId], etc.). The workspaceId URL segment is an opaque workspace id, not a directly meaningful filesystem path.
HostRuntimeController manages saved host connections, reconnection, and per-host runtime state. Direct TCP and relay connections use the ordinary client transport; desktop socket, pipe, and SSH connections cross one Electron-owned transport boundary. SSH only tunnels to an already-running daemon.
runtime/replica-cache is typed storage behind the directory and timeline owners. It never observes or mutates SessionStore.
runtime/directory-sync owns directory cache selection and network reconciliation. On demand it paints accepted rows for one host, then passes the persisted per-entity cursor through project.list, fetch_workspaces, and fetch_agents; the daemon returns each entity's latest projection when its sequence is newer, plus tombstones.
workspace-labels owns one sequenced catalog replica per connected host, the deterministic cross-host projection that surfaces spanning hosts use (the filter page, the manager), and the per-host resolution a workspace row's chips use. Two hosts may give one name different colors, so a row resolves against its own host's catalog and a merged answer would be wrong there. Catalogs never synchronize between hosts; assignment creates a missing definition only on the target host. On the daemon, catalog and assignment rewrites share a journaled commit boundary. Startup recovery completes that commit before workspace or catalog publication.
SessionContext wraps the daemon client for the active session
Composer UI and submit/draft behavior live in packages/app/src/composer/; screens and panels should integrate it from there instead of dropping composer internals into components/, hooks/, or screens/workspace/
Timeline reducers in timeline/session-stream-reducers.ts handle compaction, gap detection, sequence-based deduplication
Timeline sync correctness is documented in docs/timeline-sync.md: live streams are for immediacy, fetch_agent_timeline_request is authoritative, and catch-up is paged but complete.
Voice features: dictation (STT) and voice agent (realtime)

Consumers request directory or timeline data without choosing memory, cache, or network. The owner
publishes an accepted cache hit and then reconciles it over the existing network path. A miss or an
invalid row uses that same path. Offline demand still publishes an accepted cache hit and defers
network reconciliation. Cache loading is demand-driven: opening a chat reads its agent row and
focused timeline row, plus the workspace and project rows needed by the route; opening a directory
reads directory rows for that host and establishes its live subscription when connected. Accepted
cached rows satisfy the same consumer-readiness projection as network rows. Host registry startup and
host connection do not create directory demand or install replicas. The directory owner retains
declared surface demand and re-establishes network reconciliation after reconnect; React does not
track connection generations. Late cache reads cannot replace state already advanced by live or
authoritative network data. Owners explicitly persist accepted commits; directory rows and their
checkpoint share one storage transaction. See
data-model.md
for the storage shape and timeline-sync.md for timeline
resume behavior.

The three directory entity types have independent monotonic sequences and share one daemon
generation. The daemon retains only the latest projection per entity and bounded tombstones, not an
event log. A missing, expired, or previous-generation cursor receives a full snapshot. Projects are
independent records; a project with no workspaces does not need a workspace placeholder.

Workspace label definitions use a separate, explicitly subscribed sequence. The list request both
fetches and grants live updates for that session. A current cursor receives an empty correlated
catch-up response when nothing changed; idle sessions and unsubscribed sessions receive no label
traffic. Workspace assignments stay on the workspace directory sequence.

`packages/cli` — Command-line client

Commander.js CLI with Docker-style commands. Common agent operations are also exposed at the top level (e.g. paseo ls, paseo run).

paseo agent ls/run/import/attach/logs/stop/delete/send/inspect/wait/archive/reload/update/mode
paseo daemon start/run/stop/restart/status/reload/config/pair/set-password
paseo terminal ls/create/capture/send-keys/kill
paseo script ls/start/stop
paseo schedule create/ls/inspect/update/pause/resume/run-once/logs/delete
paseo heartbeat create/update/delete
paseo project create/ls/rename/delete
paseo workspace create/ls/rename/archive
paseo permit allow/deny/ls
paseo provider ls/models
hidden legacy paseo worktree create/ls/archive compatibility alias
paseo speech …

Communicates with the daemon via the same WebSocket protocol as the app.

`packages/relay` — Relay transport and E2E encryption

Enables remote access when the daemon is behind a firewall.

Updated peers negotiate a Noise NK session with per-record counters; peers on either side that predate it fall back to the legacy NaCl box construction. docs/relay-endpoint-security.md owns the mapping, negotiation, and the daemon.relay.requireProtectedSecurity flag
The relay is zero-knowledge — it routes encrypted bytes and cannot read content
Client and daemon channels with identical API (openClientSecureChannel, openDaemonSecureChannel)
Pairing via QR code transfers the daemon's public key to the client
New homes keep relay disabled until pairing consent. DaemonConfigStore persists the desired state, while the relay runtime starts or stops the outbound transport live; pairing reads that current state instead of a startup snapshot.
Optional E2EE capability negotiation preserves application frame kind: text plaintext uses base64 ciphertext text frames, while binary plaintext uses raw ciphertext binary frames; mixed-version peers remain base64-only
Self-hosted relays opt into TLS with daemon.relay.useTls or PASEO_RELAY_USE_TLS=true; the public (client-facing) TLS setting can be overridden independently via daemon.relay.publicUseTls or PASEO_RELAY_PUBLIC_USE_TLS

The production relay server lives in getpaseo/paseo-relay. It is a distributed Elixir service. The Cloudflare relay implementation in this monorepo is retained as legacy code and is not deployed.

See SECURITY.md for the full threat model.

Paseo Hub

The optional Hub relationship is daemon-outbound and does not use the relay. Its connection,
authorization, ownership, persistence, and lifecycle contract is documented in hub.md.

`packages/desktop` — Desktop app (Electron)

Electron wrapper for macOS, Linux, and Windows.

Can spawn the daemon as a managed subprocess
Native file access for workspace integration
Same WebSocket client as mobile app

The desktop does not manage agent skills. It retains one compatibility reader for the old
skill-selection.json, imports that preference into its managed local daemon, then deletes the old
file after the daemon confirms persistence.

Multi-window (hybrid land-on model). createWindow() in main.ts is reusable: ⌘⇧N/File→New Window, relaunching the app (second-instance), and the sidebar "Open in new window" action each open a fresh BrowserWindow. Every window shows the full sidebar — there is no per-window project ownership or filtering. "Land on a project" is delivered by a per-webContents PendingOpenProjectStore: each window pulls its own pending project path on mount (paseo:get-pending-open-project) and runs the normal open-project flow, identical to a CLI paseo launch.

Window-state v1 limitation: only the first window of a session restores and persists saved geometry (size/position/maximized). Windows opened via ⌘⇧N / second-instance / "Open in new window" open at the default size, OS-cascaded, and do not persist — this avoids every window stacking on the same restored bounds and fighting over the single window-state store. Lifting this needs per-window state keys.

In-app browser profile. Every browser guest uses one stable persistent Electron session, so cookies, authentication, cache, and site storage are shared across tabs, workspaces, and desktop windows and survive tab or app closure. Browser identity is independent of that storage partition: after every did-attach, the renderer explicitly registers its browser id, workspace id, and current guest WebContents id, and main accepts the registration only when that guest belongs to the calling renderer and the shared profile. Registration is intentionally repeated because reparenting a retained <webview> can replace its guest without replacing the DOM element. Settings > General > Clear browser data is the sole profile-deletion path; it clears the shared session and reloads live guests without deleting saved tabs or URLs.

In-app browser window opens. Ordinary link opens, including Shift-clicked links, become Paseo workspace tabs. Script-created opens with popup features or a named window target and POST-backed opens remain secured Electron child windows in the shared browser profile, preserving window.opener, postMessage, named-window reuse, request bodies, and window.close() for OAuth, payment, and similar popup protocols. Unsupported URL schemes are denied before either path.

In-app browser ownership. Each registered guest records its owning host window. The active browser is keyed by (host window, workspace), and application-menu Reload / Force Reload resolve only within the window Electron supplies to the menu callback. A non-null active update must name a browser owned by that host; a null update clears only that host/workspace. Browser automation continues to target explicit browser ids returned by browser_new_tab or browser_list_tabs.

Browser keyboard boundary. Guest pages receive renderer-published shortcuts first. Cmd/Ctrl+L and Cmd/Ctrl+R are explicit guest-shell reservations; ordinary Paseo shortcuts run only after the page declines them. The sandboxed guest preload runs in every frame so focused iframes use the same boundary, while Node integration remains disabled. Human guest input disables Electron's menu fallback for plain keys. Agent-generated keys use guest sendInputEvent with skipIfUnhandled, so an unhandled Enter stops at the guest instead of reaching the host composer. Main selects the preload; it exposes no APIs to guest pages.

text

Human key -> guest WebContents
  |-- Cmd/Ctrl+T/L/R ----------> reserved browser-shell action
  `-- page keydown
        |-- page prevents ------> page owns it
        `-- published shortcut -> guest preload -> IPC(browserId) -> Paseo resolver

Agent browser_keypress -> guest sendInputEvent(skipIfUnhandled)
  |-- guest handles ------------> page owns it
  `-- guest does not handle ----> stop; never redispatch to the host window

`packages/website` — Marketing site

TanStack Router + Cloudflare Workers. Serves paseo.sh.

WebSocket protocol

All clients speak the same WebSocket protocol over a single connection that mixes JSON text frames and a small binary framing for terminal streams. Schemas live in packages/protocol/src/messages.ts.

Handshake:

text

Client → Server:  WSHelloMessage {
                    type: "hello",
                    clientId,
                    clientType: "mobile" | "browser" | "cli" | "mcp",
                    protocolVersion,
                    appVersion?,
                    capabilities?: { voice?, pushNotifications?, ... },
                  }
Server → Client:  status message with payload { status: "server_info",
                    serverId, hostname, version, capabilities?, features }

There is no dedicated welcome message; the server emits one initial status.server_info after
accepting hello. Modern clients negotiate owned_subscriptions against
features.ownedSubscriptions. Connecting or attaching a local listener creates no application-data
demand. A list is a snapshot; adding subscribe: {} creates an independent server ID. The client
correlates the initial reply by request ID, then routes updates by subscription ID.

A logical Session can contain several physical sockets. Each socket owns its capabilities,
subscriptions and ongoing operations; the final JSON/binary send boundary requires that source's
request or subscription provenance. Domain modules own filtering, bootstrap and resource teardown.
The shared ownership boundary only tracks source and lifetime. Releasing a subscription acknowledges
its teardown; reconnect creates new server IDs for surviving client handles. See
protocol compatibility for the legacy boundary.

Top-level WS envelopes are hello, recording_state, ping/pong, and session (which wraps the rich union of session messages).

Client liveness checks use the top-level JSON ping/pong envelope, not a session RPC or RFC6455 control ping. Current clients ping every 10 seconds, beginning one interval after connecting. The first ping claims an application-ownership lease for that physical socket, all later inbound activity renews it, and the daemon forcibly terminates the socket if the lease expires. A legacy or raw socket that never sends an application ping never enters this lease and is not closed for omitting one. Session RPC timeouts are operation failures, not proof that the socket is dead. A subscription bootstrap timeout closes its source to clear any unknown server-owned registration; the failed handle is released before other surviving handles reconnect.

Every physical send path enforces an 8 MiB outbound high-water mark, including JSON broadcasts, binary terminal frames, and the encrypted relay adapter's asynchronous queue. This sits above the terminal stream's 4 MiB soft backpressure threshold, leaving room for snapshot catch-up before the hard cutoff. JSON is serialized once per broadcast after sockets already at the limit are removed, then its exact byte length is checked for every remaining socket. A frame that would cross the limit is not sent; that physical socket is forcibly terminated without disturbing other sockets attached to the same logical session. Multiple tabs and simultaneous direct and relay paths may legitimately share a client id.

Client session RPC waits default to 60s so slow relay or mobile networks do not turn a live but delayed daemon response into a false operation failure. Keep connect timeouts, app-level grace windows, explicit diagnostic latency probes, liveness ping timers, and genuinely long-running RPCs separate from this default.

New session RPCs use dotted names with .request and .response suffixes, such as checkout.forge.set_auto_merge.request and checkout.forge.set_auto_merge.response. See rpc-namespacing.md for the convention and migration rules for older flat RPC names.

Notable session message types:

agent_update — Agent state changed (status, title, labels)
agent_stream — New timeline event from a running agent
workspace_update, script_status_update, workspace_setup_progress — Workspace state
agent_permission_request / agent_permission_resolved — Tool-call permission flow
agent_deleted, agent_archived, agent_status, agent_list
checkout_status_update, checkout_diff_update, and the full checkout_* request/response set for git operations

Agent snapshots optionally carry the daemon-owned active turn identity, and turn lifecycle stream events
optionally carry the same turnId. New clients use these fields when present and normalize an old daemon's
status once at the directory boundary rather than maintaining a second activity model.

Terminal subscribe/input/capture commands
Voice/dictation streaming events (dictation_stream_*, assistant_chunk, audio_output, transcription_result)
Request/response pairs for fetch, list, create, etc., correlated by requestId; failures use rpc_error

directory_suggestions_request is one daemon-owned filesystem search capability. The daemon
configures the same searchDirectoryEntries engine with a root, output format, path-query policy,
entry-kind filters, match mode, blank-query behavior, and hidden-directory traversal policy. A
request without cwd searches the host home for absolute project paths; a request with cwd
searches that workspace and returns relative entries. Clients may prepend their small host-scoped
recent-project list for bare queries, but must not parse filesystem query syntax or re-filter a
correlated daemon response. The legacy directories response field remains a projection of the
typed entries list.

Binary frames (terminal stream protocol):

Terminal I/O is sent as binary WebSocket frames decoded by decodeTerminalStreamFrame in shared/binary-frames/terminal.ts. The layout is:

1-byte opcode: Output (0x01), Input (0x02), Resize (0x03), Snapshot (0x04)
1-byte slot: terminal slot id
variable payload: bytes for output/input, JSON-encoded { rows, cols } for resize, terminal snapshot for snapshot

Terminal PTY size is last-interacting-client-wins. A client claims the PTY size only when its terminal viewport genuinely changes size or the user focuses/taps the terminal. Passive rendering work — attaching, restoring visibility, font settling, renderer refits, or just looking at a visible terminal — must not send a resize frame. The server does not broadcast resize ownership; the resized PTY redraws through normal output, and every attached client renders that output in its own local viewport.

There is also a separate file-transfer binary frame format in the same directory, used for download/upload streams.
File downloads keep the existing FileBegin/FileChunk/FileEnd framing and stream 256 KiB chunks
from one stable file handle. Each transfer awaits completion of its own physical WebSocket send before
reading the next chunk; it is scoped to the requesting physical socket and does not queue unrelated
messages or transfers.

Compatibility rules

WebSocket schemas are append-only. Add fields, do not remove fields, and never make optional fields required.
New wire enum values must be gated at serialization with session.supports(CLIENT_CAPS.someCapability).
Capabilities belong to the physical source socket. session.supports(...) reads the requesting or observing source at the domain projection boundary; one socket must not borrow a sibling's capabilities.

Example: adding a new enum value

// 1. Add CLIENT_CAPS.newThing = "new_thing"
// 2. Let new clients advertise it in WS hello
// 3. Keep the shared producer schema strict
// 4. Gate the new emitted value: session.supports(CLIENT_CAPS.newThing) ? "new_value" : "old_value"

Creation ownership

Creation is owned by the daemon across socket lifetimes. A workspace request can include
its initial agent and prompt. Workspace readiness is published before provider startup;
the app keeps its existing disk-ready navigation and observes the remaining creation.
Callbacks do not advance the workflow. Resource reservations in acknowledgement are
identities, not ready workspace records.

The creation journal (server/creation/) owns identity and execution for both legacy and
modern creation RPCs. Requesting progress never selects a different journal. Existing
agent receipts are imported at this boundary; message delivery receipts remain separate.
It keeps cumulative milestones and permanent IDs under an operation kind and idempotency
key. Reconnect subscribes to that key; retries
join active work or reuse committed stages. A persisted resource alone cannot prove
that a provider accepted its initial prompt. Interrupted side effects with no conclusive
receipt return an unknown outcome instead of being repeated.

Agent registration commits creation. Rejecting the first prompt is a turn error on that
agent; reporting creation failure leaves an orphaned agent and invites another Create.
Receipt replay must not resend the prompt.

packages/client/src/creation/ owns capability selection and legacy orchestration.
Callers always pass the initial prompt to agent creation. On an older host, the client
adapts keyed creation to the legacy create/send sequence; it cannot continue that
sequence after the client process disappears. Explicitly requested IDs or receipts
that an old host cannot honor produce an unsupported error. Keep these adapters inside
the client package, as an exception to the default no-fallback feature policy.

Creation executes through the existing Session capabilities. Connection-owned delivery
controls observation only: detaching a socket or cleaning up its Session does not cancel
accepted creation. Updates require an explicit subscription and go only to that socket;
reconnect uses the shared subscription owner. Legacy consumers, including Hub, keep their
existing response contract.

Agent lifecycle

The lifecycle states are defined in shared/agent-lifecycle.ts:

text

initializing → idle ⇄ running
        ↓       ↓        ↓
              error
                ↓
              closed

initializing — provider session is being created
idle — has a live session, awaiting the next prompt
running — provider is currently producing a turn
error — last attempt failed; session is still attached
closed — terminal state, no live session

ManagedAgent is a discriminated union over those lifecycle tags. Notes:

AgentManager is the source of truth for agent state and broadcasts updates to all subscribers
Timeline sequence allocation is append-only with epochs (each run starts a new epoch). The one
permitted in-place enrichment adds a provider message id to the manager-owned row for an accepted
prompt; it preserves the row's sequence, content, and timestamp. Storage uses sequence numbers for
client-side dedup; the default fetch page is 200 items.
Timeline row timestamp values are canonical daemon-owned timestamps. Providers may supply original replay timestamps, but clients must not guess timestamp trust or hide time UI based on local clock heuristics.
Events stream to connected clients in real time; correctness is backed by authoritative timeline fetches and paged-to-completion catch-up.
Agent state persists to $PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json. Timeline rows are runtime memory; provider history is the durable transcript authority and resumed agents rebuild from it. That storage path is derived from cwd, not from workspace id.

Two workspaces can share the same cwd (e.g. a directory workspace and a local_checkout workspace on the same folder, or several workspaces opened against one checkout). Model B keeps these distinct: they share everything the directory determines, but nothing the workspace owns. The right-sidebar surfaces split cleanly along this line, and the split is enforced purely by what each piece of state is keyed by.

Directory-backed (shared by same-cwd workspaces) — keyed by (serverId, cwd), never by workspaceId:

Surface	Key	Source
Git status	`checkoutStatusQueryKey(serverId, cwd)`	`packages/app/src/git/query-keys.ts`
Git diff	`checkoutDiffQueryKey(serverId, cwd, mode, baseRef, ws)`	`packages/app/src/git/query-keys.ts`
Forge change request	`checkoutPrStatusQueryKey(serverId, cwd)`	`packages/app/src/git/query-keys.ts`
Change request timeline	`prPaneTimelineQueryKey({ serverId, cwd, prNumber })`	`packages/app/src/git/pull-request-panel/query-keys.ts`
File preview content	`["workspaceFile", serverId, cwd, path]`	`packages/app/src/components/file-pane.tsx`
File explorer listings	fetched via `listDirectory(workspaceRoot, path)`	`packages/app/src/hooks/use-file-explorer-actions.ts`

Workspace-owned (independent per workspace) — keyed by workspaceId (falling back to cwd only when no workspaceId exists):

State	Key builder / store	Source
Review draft comments	`buildReviewDraftKey`	`packages/app/src/review/store.ts`
Working diff comparison	`workingDiffComparisonKey` (in-memory)	`packages/app/src/git/working-diff-comparison/state.ts`
Composer attachments	`buildWorkspaceAttachmentScopeKey`	`packages/app/src/attachments/workspace-attachments-store.ts`
File explorer nav/open state	`fileExplorer` map keyed `workspace:{workspaceId}`	`packages/app/src/hooks/use-file-explorer-actions.ts`
File explorer expanded paths	`expandedPathsByWorkspace[workspaceStateKey]`	`packages/app/src/stores/panel-store/state.ts`

diff-pane.tsx is the canonical wiring site: it passes { serverId, cwd } to the git queries and { serverId, workspaceId, cwd } to the draft/comparison/attachment scope keys.

Do not "fix" the sharing away. Re-keying a directory-backed query by workspaceId makes same-cwd workspaces diverge (two windows onto the same git tree showing different diffs). Re-keying owned state (drafts, expanded paths) by cwd makes them leak between distinct workspaces on the same folder. The workspaceId-keyed builders carry a // workspaceId is opaque; do not parse this key back into a path. comment — the opaque-id fallback to cwd exists only for old payloads without a workspaceId, not as a content-sharing mechanism.

One deliberate non-violation: AgentFileExplorerState.directories/files cache directory listings inside the workspaceId-keyed explorer map. Same-cwd workspaces therefore keep duplicate caches, but they can never diverge — both fetch the identical directory via listDirectory(workspaceRoot, …). This is duplication, not leakage, and is left as-is.

Agent providers

Each provider implements the AgentClient interface in agent/agent-sdk-types.ts. Provider implementations live in agent/providers/.

The built-in, user-facing providers are Claude Code, Codex, Copilot, OpenCode, Pi, and OMP. Additional adapters exist in the same directory for ACP-compatible agents and internal use:

Provider	Wraps	Session format
Claude (`claude/`)	Anthropic Agent SDK	`~/.claude/projects/{cwd}/{session-id}.jsonl`
Codex	Codex AppServer (`codex-app-server`)	`~/.codex/sessions/{date}/rollout-{ts}-{id}.jsonl`
Copilot	GitHub Copilot via ACP	Provider-managed
OpenCode	OpenCode server / CLI	Provider-managed
Cursor	ACP wrapper (`acp-agent`)	Provider-managed
Generic ACP	ACP wrapper	Provider-managed
Pi	Local Pi RPC process	Provider-managed
Mock load test	In-process fake	In-memory

All providers:

Handle their own authentication (Paseo does not manage API keys)
Support session resume via persistence handles
Map tool calls to a normalized ToolCallDetail type
Expose provider-specific modes (plan, default, full-access)

Providers that can accept native tool definitions should set supportsNativePaseoTools and read launchContext.paseoTools. The daemon then passes the shared Paseo tool catalog directly and removes the internal Paseo MCP server from that provider launch config. Providers that only support MCP continue to receive the same tools through the MCP fallback at /mcp/agents.

Data flow: running an agent

Client sends CreateAgentRequestMessage with config (prompt, cwd, provider, model, mode)
Session routes to AgentManager.create()
AgentManager creates a ManagedAgent, initializes provider session
Provider runs the agent → emits AgentStreamEvent items
Events append to the agent timeline, broadcast to all subscribed clients
Tool calls are normalized to ToolCallDetail (shell, read, edit, write, search, etc.)
Permission requests flow: agent → server → client → user decision → server → agent

Storage

$PASEO_HOME defaults to ~/.paseo. The most important files:

text

$PASEO_HOME/
├── agents/{cwd-with-dashes}/{agent-id}.json   # Agent record
├── projects/projects.json                      # Project registry
├── projects/workspaces.json                    # Workspace registry
├── projects/icons/                             # Custom project icon images
├── schedules/                                  # Scheduled-agent definitions and runs
├── config.json                                 # Daemon config (mutable)
├── daemon-keypair.json                         # Daemon identity for relay/E2EE
├── push-tokens.json                            # Mobile push tokens
├── paseo.pid                                   # Supervisor identity and published bound endpoint
└── daemon.log                                  # Daemon trace logs (rotated)

The supervisor alone publishes its ready worker's endpoint in paseo.pid, clears it before respawn, and fails if any worker exits before first readiness. CLI home selection trusts only that live record; config expresses desired state, never an endpoint fallback. POSIX home stop signals the captured supervisor without TCP. Windows graceful stop and ordinary RPCs trust the published endpoint. This metadata is not cryptographic listener ownership: edited endpoints, copied identities, PID reuse, and address takeover races remain outside that guarantee. A stale heartbeat never permits reclaiming a live lock.

Worker restart retains supervisor arguments/environment and rereads the configuration file. Updating a package and observing its new worker version do not refresh the running supervisor code; the launcher owns full-process replacement. See CLI lifecycle contracts.

Deployment models

Local daemon (default): paseo daemon start on 127.0.0.1:6767
Managed desktop: Electron uses the server package’s local-instance lifecycle capability for sanitized launch, published readiness, and captured-PID stop. Only a matching {pid, startedAt} from a spawn in the current Desktop session authorizes automatic stop or binary replacement. Preexisting instances, including legacy desktopManaged records, are attach-only. Keep-running survivors attach in the next session. Explicit attached Stop requires a confirmation naming the captured home/PID. Ordinary Restart uses the worker RPC on every app platform.
Remote + relay: Daemon behind firewall, relay bridges with E2E encryption

Browser Capture Harness (`docs/browser-capture-harness.md`)

Browser Capture Harness

The desktop capture harness is the real-Electron verification path for browser screenshots.
It validates the compositor behavior that unit tests cannot see:

the resident automation <webview> starts in the production parking state;
the parked guest remains paintable and has a copyable viewport frame;
a never-presented resident webview guest defaults to 1280x800 logical pixels;
multiple resident webviews are parked as an overlapping stack without per-capture
stacking changes;
a newly attached resident webview whose first useful frame is delayed can be captured
by retrying until the frame appears;
both viewport capturePage and full-page CDP screenshots return real pixels from
the permanent production parking state;
parked guests remain capturable with Chromium background throttling enabled;
the real-Electron host-composer sentinel proves guest Enter cannot submit a focused
host composer;
the automation group loads the compiled production keyboard boundary and guest
preload, then proves that initial page window handlers get first refusal, unhandled
shortcuts synchronously suppress editable browser defaults before crossing the host
boundary, shortcuts marked unavailable in editable targets retain the browser field's
native behavior, handlers registered after preload still get first refusal, focused
iframes share the same boundary, digit wildcard shortcuts cross, and background automation
stays in the guest.

Run it with the repo Electron:

bash

npm run capture-harness --workspace=@getpaseo/desktop

Build the desktop main process before the automation group so its production guest
preload is available:

bash

npm run build:main --workspace=@getpaseo/desktop
PASEO_CAPTURE_HARNESS_GROUP=automation npm run capture-harness --workspace=@getpaseo/desktop

Run the shared browser profile fixture with:

bash

PASEO_CAPTURE_HARNESS_GROUP=browser-profile npm run capture-harness --workspace=@getpaseo/desktop

On macOS, test native titlebar dragging after scrolling with:

bash

PASEO_CAPTURE_HARNESS_GROUP=titlebar-drag npm run capture-harness --workspace=@getpaseo/desktop

This group needs Xcode Command Line Tools and Accessibility permission for the
terminal running it. It sends real mouse input to its test window and checks
window movement, including button clicks and a portal over the titlebar. Leave
the mouse idle during this group. It reads the app's production CSS and writes
screenshots and window bounds to the output directory.

The browser profile group runs two Electron processes in sequence. It verifies that each
renderer-side did-attach identity maps to the correct main-process guest, that two live
tabs share cookies and local storage through one persistent session, and that the data is
still present after the first Electron process exits and the second starts.

The automation group uses a real guest webview to verify the page-side ref contract:
ARIA-like snapshot text includes headings, static text, and controls; refs survive
pushState when the element still matches; same-URL rerenders stale old refs; and a
file-input ref can be resolved to a CDP backend node id for upload. It also verifies
page-context evaluation, including passing a resolved ref element as the function argument.
Keyboard containment runs last because the host-composer sentinel intentionally leaves
native focus in the host. It reuses an existing fixture button: adding a test-only control
changes the inline fixture geometry exercised by the earlier actionability checks.

On macOS the harness process must set app.setActivationPolicy("accessory") and
hide the Dock icon before creating any window. showInactive() only prevents window
focus; a normal Electron app launch can still activate the app and steal focus.
Harness windows are then created hidden, positioned in a screen corner, skipped from
the taskbar where Electron supports it, and revealed with showInactive() from
ready-to-show. Do not replace this with show(), focus(), or app.focus():
the compositor only needs visible inactive windows, and harness runs must not steal
focus from the person using the machine.

The harness writes PNG evidence and results.json to:

text

packages/desktop/capture-harness/out/

A passing run prints PASS lines for the production P1 default-throttling parking state,
including fresh, settled, 75-second soak, multi-tab, viewport, and full-page checks. The
PNG sizes may be device-pixel scaled; on a Retina display the 1280x800 logical viewport
is usually saved as 2560x1600.

The existing npm run test:e2e:browser-tabs --workspace=@getpaseo/desktop journey
verifies that a hidden window stops guest animation, captures fresh viewport pixels,
and resumes animation after restoring the window. Its artifacts include the screenshot
and animation measurements. Full-page content correctness remains separately tracked in
the full-page repetition bug.

Mechanism

Electron captures copy from the guest web contents' compositor surface. A resident
webview parked with display:none, offscreen coordinates, or opacity:0 can lose its
copyable surface. Each production webview keeps one permanent body-level surface. Presenting
or parking changes that surface's geometry without reparenting the webview. The parking state
uses left:0, top:0, width:1px, height:1px, overflow:hidden, opacity:1, and
pointer-events:none. The webview stays at its resolved logical viewport, defaulting to
1280x800 before first presentation, with display:inline-flex at left:0, top:0.
Presentation resolves responsive guests to the pane's exact pixel dimensions after the surface
has visible bounds. Do not apply percentage guest sizing against the parked surface: Electron
exposes the 1x1 parking geometry as a real guest resize before expanding it again.

The permanent browser host and overlay-root are explicit sibling paint planes. The browser
plane stays below the overlay plane regardless of body insertion order; menus keep their relative
layering inside overlay-root. Activating a presented browser also focuses its registered guest
WebContents in main so macOS assigns keyboard first-responder ownership to the page.

There is no renderer prep/restore handshake or lifetime background-throttling override.
Screenshot capture temporarily enables frame production inside the shared serialized queue,
restores the previous throttling policy on success or failure, and retains a 5-second capture budget.
The browser tool takes one viewport frame through Electron's frame subscription and releases the
subscription on completion or cancellation. A resized resident guest can produce fresh pixels
while capturePage() leaves its surface-copy request pending; waiting for animation frames or
retrying the copy does not repair that state. Full-page screenshots retain the CDP path with layout
metrics and screenshot clip.

Coding Standards (`docs/coding-standards.md`)

Coding Standards

The core instinct: AI-generated code hedges — it covers every case, layers over instead of cutting in, scatters uncertainty everywhere, wraps in case. A senior engineer commits — to a shape, a boundary, a name, a happy path, a type — and lets everything else fall into place. Every rule below catches a different form of indecision.

For testing rules, see testing.md.

Core principles

Zero complexity budget — every abstraction must justify itself with a specific, current benefit.
YAGNI — build features and abstractions only when needed. A function called once is indirection, not abstraction.
No "while I'm at it" cleanups — make the change you came for. Drive-by edits hide in the diff.
Functional and declarative over object-oriented.
function declarations over arrow function assignments.
interface over type when both work.
No index.ts barrel files that only re-export — they create indirection and circular-dep risk. Import from the source.

Shell scripts

Bash scripts always use #!/usr/bin/env bash. Never hard-code /bin/bash or /usr/bin/bash; those paths are not portable to environments such as NixOS.

Comments and noise

Delete any comment where removing it loses zero information. Comments explain why, not what.
No tutorial comments explaining language features (// Use destructuring to...).
No decorative section dividers (// ===== Helpers =====). Use files and modules to organize, not ASCII art.
No hedging comments (// might need to revisit, // should work for most cases). If you're unsure, investigate.
No commented-out code. Git remembers.
No console.log / debugger left behind. No TODO: implement stubs — if it needs to exist, write it.

Confidence: commit to a shape

Validate at boundaries (network, IPC, user input, file I/O), trust types internally. After the parse, the value is what its type says.
Every ?. and ?? past the validation boundary is unconfident code — either the boundary should resolve it, or the type should reflect reality.
No defensive checks for conditions the type system already rules out (if (!agent) return on a non-nullable parameter).
No try/catch "just in case." If you can't say what you're catching and why, don't catch.
Optionality is a design decision, not a migration shortcut. Distinct valid states → discriminated union. Intentionally empty → explicit null. Keep optionality at real boundaries.

Types

No any. No as casts to bypass errors. No @ts-ignore / @ts-expect-error. Narrow with if / schema validation; let the compiler check harder, not less.
If a Zod schema exists, the TypeScript type is z.infer<typeof schema>. Never hand-write a parallel type.
One canonical type per concept. Layer-specific views are Pick / Omit, not duplicated fields.
Name multi-property object shapes — no inline Array<{ ... }> or Promise<{ ... }> in signatures, returns, or generic args.
Use string literal unions, not raw string, when the value is one of a known set. Catches typos at compile time.
Object parameters past the obvious-name threshold: 3+ args, any boolean arg, any optional arg → object. (thing, true, false, true) is unreadable at the call site.
Make impossible states impossible — discriminated unions over { isLoading; error?; data? } bags.

Errors

Throw typed error classes that carry the fields a caller would want to read. Plain Error("Provider X not found") collapses structured info into a string.
Catch blocks branch on instanceof for what they can handle; rethrow the rest. No catch (e) { return null }.
Separate user-facing copy from log/debug strings — don't make one string serve telemetry, logs, and the UI.
Fail explicitly. If the caller asked for X and X isn't available, throw — don't silently substitute Y.
Every fallible user action owns explicit pending, success, and failure UI. Console logs and unverified platform alerts do not satisfy this contract. See testing.md.
A capability advertised to a client means the current runtime can perform the action, not merely that its RPC handler exists. If an unavailable action needs explanatory UI, send the runtime fact or reason separately and keep the server-side refusal fail-closed.

Density

Nested ternaries are forbidden. A single ternary is fine only when both branches are a single identifier or trivial access (x ? a : b).
Boolean expressions with 2+ clauses or mixed concerns → name the conditions.
Object literals assemble pre-computed values; don't pack branching and lookups into property positions.
Operations wrapping operations (Object.fromEntries(arr.filter(...).map(...)), Math.max(...xs.map(...))) → break into named intermediates.
Max 3 levels of nesting (callbacks, JSX, control flow). Above that, extract.

Structure and modules

A directory is a module, not a namespace. One intentional public surface; internal files stay internal.
Path is part of the name — prefer provider/registry.ts over provider/provider-registry.ts. If the filename has to do double duty, deepen the path.
Filenames ending in -utils, -helpers, -manager, -handler, -controller, -formatter, -builder are a smell — the path didn't carry enough domain.
Boundary returns answer the caller's question (getActiveAgents()), not "here's my storage" (getAgents().filter(...) repeated everywhere).
One adapter means a hypothetical seam; two adapters means a real one. Don't define a port until something actually varies across it.
Pass-through modules fail the deletion test — if removing the module makes callers go straight to what they wanted, delete it.
Centralize policy. The same discriminator (plan, provider, kind, status) branched in 3+ files → policy table, not another else if per case.
New features get a home before implementation. A feature smeared across 5 shared files is the same slop as a flat-peer namespace.
Don't drop new files at the nearest root just because placement is unclear — say so and ask.

Refactoring is a bolt-on test

A change should look like a thoughtful edit to existing code, not a new layer next to it. New coordinator wrapping a coordinator, new flag bypassing the normal path, new helper duplicating an existing selector — stop and reshape instead.
Refactors preserve behavior by default. No removing features to simplify code without explicit approval.
Have a verification plan before refactoring — name the invariants, confirm a test holds them, write one if not. See testing.md.
Migrate all callers and remove old paths in the same refactor. No fallback behavior unless explicitly designed.

React

useEffect is for synchronizing with external systems (DOM, network, timers, subscriptions). Not for transforming React state. Derived state → compute in render or useMemo.
No effect cascades — chains of effects setting state that triggers more effects almost always want React Query or a reducer.
useRef is for DOM refs and non-rendering identities (timer IDs, AbortController, latest-callback caches). If the value affects what renders next, it's state — model it explicitly with useReducer and a discriminated union.
Server state goes through React Query. Manual useState + useEffect + isLoading + error for fetched data is always worse.
Components render and dispatch — they don't compute transitions. Two-plus interacting useStates → extract a reducer.
Never define components inside other components. Module-scope only.
Subscribe narrowly: select primitives from stores, pass status not agent, use useShallow / deep-equal when returning derived arrays/objects.
Collection rows do not independently subscribe to a high-frequency global store. The collection owner selects structurally shared indexes once, derives a keyed row model with useMemo, and passes entries to rows. This keeps retained hidden collections current without running one selector per row on every store update.
Equality functions prevent React renders; they do not prevent selector callbacks from running. A selector attached to a hot store must be O(1) when its relevant source references have not changed.
Retained native panels use RetainedPanel. If an existing gesture/layout wrapper must own visibility, wrap its contents in RetainedPanelActivity instead. Keep keyed panel roots in a stable sibling order, include the newly active panel in the same render, centralize subscriptions, and gate genuine effects through useRetainedPanelActive. Follow the native ownership constraints and chat suspension boundary when stopping hidden rendering.
Infinite animations are subscriptions. Start them only while their retained panel is active, and cancel a shared clock when its final active consumer leaves. Synchronized animations use one clock per animation family and feed active instances through local shared values; retained hidden instances stay mounted but unsubscribed. Match state updates to the actual visual cadence; do not run every style worklet at 60 fps when the rendered value changes only a few times per second.
Stable references for props that cross memo boundaries or feed dependency arrays. Static literals at module scope as const; derived with useMemo; handlers with useCallback only when there's a memoized beneficiary.
Use stable ids for key, never array index for reorderable/filterable lists.
Context for stable values (theme, auth). Store with selectors for state that changes.

Retained panel measurements

Inactive retained panels use display: none, so DOM and layout APIs report zero width and height. A non-positive measurement means the surface is not rendered; it is never a valid compact layout.

Suspend geometry-derived updates while either measured dimension is non-positive. Preserve the last valid state until the surface reports positive geometry again.
Enforce the rule at the measurement boundary shared by every trigger. Guarding only an onLayout or ResizeObserver callback still lets effects, content changes, and imperative remeasurement publish hidden geometry.
Test the hide-and-reveal path through a real retained surface. Settled assertions do not catch stale geometry painted during the first returned frames.

Naming

Names describe meaning, not mechanics. submitForm over handleOnClickButtonSubmit. running over filteredArrayOfRunningAgents.
The right length is the shortest unambiguous in context. Inside AgentManager, methods are start, stop, list.
Match the surrounding code's vocabulary. If the codebase uses getX, don't introduce fetchX / retrieveX for the same shape.
Don't leak implementation into names — getAgent, not queryPostgresForAgent. If swapping the impl would force a rename, the name is wrong.
Booleans read as yes/no questions: isX, hasX, canX. Avoid negative booleans (isNotConnected).
data, result, info, manager, temp are smells — say what the thing is.

Connected Hosts (`docs/connected-hosts.md`)

Connected hosts

A saved host belongs to the daemon that stores it. The app's saved connections remain a separate list.
Connect A to B through paseo --host A host or paseo.hosts. Consumers select B by its learned serverId; management uses the stable
registrationId created before B is reachable.

Ownership and authority

Credentials live in A's hosts.json, written atomically with mode 0600 on POSIX systems. Discovery returns a safe
target description. Replacement inputs never come back through a read API. Keep this file private
when collecting diagnostics or backing up daemon state.

The authenticated producer owns its source key. Repeating an unchanged add returns the saved entry,
including a user's disabled state. Changed input requires an explicit update. Display labels and
access can be changed by users with tunnel.manage; connection and metadata changes require the
producer or access.manage. Removing a producer-managed entry allows that producer to add it again.
Disabling retains the opt-out.

Each enabled registration owns one physical daemon link, shared by status monitoring and every
routed API scope. Each scope owns an isolated virtual session on B. A derives its identity from the
admitted origin session, producer, and logical SDK scope. B admits virtual sessions under the actual
physical link principal, then intersects forwarded caller grants with that link's current authority.
Changing or resuming a parent's grants closes its existing channels; reconnect re-admits demand with
current authority. A routed API cannot select a second hop, and saving a host grants no reverse access.

A producer that registers a host through a routed API is qualified on B as
route::<A serverId>:<A producer>, with each component percent-encoded. This namespace belongs to the authenticated link
principal. An ordinary direct B consumer does not become that producer by supplying a source key.
The optional server_info.sourceId reports this producer identity separately from the authenticated admission principal.
Trusted server plugins retain the authority of their runtime; they are not sandboxed by this feature.

Delegating agents

Agent MCP discovers destination IDs with list_hosts. create_workspace, list_workspaces,
create_agent, send_agent_prompt, get_agent_status, get_agent_activity, and list_agents
accept serverId; omission selects the calling daemon. Remote creation requires a
destination workspace and explicit provider/model. Caller filesystem defaults apply only on the
calling daemon. Prompting a remote child acknowledges acceptance and uses the existing idle wait for
finish notifications. Remote agent lists have no caller-directory default; pass cwd to filter them.

The parent’s Subagents track shows qualified children across connected hosts. Opening a child uses
the ordinary conversation on the destination's session. The runtime selects among that host's
connection candidates, including direct connections and routes discovered through another daemon.
Adding a direct connection to a discovered host adds another candidate. If no candidate connects,
the destination workspace keeps its existing disconnected or reconnecting behavior.

Finish notifications use the existing idle wait, including a pending initial run or an already idle
child. They name the server and agent. A daemon restart or route loss ends an outstanding notification
wait; inspect or wait for the child again rather than resending its prompt. Concurrent prompts gain
no additional turn attribution or delivery guarantee.

Connections and recovery

The shared Node connector owns the target grammar and each connection attempt, including a fresh
SSH process. SSH reaches an already running daemon. The shared client connection lifecycle owns
physical reconnect and keepalive; the registry retains configuration, identity acceptance, and recovery
status. Unreachable registrations remain saved. Identity is pinned when discovered. Self and duplicate
registrations remain inspectable; a changed destination requires explicit identity replacement.

Both daemons advertise connectedHosts; the shared link additionally requires hostMultiplexing.
A completes capability and pinned-identity checks on each physical recovery before admitting channels. There is no local fallback. An older daemon continues to serve existing local
operations; requesting this feature gives update guidance.

Disposing a routed API releases its observations and session. It does not remove the saved host or
affect sibling API scopes. Disposing the origin cascades to its derived scopes. Observations restore
through the usual owned-subscription contract. The ordinary client queues new requests while connecting
within its existing deadline and rejects requests while disconnected. Connection loss clears old
waiters and queued sends. Submitted requests with no response fail with DaemonConnectionError
(DAEMON_CONNECTION_LOST), optional outcome: "unknown" and known serverId. Inspect the destination
before retrying a mutation.
Ordinary non-recoverable mutations are not automatically replayed. Existing acknowledged/idempotent
creation recovery retains its request identity and resumes through the ordinary creation lifecycle. Multiplexing changes only the transport: ordinary permission
RPC codes pass through unchanged, and connection/recovery behavior matches direct clients.

Text session envelopes carry a channel identifier. Binary routing adds an opcode, a bounded UTF-8
channel identifier, and the original terminal or file-transfer bytes. It never converts those bytes to
base64 JSON. The existing direct binary opcodes and 100 MiB message limit remain unchanged; routed
payloads reserve space for the routing header inside that limit. Relay encryption retains its own
existing frame limit.

Host links cap saved registrations, simultaneous channels, handshake lifetime, frames, physical
output, and aggregate queued bytes. Capacity checks use the actual escaped outer JSON or binary
frame size. Awaitable output completes when the physical send completes. An overflowing channel
closes without closing siblings or the saved link. Routed sessions release resources on disconnect;
subscription demand is rebuilt by its owning client on reconnect.

See the SDK reference,
CLI reference, and
plugin reference.

Custom Providers (`docs/custom-providers.md`)

Custom Provider Configuration

Paseo supports configuring custom agent providers through config.json (located at $PASEO_HOME/config.json, typically ~/.paseo/config.json). You can extend built-in providers with different API backends, add ACP-compatible agents, set custom binaries, disable providers, and create multiple profiles for the same underlying provider.

Provider definitions live under agents.providers in config.json:

json

{
  "version": 1,
  "agents": {
    "providers": {
      "provider-id": { ... }
    }
  }
}

Provider IDs must be lowercase alphanumeric with hyphens (/^[a-z][a-z0-9-]*$/).

Each provider catalog refresh waits up to 2 minutes. If a provider loads many plugins or a large
agent catalog during startup, raise the limit in milliseconds:

json

{
  "agents": {
    "catalogRefreshTimeoutMs": 180000
  }
}

The limit applies independently to every provider refresh and covers availability plus the entire
catalog probe. PASEO_PROVIDER_REFRESH_TIMEOUT_MS sets it when the config field is absent.

Provider options

Set provider defaults in agents.providers..options. At agent creation, use
providerOptions on the wire or config.options in the SDK. Both are opaque
Record<string, unknown> values: the provider owns validation and application.
Claude, Codex, and OpenCode reject unknown keys with a key-specific creation error.
Providers without option handling ignore the record.

The daemon deep-merges the agent's options over the provider defaults at each
session launch or resume. Plain objects merge recursively; arrays, scalars, and
null replace the base value. Only the agent's own options are persisted, so edits
to provider defaults apply on the next launch or resume. A profile inherits its
base provider's options unless it sets its own options record.

json

{
  "agents": {
    "providers": {
      "codex": {
        "options": { "sandbox_mode": "read-only", "approval_policy": "never" }
      }
    }
  }
}

See the SDK provider options guide for
per-agent examples and provider-specific keys.

Extending a built-in provider
Z.AI (Zhipu) coding plan
Alibaba Cloud (Qwen) coding plan
Codex with a custom OpenAI-compatible endpoint
Multiple profiles for the same provider
Custom binary for a provider
Disabling a provider
ACP providers
Provider override reference

Extending a built-in provider

Use extends to create a new provider entry that inherits from a built-in provider (claude, codex, copilot, opencode, pi, omp). The new provider gets its own entry in the provider list, with its own label, environment, and model definitions.

json

{
  "agents": {
    "providers": {
      "my-claude": {
        "extends": "claude",
        "label": "My Claude",
        "description": "Claude with custom API endpoint",
        "env": {
          "ANTHROPIC_API_KEY": "sk-ant-...",
          "ANTHROPIC_BASE_URL": "https://my-proxy.example.com/v1"
        }
      }
    }
  }
}

Required fields for custom providers:

extends — which built-in provider to inherit from (or "acp")
label — display name in the UI

See Codex with a custom OpenAI-compatible endpoint below for the dedicated Codex example.

Z.AI (Zhipu) coding plan

Z.AI is a Chinese AI company (Zhipu AI) that offers an Anthropic-compatible API endpoint. Their GLM Coding Plan provides flat-rate access to GLM models through Claude Code's Anthropic API protocol. These are not Anthropic Claude models — they are Zhipu's own GLM models exposed through an Anthropic-compatible API.

Setup

Register at z.ai and subscribe to a coding plan
Create an API key from the Z.AI dashboard
Add a provider entry in config.json:

json

{
  "agents": {
    "providers": {
      "zai": {
        "extends": "claude",
        "label": "ZAI",
        "env": {
          "ANTHROPIC_AUTH_TOKEN": "<your-zai-api-key>",
          "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
          "API_TIMEOUT_MS": "3000000"
        },
        "disallowedTools": ["WebSearch"],
        "models": [
          { "id": "glm-4.5-air", "label": "GLM 4.5 Air" },
          { "id": "glm-5-turbo", "label": "GLM 5 Turbo", "isDefault": true },
          { "id": "glm-5.1", "label": "GLM 5.1" }
        ]
      }
    }
  }
}

Available models

Model	Tier
`glm-5.1`	Advanced (flagship)
`glm-5-turbo`	Advanced
`glm-4.7`	Standard
`glm-4.5-air`	Lightweight

Notes

ANTHROPIC_AUTH_TOKEN is used instead of ANTHROPIC_API_KEY — this is the z.ai API key
The API_TIMEOUT_MS env var extends the request timeout (z.ai can be slower than direct Anthropic)
If you get auth errors, run /logout inside Claude Code before switching to the z.ai provider
Web search (WebSearch tool) is an Anthropic-only server-side feature — third-party endpoints don't support it. Add "disallowedTools": ["WebSearch"] to avoid errors.
Automated setup is also available: npx @z_ai/coding-helper
Official docs: docs.z.ai/devpack/tool/claude

Alibaba Cloud (Qwen) coding plan

Alibaba Cloud Model Studio offers a coding plan that routes Claude Code requests to Qwen models through an Anthropic-compatible API. Like z.ai, these are not Anthropic Claude models.

Setup

Go to the Coding Plan page on Alibaba Cloud Model Studio (Singapore region)
Subscribe to the Pro plan ($50/month)
Obtain your plan-specific API key (format: sk-sp-xxxxx) — this is different from a standard Model Studio key
Add a provider entry in config.json:

json

{
  "agents": {
    "providers": {
      "qwen": {
        "extends": "claude",
        "label": "Qwen (Alibaba)",
        "env": {
          "ANTHROPIC_AUTH_TOKEN": "sk-sp-<your-coding-plan-key>",
          "ANTHROPIC_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
        },
        "disallowedTools": ["WebSearch"],
        "models": [
          { "id": "qwen3.5-plus", "label": "Qwen 3.5 Plus", "isDefault": true },
          { "id": "qwen3-coder-next", "label": "Qwen 3 Coder Next" },
          { "id": "kimi-k2.5", "label": "Kimi K2.5" }
        ]
      }
    }
  }
}

API endpoints

Mode	Base URL
Coding plan (subscription)	`https://coding-intl.dashscope.aliyuncs.com/apps/anthropic`
Pay-as-you-go (no subscription)	`https://dashscope-intl.aliyuncs.com/apps/anthropic`

For pay-as-you-go, use ANTHROPIC_API_KEY with a standard Model Studio key (sk-xxxxx) instead of ANTHROPIC_AUTH_TOKEN.

Available models

Recommended for coding plan:

Model	Notes
`qwen3.5-plus`	Vision capable, recommended
`qwen3-coder-next`	Optimized for coding
`kimi-k2.5`	Vision capable
`glm-5`	Zhipu GLM
`MiniMax-M3`	MiniMax

Additional models (pay-as-you-go):
qwen3-max, qwen3.5-flash, qwen3-coder-plus, qwen3-coder-flash, qwen3-vl-plus, qwen3-vl-flash

Notes

API keys must be created in the Singapore region
The coding plan is for personal use only in interactive coding tools
Web search (WebSearch tool) is an Anthropic-only server-side feature — third-party endpoints don't support it. Add "disallowedTools": ["WebSearch"] to avoid errors.
Official docs: alibabacloud.com/help/en/model-studio/claude-code-coding-plan

Codex with a custom OpenAI-compatible endpoint

Codex talks to OpenAI's Responses API by default. Custom providers that extend "codex" can point Codex at any OpenAI-compatible endpoint (OpenRouter, LiteLLM, vLLM, llama.cpp server, an internal gateway, etc.) by setting OPENAI_BASE_URL and OPENAI_API_KEY in the provider env.

Paseo passes those variables through to the Codex app-server process and maps them into Codex's thread config under model_provider / model_providers, because Codex reads provider routing from config rather than from OPENAI_BASE_URL alone.

Setup

json

{
  "agents": {
    "providers": {
      "my-codex": {
        "extends": "codex",
        "label": "My Codex",
        "description": "Codex via custom OpenAI-compatible endpoint",
        "env": {
          "OPENAI_API_KEY": "sk-...",
          "OPENAI_BASE_URL": "https://custom-relay.example.com"
        },
        "models": [{ "id": "custom-model", "label": "Custom Model", "isDefault": true }]
      }
    }
  }
}

What Paseo wires up

Under the hood, for each custom Codex provider Paseo injects this into Codex's config:

toml

model_provider = "my-codex"

[model_providers.my-codex]
name = "My Codex"
base_url = "https://custom-relay.example.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"
requires_openai_auth = false

base_url — taken from OPENAI_BASE_URL. If it does not already end in /v1, Paseo appends /v1. Trailing slashes are stripped.
wire_api — always "responses" (OpenAI Responses API protocol).
env_key — set to "OPENAI_API_KEY" when that env var is present and non-empty, so Codex reads the key from the same env var Paseo passes through.
requires_openai_auth — forced to false when OPENAI_API_KEY is provided, so Codex skips its built-in OpenAI login flow.

Notes

The endpoint must speak the OpenAI Responses API, not just chat completions. Many gateways (OpenRouter, LiteLLM) support both — pick the Responses-compatible route.
Set models explicitly. Custom endpoints expose their own model IDs (anthropic/claude-opus-4-7, qwen/qwen3-coder, local/llama, etc.), and Paseo does not discover them automatically for Codex.
To run multiple endpoints side-by-side, define multiple entries that each extend "codex" with different IDs, labels, and env. Each appears as its own provider in the app.
If you only want to override the binary (e.g. a nightly Codex build) without changing the endpoint, omit OPENAI_BASE_URL and use command instead — see Custom binary for a provider.

Multiple profiles for the same provider

You can create multiple entries that extend the same built-in provider. Each gets its own entry in the provider list with independent credentials, models, and environment.

"Profile" here means a provider alias, and it is not an Agent profile — that is a named bundle of provider, model, mode, thinking option and features, stored under daemon.agentProfiles. See glossary.md for all four senses of the word.

Example: two different Anthropic accounts as separate profiles:

json

{
  "agents": {
    "providers": {
      "claude-work": {
        "extends": "claude",
        "label": "Claude (Work)",
        "description": "Work Anthropic account",
        "env": {
          "ANTHROPIC_API_KEY": "sk-ant-work-..."
        }
      },
      "claude-personal": {
        "extends": "claude",
        "label": "Claude (Personal)",
        "description": "Personal Anthropic account",
        "env": {
          "ANTHROPIC_API_KEY": "sk-ant-personal-..."
        }
      }
    }
  }
}

Each profile appears as a separate provider in the Paseo app. You can select which one to use when launching an agent.

You can also combine profiles with model overrides to pin specific models per profile:

json

{
  "agents": {
    "providers": {
      "claude-fast": {
        "extends": "claude",
        "label": "Claude (Fast)",
        "models": [{ "id": "claude-sonnet-4-6", "label": "Sonnet 4.6", "isDefault": true }]
      },
      "claude-smart": {
        "extends": "claude",
        "label": "Claude (Smart)",
        "models": [{ "id": "claude-opus-4-6", "label": "Opus 4.6", "isDefault": true }]
      }
    }
  }
}

Custom binary for a provider

Override the command used to launch any provider with the command field. This is an array where the first element is the binary and the rest are arguments.

Override a built-in provider's binary

json

{
  "agents": {
    "providers": {
      "claude": {
        "command": ["/opt/claude-nightly/claude"]
      }
    }
  }
}

Use a custom wrapper script

json

{
  "agents": {
    "providers": {
      "claude": {
        "command": ["/usr/local/bin/my-claude-wrapper", "--verbose"]
      }
    }
  }
}

Custom binary on a derived provider

json

{
  "agents": {
    "providers": {
      "my-codex": {
        "extends": "codex",
        "label": "Codex (Custom Build)",
        "command": ["/home/user/codex-dev/target/release/codex"]
      }
    }
  }
}

The command array completely replaces the default command for that provider. The binary must exist on the system — Paseo checks for its availability and will mark the provider as unavailable if not found.

OMP profiles and Pi-compatible forks

OMP ships as a first-class built-in provider option. It is disabled by default; enable it with:

json

{
  "agents": {
    "providers": {
      "omp": { "enabled": true }
    }
  }
}

Custom OMP profiles should extend omp. They inherit the OMP adapter's rpc-ui approvals, native Paseo host tools, provider-managed subagents, and import behavior:

json

{
  "agents": {
    "providers": {
      "omp-work": {
        "extends": "omp",
        "label": "Oh My Pi (Work)",
        "command": ["omp"],
        "env": {
          "XDG_CONFIG_HOME": "~/.config/omp-work",
          "XDG_STATE_HOME": "~/.local/state/omp-work"
        },
        "options": {
          "sessionDir": "~/.local/state/omp-work/omp/agent/sessions",
          "rpcTimeoutMs": 60000,
          "smolModel": "openai/gpt-5-mini",
          "slowModel": "anthropic/claude-opus-4-1",
          "planModel": "openai/o3"
        }
      }
    }
  }
}

options.sessionDir is used only for importing sessions that were started outside Paseo. If command or XDG env vars move OMP's state directory, set options.sessionDir to the resulting OMP JSONL session directory; launching and resuming still go through the configured command. OMP waits 20 seconds for its initial ready frame and 60 seconds for later control-plane RPCs by default. options.rpcTimeoutMs overrides both deadlines.

For other providers that keep Pi's --mode rpc API but write sessions somewhere else, extend pi, replace the command, and provide the JSONL session directory:

json

{
  "agents": {
    "providers": {
      "my-pi-fork": {
        "extends": "pi",
        "label": "My Pi Fork",
        "command": ["my-pi-fork"],
        "options": {
          "sessionDir": "~/.my-pi-fork/sessions",
          "rpcTimeoutMs": 60000
        }
      }
    }
  }
}

This session directory is also import-only. Launching and resuming still go through the configured command, so this example resumes with my-pi-fork --mode rpc --session <session-file>. options.rpcTimeoutMs overrides the 60-second Pi control-plane RPC deadline.

Disabling a provider

Set enabled: false to hide a provider from the provider list. The provider will not appear in the app or CLI.

json

{
  "agents": {
    "providers": {
      "copilot": { "enabled": false },
      "codex": { "enabled": false }
    }
  }
}

This works for both built-in and custom providers. To re-enable, set enabled: true or remove the enabled field entirely. Most providers are enabled by default; OMP is intentionally disabled by default and requires enabled: true.

ACP providers

The Agent Client Protocol (ACP) is an open standard for communication between editors and AI coding agents — think LSP but for AI agents. Any agent that supports ACP can be added to Paseo as a custom provider.

ACP agents communicate over JSON-RPC 2.0 on stdio. Paseo spawns the agent process and talks to it through stdin/stdout.

Paseo also ships an in-app ACP provider catalog for common agents, including CodeWhale, Cursor, DeepAgents, DimCode, Gemini CLI, Hermes, Qwen Code, and Kimi Code. Most catalog entries create the same extends: "acp" provider config shown below. Hoplite activates its bundled provider instead.

Adding a generic ACP provider

Set extends: "acp" and provide a command:

json

{
  "agents": {
    "providers": {
      "my-agent": {
        "extends": "acp",
        "label": "My Agent",
        "command": ["my-agent-binary", "--acp"],
        "env": {
          "MY_API_KEY": "..."
        }
      }
    }
  }
}

Required fields for ACP providers:

extends: "acp"
label
command — the command to spawn the agent process (must support ACP over stdio)

Paseo tools such as subagent creation come from the shared internal tool catalog. ACP providers receive those tools through the MCP fallback by default because ACP exposes mcpServers, not Paseo's native tool catalog. Some ACP adapters cannot create sessions when mcpServers is non-empty. Disable injected MCP for those providers with options.supportsMcpServers: false:

json

{
  "agents": {
    "providers": {
      "my-agent": {
        "extends": "acp",
        "label": "My Agent",
        "command": ["my-agent", "acp"],
        "options": {
          "supportsMcpServers": false
        }
      }
    }
  }
}

ACP agents execute filesystem operations in their own environment by default,
while terminal operations run through Paseo on the host. To customize which
operations Paseo handles, configure client capabilities in provider options:

json

{
  "agents": {
    "providers": {
      "container-agent": {
        "extends": "acp",
        "label": "Container Agent",
        "command": ["container-agent", "acp"],
        "options": {
          "clientCapabilities": {
            "fs": {
              "readTextFile": false,
              "writeTextFile": false
            },
            "terminal": false
          }
        }
      }
    }
  }
}

When an agent runs in a container or remote environment that manages its own
terminal, set terminal: false to keep command execution inside the agent
container. When delegating filesystem operations to Paseo (fs.readTextFile: true
or fs.writeTextFile: true), ensure the agent and Paseo share equivalent
absolute workspace paths.

Generic ACP diagnostics

Paseo diagnostics for extends: "acp" providers report the configured command, resolved launcher binary, version output, ACP initialize, ACP session/new, model count, modes, and final status.

For package-runner commands such as npx -y @google/gemini-cli --acp, the version probe keeps the package spec and runs npx -y @google/gemini-cli --version. This diagnoses the actual agent package instead of only proving that npx exists.

ACP probes use short timeouts and browser-suppression environment variables so agents that enter an auth/browser flow fail as a diagnostic error instead of hanging the provider screen.

Example: Google Gemini CLI

Gemini CLI supports ACP via the --acp flag.

Install: npm install @google/gemini-cli or see Gemini CLI docs
Authenticate with Google (Gemini CLI handles its own auth)
Add to config.json:

json

{
  "agents": {
    "providers": {
      "gemini": {
        "extends": "acp",
        "label": "Google Gemini",
        "command": ["gemini", "--acp"]
      }
    }
  }
}

Ref: Gemini CLI ACP mode docs

Example: Hermes (Nous Research)

Hermes is an open-source coding agent by Nous Research with persistent memory and multi-provider LLM support. It supports ACP via the acp subcommand.

Install: curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Install ACP support: pip install -e '.[acp]'
Configure Hermes credentials in ~/.hermes/
Add to config.json:

json

{
  "agents": {
    "providers": {
      "hermes": {
        "extends": "acp",
        "label": "Hermes",
        "description": "Nous Research self-improving AI agent",
        "command": ["hermes", "acp"]
      }
    }
  }
}

Ref: Hermes ACP docs

How ACP providers work in Paseo

When you launch an agent with an ACP provider:

Paseo spawns the process using the configured command
Sends an initialize JSON-RPC request over stdin
The agent responds with its capabilities, available modes, and models
Paseo creates a session and sends prompts through the ACP protocol
The agent streams responses, tool calls, and permission requests back over stdout

Every ACP provider exposes an Auto Accept toggle. Enable it per session to let Paseo approve
ACP permission requests without surfacing each prompt. If the provider sends no allow option,
Paseo leaves the request for you to answer. Unattended agents enable Auto Accept unless you
explicitly disable it.

Models and modes are discovered dynamically at runtime from the agent process. If you want to override the model list (e.g., to curate which models appear in the UI), use the models field:

json

{
  "agents": {
    "providers": {
      "my-agent": {
        "extends": "acp",
        "label": "My Agent",
        "command": ["my-agent", "--acp"],
        "models": [
          { "id": "fast-model", "label": "Fast", "isDefault": true },
          { "id": "smart-model", "label": "Smart" }
        ]
      }
    }
  }
}

Profile models (defined in config.json) completely replace runtime-discovered models when present.

If you want to keep runtime-discovered models and add or relabel a few entries, use additionalModels instead.

Example: add an experimental model while keeping every model the provider discovers at runtime:

json

{
  "agents": {
    "providers": {
      "my-agent": {
        "extends": "acp",
        "label": "My Agent",
        "command": ["my-agent", "--acp"],
        "additionalModels": [
          { "id": "experimental-model", "label": "Experimental", "isDefault": true }
        ]
      }
    }
  }
}

Example: relabel a discovered model without replacing the full list:

json

{
  "agents": {
    "providers": {
      "my-agent": {
        "extends": "acp",
        "label": "My Agent",
        "command": ["my-agent", "--acp"],
        "additionalModels": [{ "id": "provider/model-id", "label": "My Preferred Label" }]
      }
    }
  }
}

When an additionalModels entry has the same id as a discovered model, it updates that model in place.

Provider override reference

Every entry under agents.providers accepts these fields:

Field	Type	Required	Description
`extends`	`string`	Yes (custom only)	Built-in provider ID to inherit from, or `"acp"`
`label`	`string`	Yes (custom only)	Display name in the UI
`description`	`string`	No	Short description shown in the UI
`command`	`string[]`	Yes (ACP only)	Command to spawn the agent process
`env`	`Record<string, string>`	No	Environment variables to set for the agent process
`options`	`Record<string, unknown>`	No	Provider-specific options such as `supportsMcpServers: false`
`models`	`ProviderProfileModel[]`	No	Static model list (overrides runtime discovery)
`additionalModels`	`ProviderProfileModel[]`	No	Static model additions (merged with runtime discovery or `models`)
`disallowedTools`	`string[]`	No	Tool names to disable for this provider (e.g. `["WebSearch"]`)
`enabled`	`boolean`	No	Set to `false` to hide the provider (default: `true`)
`order`	`number`	No	Sort order in the provider list

Model definition

Each entry in the models array:

Field	Type	Required	Description
`id`	`string`	Yes	Model identifier sent to the provider
`label`	`string`	Yes	Display name in the UI
`description`	`string`	No	Short description
`isDefault`	`boolean`	No	Mark as the default model selection
`thinkingOptions`	`ThinkingOption[]`	No	Available thinking/reasoning levels

Thinking option

Field	Type	Required	Description
`id`	`string`	Yes	Thinking option identifier
`label`	`string`	Yes	Display name
`description`	`string`	No	Short description
`isDefault`	`boolean`	No	Mark as the default thinking option

Claude settings.json model discovery

The built-in claude provider appends concrete model IDs from ~/.claude/settings.json to its first-party Claude model list. Paseo reads the top-level model field and these env keys: ANTHROPIC_MODEL, ANTHROPIC_SMALL_FAST_MODEL, ANTHROPIC_DEFAULT_FABLE_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL.

This lets users who already configured Claude Code for Bedrock, OpenRouter, ollama, Z.AI, or another Anthropic-compatible gateway select the exact model ID in Paseo. Explicit model IDs are passed unchanged to Claude Code, even when the same string is a compatibility alias for a built-in model. When agents.providers.claude.models is set it replaces both the hardcoded first-party Claude list and any settings.json-discovered entries; use agents.providers.claude.additionalModels to keep the first-party list and append curated entries on top.

Gotcha: `extends: "claude"` with third-party endpoints

When a custom provider extends "claude" but points ANTHROPIC_BASE_URL at a non-Anthropic API (Z.AI, Alibaba/Qwen, proxies), the Claude Agent SDK may try to use Anthropic-only server-side tools like WebSearch. Third-party APIs don't support these tools, causing errors.

Use disallowedTools to disable unsupported tools:

json

{
  "agents": {
    "providers": {
      "my-proxy": {
        "extends": "claude",
        "label": "My Proxy",
        "env": {
          "ANTHROPIC_BASE_URL": "https://my-proxy.example.com/v1"
        },
        "disallowedTools": ["WebSearch"]
      }
    }
  }
}

Valid `extends` values

Built-in providers: claude, codex, copilot, opencode, pi, omp

Special value: acp — creates a generic ACP provider (requires command)

Full example

A config.json with multiple custom providers:

json

{
  "version": 1,
  "agents": {
    "providers": {
      "copilot": { "enabled": false },

      "zai": {
        "extends": "claude",
        "label": "ZAI",
        "env": {
          "ANTHROPIC_AUTH_TOKEN": "<zai-api-key>",
          "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
          "API_TIMEOUT_MS": "3000000"
        },
        "disallowedTools": ["WebSearch"],
        "models": [
          { "id": "glm-4.5-air", "label": "GLM 4.5 Air" },
          { "id": "glm-5-turbo", "label": "GLM 5 Turbo", "isDefault": true },
          { "id": "glm-5.1", "label": "GLM 5.1" }
        ]
      },

      "qwen": {
        "extends": "claude",
        "label": "Qwen (Alibaba)",
        "env": {
          "ANTHROPIC_AUTH_TOKEN": "sk-sp-<coding-plan-key>",
          "ANTHROPIC_BASE_URL": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
        },
        "disallowedTools": ["WebSearch"],
        "models": [
          { "id": "qwen3.5-plus", "label": "Qwen 3.5 Plus", "isDefault": true },
          { "id": "qwen3-coder-next", "label": "Qwen 3 Coder Next" }
        ]
      },

      "gemini": {
        "extends": "acp",
        "label": "Google Gemini",
        "command": ["gemini", "--acp"]
      },

      "hermes": {
        "extends": "acp",
        "label": "Hermes",
        "command": ["hermes", "acp"]
      }
    }
  }
}

Data Model (`docs/data-model.md`)

Data Model

Project identity

Projects are allocated for the exact root selected by the caller, normalized lexically with path.resolve (never realpath). New project IDs are opaque prj_<16 hex> values. Existing remote-shaped or path-shaped IDs are retained as readable compatibility records and are never rekeyed. An active exact root is idempotent; archived-only matches do not resurrect an old project. Workspace projectId is stable membership: reconciliation may update git-derived kind and branch metadata, but never rehomes a workspace or changes a project's root, ID, or default name.

projectKey is a persisted, opaque equivalence key used only to group the same logical project
across hosts. It is separate from the host-local projectId; today's producer prefers a normalized
Git remote and otherwise uses the local project root. Consumers never derive it from live Git.
Creation persists it with the project, and normal boot reconciliation fills it for
older records where the field is absent—there is no migration.

kind and projectKey are mutable metadata, not identity. Workspace reconciliation watches active project roots and
updates those fields and updatedAt when Git facts change, preserving the project's ID, root path,
names, and workspace foreign keys. Attached workspaces are independently refreshed
from their own cwd, so an explicit project root never implies a workspace checkout. Empty projects
are observed too.

The workspace registry model defines placement once: initial directory/worktree construction,
mutable reconciliation fields, and the persisted-to-wire checkout projection. Its update policy
preserves displayName and baseBranch. WorkspaceProvisioningService owns the corresponding
registry writes, so directory opens, agent imports, and worktree creation all enter through that
service instead of constructing records independently. The workspace record is then the durable
placement authority: cwd is the exact execution directory, while worktreeRoot is the backing
checkout root. They intentionally differ for an exact subproject inside a worktree. Archive,
restore, branch auto-name, and descriptor flows consume those persisted facts rather than
rediscovering ownership from a directory that may already be gone. Reconciliation may refresh
mutable placement facts, but never changes projectId, cwd, displayName, or baseBranch.
Workspace archive runs lifecycle teardown from the exact cwd but removes only the backing
worktreeRoot after its last active reference disappears. Worktree recovery recreates that backing
checkout from mainRepoRoot, then restores the relative path from worktreeRoot to cwd.

Paseo uses file-based JSON persistence instead of a traditional database. All data is validated at runtime with Zod schemas. Most stores write atomically (write to temp file, then rename); a few still use plain writeFile — see each section. There is no schema-versioning/migration framework — schemas rely on optional fields with defaults for forward compatibility, with a small amount of inline normalization in persisted-config.ts for legacy provider/speech entries.

All server-side stores live under $PASEO_HOME (defaults to ~/.paseo).

Store Surface Rules

Store APIs own persistence atomicity and should not make services coordinate raw reads and writes. A good store method maps cleanly to one SQL statement or one SQL transaction, even when the current implementation is JSON files. If a caller needs a queue, lock, read-merge-write loop, or uniqueness race workaround, that behavior belongs behind the store surface.

Directory layout

text

$PASEO_HOME/
├── config.json                          # Daemon configuration
├── server-id                            # Stable daemon identifier (plain text, "srv_<base64url>")
├── daemon-keypair.json                  # E2EE keypair for relay (mode 0600)
├── paseo.pid                            # Daemon PID lock file
├── local-credential                     # Per-run local client credential (mode 0600)
├── daemon.log                           # Default log file (path configurable)
├── agents/
│   └── {sanitized-cwd}/
│       └── {agentId}.json               # One file per agent
├── schedules/
│   └── {scheduleId}.json                # One file per schedule
├── projects/
│   ├── projects.json                    # Project registry
│   ├── workspaces.json                  # Workspace registry
│   ├── workspace-labels.json            # Shared host-local label catalog
│   ├── workspace-labels.transaction.json # Recoverable catalog/assignment compound commit
│   └── icons/                           # Host-local custom project icon images
├── runtime/
│   └── managed-processes/
│       └── {recordId}.json              # Helper processes owned by Paseo; reconciled on daemon bootstrap
├── plugins/
│   ├── sources.json                      # Managed kind and Git acquisition remote
│   └── {pluginId}/{uuid}/                # Git checkout or npm package/lockfile/dependency tree
└── push-tokens.json                     # Expo push notification tokens

The agents/{sanitized-cwd}/ directory name is derived from the agent's cwd by stripping the filesystem root and replacing path separators with - (Windows drive letters become a C- style prefix). Persistent server stores write atomically by writing a temp file in the target directory and then renaming it into place.

1. Agent Record

Path: $PASEO_HOME/agents/{project-dir}/{agentId}.json

Each agent is stored as a separate JSON file, grouped by project directory.

Field	Type	Description
`id`	`string`	UUID, primary key
`provider`	`string`	Agent provider (`"claude"`, `"codex"`, `"opencode"`, etc.)
`cwd`	`string`	Working directory the agent operates in
`workspaceId`	`string?`	Owning workspace id — the single source of ownership. Every agent is stamped with one at create time; legacy cwd-only records are backfilled once by `migrations/backfill-workspace-id.migration.ts` (the only place a cwd→id mapping exists). Runtime code never infers ownership or status from cwd: status is computed per `workspaceId`, and same-cwd siblings are independent.
`createdAt`	`string` (ISO 8601)	Creation timestamp
`updatedAt`	`string` (ISO 8601)	Last update timestamp
`lastActivityAt`	`string?` (ISO 8601)	Last activity timestamp
`lastUserMessageAt`	`string?` (ISO 8601)	Last user message timestamp
`title`	`string?`	User-visible title
`labels`	`Record<string, string>`	Key-value labels (default `{}`). Paseo uses `paseo.parent-agent-id` for parentage and client-scoped `paseo.open-agent-tab.*` labels while managed subagent tabs are open — see agent-lifecycle.md
`lastStatus`	`AgentStatus`	One of: `"initializing"`, `"idle"`, `"running"`, `"error"`, `"closed"`. `closed` means the record is resumable but has no live provider runtime; archive remains represented separately by `archivedAt`.
`lastModeId`	`string?`	Last active mode ID
`config`	`SerializableConfig?`	Agent session configuration (see below)
`runtimeInfo`	`RuntimeInfo?`	Live runtime state (see below)
`features`	`AgentFeature[]?`	Provider-reported features (toggles/selects)
`persistence`	`PersistenceHandle?`	Handle for resuming sessions
`lastError`	`string?` (nullable)	Last error message, if any
`requiresAttention`	`boolean?`	Whether the agent needs user attention
`attentionReason`	`"finished" \| "error" \| "permission"?`	Why attention is needed
`attentionTimestamp`	`string?` (ISO 8601)	When attention was flagged
`internal`	`boolean?`	Whether this is a system-internal agent
`archivedAt`	`string?` (ISO 8601)	Soft-delete timestamp

Nested: SerializableConfig

Field	Type	Description
`title`	`string?`	Configured title
`modeId`	`string?`	Configured mode
`model`	`string?`	Configured model
`thinkingOptionId`	`string?`	Thinking/reasoning level
`featureValues`	`Record<string, unknown>?`	Feature preference overrides
`extra`	`Record<string, any>?`	Provider-specific config
`systemPrompt`	`string?`	Custom system prompt
`mcpServers`	`Record<string, any>?`	MCP server configurations

Nested: RuntimeInfo

Field	Type	Description
`provider`	`string`	Active provider
`sessionId`	`string?`	Active session ID
`model`	`string?`	Active model
`thinkingOptionId`	`string?`	Active thinking option
`modeId`	`string?`	Active mode
`extra`	`Record<string, unknown>?`	Provider-specific runtime data

Nested: PersistenceHandle

Field	Type	Description
`provider`	`string`	Provider that owns the session
`sessionId`	`string`	Session ID for resumption
`nativeHandle`	`any?`	Provider-specific handle (Codex thread ID, Claude resume token, etc.)
`metadata`	`Record<string, any>?`	Extra metadata

Nested: AgentFeature (discriminated union on `type`)

Toggle:

Field	Type
`type`	`"toggle"`
`id`	`string`
`label`	`string`
`description`	`string?`
`tooltip`	`string?`
`icon`	`string?`
`value`	`boolean`

Select:

Field	Type
`type`	`"select"`
`id`	`string`
`label`	`string`
`description`	`string?`
`tooltip`	`string?`
`icon`	`string?`
`value`	`string \| null`
`options`	`AgentSelectOption[]`

Runtime-only Terminal Sessions

Terminals are live daemon state, not persisted JSON records. A terminal carries a workspaceId while it is running; workspace-scoped terminal lists include only terminals with the matching workspaceId. Legacy live terminals without an owner remain visible to unscoped terminal reads but contribute to no workspace status.

Terminal activity contributes to the workspace status bucket per workspaceId: a working terminal drives running onto the workspace it carries only. Same-cwd siblings are untouched; terminal visibility is likewise workspaceId-scoped.

2. Daemon Configuration

Path: $PASEO_HOME/config.json

Single file, validated with PersistedConfigSchema.

agents.skills.selection is the daemon host's orchestration-skill preference. Missing means
{ mode: "all" }. Installed state is not persisted; the daemon derives it from the shared
~/.agents/skills and Claude skill directories and keeps config plus filesystem convergence behind
one serialized owner. Codex discovers the shared directory. Updates retire unchanged files from
Paseo-managed copies in ~/.codex/skills, preserving user edits and untracked files.

paseo reload reads and validates this file once inside the daemon. That snapshot drives resolution,
classification, application, and reload bookkeeping. DaemonConfigStore owns applying runtime-safe
fields and their removal/default semantics; session handlers and the CLI only relay the structured
result. Normal config patches persist only the requested fields, so launch overrides and resolved
defaults never leak into the file. Startup-only fields remain compared with the daemon's launch
snapshot so a mixed edit can apply its live subset and still name the paths that require restart.

text

/* Detailed source-code truncated for AI context efficiency. */

All fields are optional with sensible defaults.

Managed plugins appear as directory sources in config.json; it owns the active path and enabled
state. plugins/sources.json is written atomically and stores only managed kind and the Git acquisition
remote. Installed revision, package/subdirectory identity and ownership root come from retained
artifacts and the fixed managed layout; managed source ownership
explains their authority. An update prepares a new directory before replacing the active path and
removing the previous version. Old record fields are accepted at the store boundary and ignored;
there is no startup migration or persistent update policy.

Profile lists

terminalProfiles and agentProfiles are both whole-list fields: a config patch replaces the
array, never merges entries, so a client sends the complete next list on every add, edit, reorder
and remove. List order is the display order.

Absent and empty mean different things for terminal profiles — omitting the key falls back to
DEFAULT_TERMINAL_PROFILES, while [] means the user removed them all. Agent profiles have no
defaults, so both mean none.

PersistedConfigSchema parses strictly, so a daemon that predates a field drops it on write
rather than storing something it cannot describe. That is why the client gates the agent profiles
UI on server_info.features.agentProfiles instead of letting a save appear to succeed against an
older daemon.

Agent provider Paseo tools

agents.providers is keyed by the exact provider ID used to launch the agent. The built-in IDs are
claude, codex, copilot, opencode, pi, and omp. Custom provider IDs are their literal
configuration keys, such as my-claude or zai, not the provider named by extends.

Each entry may include a Paseo-tool policy:

json

{
  "agents": {
    "providers": {
      "my-claude": {
        "extends": "claude",
        "label": "My Claude",
        "paseoTools": {
          "enabled": true,
          "disabledTools": ["browser_evaluate"]
        }
      }
    }
  }
}

Absent paseoTools, or absent fields within it, means Paseo tools are enabled and all tools are
allowed. enabled: false disables the provider's Paseo catalog; disabledTools lists exact tool
IDs to omit. The policy covers the core and browser catalog, not the voice-only speak tool.
Browser tools also require daemon.browserTools.enabled and a connected browser host.
This policy controls the catalog presented to an agent. It is not an authorization boundary for
agents that can access the host through a shell.

daemon.mcp.injectIntoAgents is the global override. When it is false, no provider receives
Paseo tools; otherwise the provider policy applies. Provider and global policy are resolved when a
session is created, resumed, imported, or reloaded, so configuration changes affect the next
session rather than an already-running one.

agents.metadataGeneration.providers selects the models for daemon-side metadata tasks: commit messages, PR text, branch names, and generated titles. An empty list is Automatic; a non-empty list is Manual and only those models are tried. See public-docs/metadata-generation.md.

Git process limits

Git process limits are global to one daemon. The start-rate limit defaults to 64 processes per
second, and the concurrency limit defaults to 8:

json

{
  "daemon": {
    "git": {
      "maxProcessesPerSecond": 64,
      "maxProcessConcurrency": 8
    }
  }
}

maxProcessesPerSecond limits Git process starts in any one-second interval. The allowance can
start as a burst; it does not wait for earlier processes to exit. maxProcessConcurrency limits
the number of Git processes that have started but not exited. Every Git command uses both limits,
including initial workspace reads, filesystem-triggered refreshes, background checks, and explicit
requests.

Environment variables override config.json:

Environment variable	Setting
`PASEO_GIT_MAX_PROCESSES_PER_SECOND`	`maxProcessesPerSecond`
`PASEO_GIT_MAX_PROCESS_CONCURRENCY`	`maxProcessConcurrency`
`PASEO_GIT_CONCURRENCY`	Legacy concurrency alias

PASEO_GIT_MAX_PROCESS_CONCURRENCY wins when it and the legacy alias are both set. Run paseo reload
after changing config.json. Environment changes require a daemon restart; the launch environment
remains authoritative during reload.

Local speech model ids are intentionally narrow: STT uses parakeet-tdt-0.6b-v2-int8, TTS uses kokoro-en-v0_19, and turn detection uses the bundled Silero VAD model.

Set these to select OpenAI instead of local speech:

Env var	Applies to
`PASEO_VOICE_STT_PROVIDER`	Voice mode STT provider
`PASEO_DICTATION_STT_PROVIDER`	Composer dictation STT provider
`PASEO_VOICE_TTS_PROVIDER`	Voice mode TTS provider

OpenAI speech can be configured under providers.openai. STT and TTS resolve independently, so they can point at different endpoints:

json

{
  "providers": {
    "openai": {
      "stt": {
        "apiKey": "sk-...",
        "baseUrl": "https://stt.example.com/v1"
      },
      "tts": {
        "apiKey": "sk-...",
        "baseUrl": "https://api.openai.com/v1"
      }
    }
  }
}

providers.openai.stt is used for both composer dictation and voice mode speech-to-text; providers.openai.tts is used for voice mode text-to-speech. The equivalent env vars are OPENAI_STT_API_KEY/OPENAI_STT_BASE_URL and OPENAI_TTS_API_KEY/OPENAI_TTS_BASE_URL. Each feature falls back to providers.openai.apiKey/providers.openai.baseUrl, then OPENAI_API_KEY/OPENAI_BASE_URL, when its own fields are unset. These settings apply only to Paseo OpenAI speech features, not to Codex or other OpenAI-backed tools.

Paseo uses these paths under the configured OpenAI base URL:

dictation STT: /v1/audio/transcriptions
voice mode STT: /v1/audio/transcriptions
voice mode TTS: /v1/audio/speech

3. Schedule

Path: $PASEO_HOME/schedules/{id}.json

One file per schedule. ID is 8 hex characters.

Field	Type	Description
`id`	`string`	8-char hex ID
`name`	`string?`	Human-readable name
`prompt`	`string`	The prompt to send
`cadence`	`ScheduleCadence`	Timing (see below)
`target`	`ScheduleTarget`	What to run (see below)
`status`	`"active" \| "paused" \| "completed"`	Current state
`createdAt`	`string` (ISO 8601)
`updatedAt`	`string` (ISO 8601)
`nextRunAt`	`string?` (ISO 8601)	Next scheduled execution
`lastRunAt`	`string?` (ISO 8601)	Last execution time
`pausedAt`	`string?` (ISO 8601)	When paused
`expiresAt`	`string?` (ISO 8601)	Auto-expire time
`maxRuns`	`number?`	Max executions before completing
`runs`	`ScheduleRun[]`	Execution history

Nested: ScheduleCadence (discriminated union on `type`)

{ type: "cron", expression: string, timezone?: string } — canonical cadence for new writes; absent timezone means UTC
{ type: "every", everyMs: number } — legacy rolling interval, still readable and executable during the compatibility window

Nested: ScheduleTarget (discriminated union on `type`)

{ type: "agent", agentId: string } — send to existing agent
{ type: "new-agent", config: { provider, cwd, modeId?, model?, thinkingOptionId?, title?, providerOptions?, featureValues?, systemPrompt?, mcpServers? } } — create a new agent

Nested: ScheduleRun

Field	Type	Description
`id`	`string`	Run ID
`scheduledFor`	`string` (ISO 8601)	Intended execution time
`startedAt`	`string` (ISO 8601)
`endedAt`	`string?` (ISO 8601)
`status`	`"running" \| "succeeded" \| "failed"`
`agentId`	`string?` (UUID)	Agent used for this run
`output`	`string?`	Agent output text
`error`	`string?`	Error message if failed

4. Project Registry

Path: $PASEO_HOME/projects/projects.json

Array of project records.

Field	Type	Description
`projectId`	`string`	Host-local primary key; new records use opaque `prj_<16 hex>` IDs
`projectKey`	`string \| null`	Persisted opaque cross-host grouping key; reconciliation backfills absent values
`rootPath`	`string`	Exact lexically normalized selected root; never realpathed
`kind`	`"git" \| "non_git"`	Mutable Git observation about `rootPath`, never a membership key
`displayName`	`string`	Selected-root basename, stable across remote and Git changes
`customName`	`string \| null`	User-set override layered over `displayName`. Null means "use the derived name".
`customIconRevision`	`string \| null`	Identifies the host-local custom icon stored under `projects/icons/`. Null means the icon is discovered by scanning the project directory.
`createdAt`	`string` (ISO 8601)
`updatedAt`	`string` (ISO 8601)
`archivedAt`	`string \| null` (ISO 8601)	Soft-delete timestamp; required nullable

Uploading a file and pasting a website or image URL are two ways of acquiring the same custom
icon. The client fetches URL imports and sends their bytes through the upload RPC. The daemon never
receives or fetches the URL; it validates the uploaded bytes, stores them, and records a new
customIconRevision. Going back to automatic deletes the stored image, as does removing the
project.

Active exact roots are idempotent using lexical platform-equivalence semantics. Existing legacy
remote-shaped and path-shaped IDs remain readable, including duplicate roots; reconciliation never
merges them, transfers names, archives them, or moves workspace foreign keys. An explicit
workspace projectId is authoritative when it names an active project, regardless of cwd
containment. Archived-only exact-root records are not resurrected by explicit add/open; a fresh
opaque project is allocated instead. Agent restore is separate and restores the agent's existing
workspace together with its owning project.

5. Workspace Registry

Path: $PASEO_HOME/projects/workspaces.json

Array of workspace records. A workspace is a specific working directory within a project.

Field	Type	Description
`workspaceId`	`string`	Opaque stable identifier (`wks_<hex>`), generated independently of the directory. MUST NOT be treated as a path; compare by exact equality. Use the `cwd` field for directory access.
`projectId`	`string`	FK to Project.projectId; the workspace's stable project membership
`cwd`	`string`	Exact execution directory selected for agents, files, scripts, and setup
`kind`	`"local_checkout" \| "worktree" \| "directory"`	Mutable checkout classification
`displayName`	`string`	The human name (the generated/derived title). Decoupled from `branch` by construction.
`title`	`string \| null`	User-set name override layered over `displayName`. Null means "use `displayName`".
`branch`	`string \| null`	The current Git branch for git-backed workspaces. Separate from `displayName`/`title`; a background branch refresh never rewrites the name.
`worktreeRoot`	`string \| null`	Backing checkout/worktree root. May differ from `cwd` for exact subprojects and remains persisted after the worktree is deleted so restore can reproduce the placement.
`baseBranch`	`string \| null`	Comparison base retained across archive and restore. Branch-off creation stores the resolved ref; legacy and PR-checkout records hold a bare name. Null means no recorded base.
`isPaseoOwnedWorktree`	`boolean`	Whether Paseo owns and may remove/recreate the backing `worktreeRoot`
`mainRepoRoot`	`string \| null`	Main repository root for worktree checkouts, independent of both exact `cwd` and backing `worktreeRoot`
`createdAt`	`string` (ISO 8601)
`updatedAt`	`string` (ISO 8601)
`archivedAt`	`string \| null` (ISO 8601)	Soft-delete; required nullable
`autoArchivedChangeRequestUrl`	`string \| null`	Change request whose merged state triggered auto-archive. Restore replaces it with the current merged change request, when present, so repeated snapshots cannot archive the workspace again.
`labels`	`string[]?`	Normalized display names assigned from this host's shared label catalog. Missing means unlabelled.
`pinnedAt`	`string \| null` (ISO 8601)	Pinned-to-top-of-sidebar timestamp; null means "not pinned"
`untrustedSource`	`{ kind: "change_request", forge, number, headRepository }?`	Provenance captured when a cross-repository change request creates the workspace. Missing means repository automation is allowed; explicit setup removes the field.

Opaque-ID invariant: workspaceId is opaque identity, never a filesystem path. Filesystem and git operations take cwd/workspaceDirectory only — never the id. A compatibility-only first-materialization bootstrap still groups pre-registry agent records by path and Git remote so existing installs retain their legacy records. That grouping never runs against a live registry, and its keys are not runtime project or workspace identity.

Workspace label catalog

Path: $PASEO_HOME/projects/workspace-labels.json

The catalog is shared by every workspace on one host. A definition contains a display name and one
of the ten identity colour names (WORKSPACE_LABEL_COLORS in
packages/protocol/src/workspace-labels.ts); trimmed, collapsed, case-insensitive name identity is
unique within that file. Definitions have no portable ID or principal owner and remain after their
last assignment. Editing a label takes a new name, a new colour, or both in one commit, so the two
fields cannot land half-applied. Workspaces store label names, so a rename and a delete rewrite
workspace assignments through one serialized compound commit while a recolour is catalog-only; a
rename onto a name the host already has is refused rather than merged. A prepared
workspace-labels.transaction.json contains both before and after images. The daemon writes the
catalog and workspace files, then atomically changes the transaction to committed; that phase
change is the durable commit point. Recovery rolls prepared transactions back before either
directory is served. A committed marker proves both data files were already written, so recovery
only loads the current catalog and retries marker cleanup; it never reapplies stale workspace
after-images over later registry mutations. A request rejected before the commit point therefore
cannot take effect after restart. If the live daemon cannot determine or restore the durable state,
the workspace registry freezes every write and later label mutations fail with
workspace_label_storage_uncertain until daemon restart performs recovery. Reads remain available,
but may reflect the last acknowledged cache until restart. Workspace directory and catalog updates
publish only after the commit point; publication failure does not roll durable state back.

projectId is still a real FK: workspace records should have a matching project record. Read-only
history surfaces tolerate transient orphaned workspaces by omitting those rows so one bad FK cannot
blank the whole History screen, but mutation paths should repair or remove the orphaned state rather
than treating it as valid.

6. Push Token Store

Path: $PASEO_HOME/push-tokens.json

json

{
  "tokens": ["ExponentPushToken[...]", ...]
}

Simple set of Expo push notification tokens. Loaded with permissive parsing (filters non-string entries). Persisted with atomic temp-file rename.

7. Daemon meta files

These small files are not validated as full Zod schemas but are persisted under $PASEO_HOME for daemon identity and runtime coordination.

Path	Format	Notes
`server-id`	Plain text, e.g. `srv_`	Stable per-`$PASEO_HOME` daemon ID. Overridable via `PASEO_SERVER_ID` env.
`daemon-keypair.json`	`{ v: 2, publicKeyB64, secretKeyB64 }` (libsodium box keypair)	E2EE relay identity. Written with mode `0600`. Regenerated if file is unreadable.
`paseo.pid`	JSON `{ pid, startedAt, ... }`	PID lock; prevents two daemons sharing one `$PASEO_HOME`.
`local-credential`	32 random bytes encoded as base64url text	Rotated before each listen and deleted on shutdown; mode `0600`.
`daemon.log`	Pino log output	Default location; path/rotation configurable via `log.file` in `config.json`.

Client-side stores (App)

These live in React Native AsyncStorage or browser IndexedDB, not on the daemon filesystem.

Keying convention: directory-backed vs workspace-owned

Right-sidebar client state splits on whether it is determined by the directory or owned by the workspace (two workspaces can share one cwd). The split is enforced by the cache key, so changing a key changes the sharing semantics — see architecture.md for the full table.

Directory-backed (shared by same-cwd workspaces): keyed by (serverId, cwd). Git status/diff, GitHub PR status, PR timeline, file preview content. These are TanStack Query caches, not persisted stores.
Workspace-owned (independent per workspace): keyed by workspaceId, with cwd used only as a fallback when no workspaceId is present. Review draft comments (@paseo:review-draft-store), diff-mode overrides (in-memory), workspace composer attachments, and file-explorer nav/expand state. The workspaceId part of these keys is opaque — never parse it back into a path.

Replica row store

The durable client replica uses IndexedDB on browser/Electron and expo-sqlite on native. Rows use the
compound key (serverId, kind, id); kinds are agent, workspace, project, timeline, and
checkpoint. Directory entities have individual rows, timelines use the agent id, and the checkpoint
uses the singleton id.

The store is a typed persistence boundary. It returns values to directory and timeline owners and
accepts their explicit commits; it never reads or writes UI state. Reads are scoped to the requested
host, kinds, and ids. Opening a cached workspace uses exact workspace and project keys rather than a
directory scan. One invalid row is deleted and returned as a miss without affecting other rows.
An invalid directory row and its affected checkpoint cursor are repaired in one transaction, so a
later launch cannot accept a checkpoint for a partial baseline. Directory changes and their
checkpoint are also applied in one transaction. Reads wait for accepted changes to reach storage,
then retry only when a requested row changes during the read. Unrelated agent streams do not
invalidate the read. Directory baseline replacements and host removal or renaming still invalidate
the affected reads.

The cache is capped at 32 MiB and evicts whole hosts in least-recently-written order. Budget
bookkeeping may scan opaque row sizes during a deferred write, never during host registry startup or
before a requested cache row can paint. The row store is not encrypted. A cached timeline can contain
source code, prompts, and tool output; encrypted-at-rest storage is a separate security decision.

Draft Store

AsyncStorage key: paseo-drafts (version 2)

typescript

{
  drafts: Record<draftKey, {
    input: { text: string, images: AttachmentMetadata[] },
    lifecycle: "active" | "abandoned" | "sent",
    updatedAt: number,     // epoch ms
    version: number        // optimistic concurrency
  }>,
  createModalDraft: DraftRecord | null
}

Attachment Store (Web)

IndexedDB database: paseo-attachment-bytes, object store: attachments

Stores binary attachment blobs keyed by attachment ID.

AttachmentMetadata

Field	Type	Description
`id`	`string`	Unique attachment ID
`mimeType`	`string`	MIME type
`storageType`	`string`	Storage backend identifier
`storageKey`	`string`	Key within the storage backend
`createdAt`	`number`	Epoch ms
`fileName`	`string?`	Original filename
`byteSize`	`number?`	Size in bytes

Design (`docs/design.md`)

Design

Tokens — every color, font size, weight, spacing step, radius, icon size — live in packages/app/src/styles/theme.ts.

1. Character

Paseo is minimal, spacious, quiet, confident. Whitespace is deliberate. Nothing crowds, nothing decorates, nothing apologizes. A row, a label, a control. That is the bar.

The app is calm so the user's work is not. Every visual decision serves either act on this or understand this — never look at this.

Consistency comes from component reuse, not from hand-matching styles across surfaces. A row in the projects list, a row in settings, and a row in a modal are the same component, not three implementations that happen to look alike. When two surfaces do the same semantic thing in two different ways, one of them is wrong.

2. Component reuse

A semantic element used in three or more places is a primitive. One of a kind is a screen.

Primitives live in packages/app/src/components/ui/ and packages/app/src/components/headers/. Card and row layout live in packages/app/src/styles/settings.ts. Section structure lives in packages/app/src/screens/settings/settings-section.tsx.

A pressable styled to look like a button is wrong; the button is (`packages/app/src/components/ui/button.tsx`). A pressable wrapping an icon is wrong; the icon action is `<ToolbarButton>` (`packages/app/src/components/ui/pane-content-toolbar.tsx`), which owns the hitbox, the rounded `interactionHighlight` fill on hover and press, the compact size, and the tooltip. Rows on a menu surface are `<MenuItem>`, or `<ComposerTrackRow>` in a track panel; other rows are (packages/app/src/components/ui/press-highlight.tsx), which flashes on native the moment a finger lands. A bare <Text> styled to look like a section header is wrong; the section header is <SettingsSection> (packages/app/src/screens/settings/settings-section.tsx). A custom Modal for a confirmation is wrong; the confirmation is confirmDialog (packages/app/src/utils/confirm-dialog.ts). A hand-rolled overflow menu is wrong; the menu is <DropdownMenu> (packages/app/src/components/ui/dropdown-menu.tsx). A hand-rolled status pill is wrong; the pill is <StatusBadge> (packages/app/src/components/ui/status-badge.tsx). A circle pinned over a scrolling surface is wrong; the floating action is <FloatingActionButton> (packages/app/src/components/ui/floating-action-button.tsx), one per surface, and the surface reserves FLOATING_ACTION_BUTTON_CLEARANCE below its content so the button never traps the last row.

Before adding a new component, read components/ui/. The primitive usually exists.

3. Hierarchy

Hierarchy is conveyed through weight and color, not size. Most interface text is fontSize.base; compact metadata and hints use fontSize.sm. The distinction between a row's primary line and its secondary line is foreground versus foregroundMuted.

The authored interface ramp uses a 14px base. New native installs default to 15px; web and desktop default to 14px. The Appearance Interface size setting is the rendered fontSize.base value and scales the rest of the UI ramp proportionally. Primary readable content has its own fontSize.content, which defaults to 16px on native and 15px on web and desktop. It owns message bodies, composer input, Markdown, and PR prose. Controls, navigation, metadata, tool chrome, code, diffs, editors, and terminals stay on their interface or code tokens. Code size remains independent.

Weight has three tiers, applied by role:

Screen titles — the title in app chrome — use <ScreenTitle> (packages/app/src/components/headers/screen-title.tsx), which renders fontSize.base at weight 400 on compact and 300 on desktop. The New workspace hero is the only larger product title; it uses fontSize["2xl"] (packages/app/src/screens/new-workspace-screen.tsx).
Structural labels use fontWeight.medium. This applies to section labels above a stack of rows (packages/app/src/components/agent-list.tsx:519-523, packages/app/src/components/keyboard-shortcuts-dialog.tsx:63-67), form field labels above an input inside a modal (packages/app/src/components/add-host-modal.tsx:19-23, packages/app/src/components/pair-link-modal.tsx:24-28), the title at the top of a modal/sheet/dialog (packages/app/src/components/adaptive-modal-sheet.tsx:90-94, packages/app/src/components/ui/combobox.tsx:1607-1611, packages/app/src/components/welcome-screen.tsx:48-53), action button labels in tight components such as the sidebar callout actions (packages/app/src/components/sidebar-callout.tsx:218-221), and inline data emphasis on dense metadata rows (packages/app/src/components/git-diff-pane.tsx:2322-2327, packages/app/src/components/file-explorer-pane.tsx:1115-1122).
Content uses fontWeight.normal. This applies to settings rows (packages/app/src/styles/settings.ts), sidebar primary list-item titles (packages/app/src/components/sidebar-workspace-list.tsx:2680-2686, packages/app/src/components/agent-list.tsx:572-578), `` text (packages/app/src/components/ui/button.tsx:80-84), <StatusBadge> text (packages/app/src/components/ui/status-badge.tsx:56-60), and <SidebarCallout> titles (packages/app/src/components/sidebar-callout.tsx:175-180).

The rule, condensed: text that names a surface or a group is medium. Text that lives inside a surface or a group is normal. Top-of-screen titles are <ScreenTitle>, which is lighter still.

Foreground is for the thing being acted on: row titles, section headings, the selected sidebar item. foregroundMuted is for context: hints, descriptions, secondary metadata, idle sidebar items, placeholders, status text.

foregroundExtraMuted is reserved for passive chrome that must sit behind muted text, such as an always-visible window control. Use the solid token instead of lowering SVG opacity; per-path opacity makes overlapping icon strokes render unevenly. Interactive hover and pressed states return to foreground.

Accent is the one CTA per surface. A `` filled with accent appears at most once on a page. Most pages have zero — settings is mostly toggles and text, the workspace pane is mostly content, the chat composer is the input itself.

Destructive is a color, not a click. Restart-daemon and remove-host are `` in the row trailing slot; the destructive surface only appears inside the confirmDialog (packages/app/src/screens/settings/host-page.tsx:541-547). Workspace archive opens a confirm dialog before any red appears (packages/app/src/components/sidebar-workspace-list.tsx). Red appears after the user has indicated intent.

4. Buttons

The button is `` (packages/app/src/components/ui/button.tsx). It has five variants. Each has one job.

default is the one primary action on a surface — filled with accent. At most one per page. The primary slot inside an <AdaptiveModalSheet> and the highlighted action on the welcome screen are the canonical uses.

secondary is the paired action when two actions carry equal weight — filled with surface3. The component default is secondary, which matches its frequency in the codebase.

outline is the low-frequency action that lives on a row — transparent with borderAccent. Restart, Remove, Update on host detail (packages/app/src/screens/settings/host-page.tsx:585-594).

ghost is structural and non-committal — no border, no fill. Back arrows, header toggles, "Load more" footers (packages/app/src/screens/sessions-screen.tsx:54-63), more-affordances. Ghost is used when the affordance is part of the chrome, not a decision.

Header and toolbar controls use interactionHighlight for hovered, pressed, open, and selected
backgrounds. It is a translucent semantic fill so the same control works over the main surface and
the sidebar. Apply it as backgroundColor; setting opacity on the control also fades its content.

destructive is filled with destructive. It only appears inside a confirm. The button on the page is outline; the destructive button is the confirm button inside the dialog.

Sizes: xs for ultra-tight inline triggers. sm for any button sitting in a row. md is the page default. lg is reserved for large standalone CTAs.

Sizes are a shared contract across control kinds, defined once in control-geometry.ts: xs = 28px tall with fontSize.sm labels, sm = 32px with fontSize.base, md/lg = 44px with fontSize.base. <SegmentedControl> (packages/app/src/components/ui/segmented-control.tsx) takes the same xs/sm/md sizes — a segmented control next to a `` of the same size always matches in height, label size, and corner radius. Its segments run one padding step tighter than a button, because the gap between segments already reads as padding. The selected segment is a surface3 fill with foreground text, not an inverted one — inverting it inside thin chrome puts a white slab in the toolbar. Thin chrome such as the file toolbar uses xs; settings rows use sm. Never shrink a control's font or padding locally to fit a context — if the context needs a smaller control, the size tier is missing or the wrong one is in use.

A wrapping a `<Text>` is a sixth variant. It is wrong. accepts style, textStyle, leftIcon, disabled, size, and variant.

5. Borders

Borders group, separate, or rarely emphasize.

A logical block of related rows lives inside a card — one border around the whole group. The card primitive is settingsStyles.card; the keyboard-shortcuts dialog uses the same shape inline (packages/app/src/components/keyboard-shortcuts-dialog.tsx:68-73). The border defines what belongs together.

Rows after the first inside a card carry settingsStyles.rowBorder — a single top border. The first row never has one. The same divider pattern appears in the keyboard-shortcuts dialog rows (packages/app/src/components/keyboard-shortcuts-dialog.tsx:74-83). Rows do not need their own background to feel separated.

A list that is itself the page content — sidebar items in sidebar-workspace-list.tsx, the workspace list, the agent list (packages/app/src/components/agent-list.tsx) — uses spacing and surface, not borders, to separate items. Rows-in-a-card is an interior pattern; lists-as-pages are not.

Pane chrome — the workspace pane header, the file-explorer header, the diff pane header — uses a single bottom border to separate the header from the content (packages/app/src/components/git-diff-pane.tsx:2328-2331). One border, no shadow.

borderAccent is reserved for the outline button. Inputs use border. Single-thing borders are wrong; a single bordered element is either a card with one row (use the card) or it does not need a border.

6. Pickers

Five primitives. The pick is determined by option count, the need to search, and how the picker is anchored.

<DropdownMenu> is for a small fixed set anchored to a trigger. Theme picker, kebab menus on workspace and project rows (packages/app/src/components/sidebar-workspace-list.tsx:684-770), row "more" menus. Items can be async (status: "pending") and can include destructive entries. Under ~10 options where the user knows what they're looking for.

<Combobox> is for a large or searchable list. Host switcher in the sidebar footer, model selector in the composer, branch switcher in the workspace header (packages/app/src/components/branch-switcher.tsx). The user types to find the option, or the list is long enough to scroll.

<ContextMenu> is for right-click and long-press on a target. The row is the trigger; there is no visible affordance. Used for incidental actions on workspace rows in the sidebar (packages/app/src/components/sidebar-workspace-list.tsx).

<AdaptiveModalSheet> is for a focused task. Multi-field forms (packages/app/src/components/add-host-modal.tsx, packages/app/src/components/pair-link-modal.tsx, packages/app/src/components/project-picker-modal.tsx), confirmations with detail, anything that earns a backdrop. Bottom sheet on compact, centered card on desktop. Raw Modal is wrong for any of these.

<AdaptiveModalSheet> owns the presentation. Its content inset — the gutter that puts sheet content on the same rails as the sheet header — and compact bottom safe-area padding are the sheet's, not the caller's. A caller declares layout intent through contentStyle and never branches on form factor to add its own margins. If a sheet's first snap point is shorter than its header, content, and safe-area clearance, raise that snap point rather than moving the sheet container.

confirmDialog is for destructive yes/no and imperative confirmation. Promise-based: await confirmDialog({ destructive: true, ... }). Anything where a wrong click loses work.

Three themes is DropdownMenu. Thirty hosts is Combobox. A label and a value is AdaptiveModalSheet. "Are you sure?" is confirmDialog.

7. Density and rhythm

Settings detail pages, the projects detail page, and any list+detail content sit inside a centered, max-width 720 column (packages/app/src/screens/settings-screen.tsx, packages/app/src/screens/projects-screen.tsx). Lines stay readable, the eye does not have to track wide horizontal distances. Form modals carry their own narrower content frame (packages/app/src/components/add-host-modal.tsx).

Workspace and chat surfaces use the full width — these are working surfaces, not reading surfaces. The composer carries MAX_CONTENT_WIDTH from packages/app/src/constants/layout.ts to keep lines readable while letting the workspace pane fill the rest.

Sections sit apart. <SettingsSection> owns its own bottom margin; the next thing is wrapped in another <SettingsSection>. The agent-list sectionHeading carries the same marginTop/marginBottom rhythm (packages/app/src/components/agent-list.tsx:511-517). Adding marginBottom to a section is wrong.

A section or group explains itself through the info prop on <SettingsSection> or <SettingsGroup> — an info icon beside the header that opens a tooltip (packages/app/src/components/settings/headings/settings-info-tip.tsx). A muted paragraph between the header and the card is wrong: it sits in the section's own gap, so it reads as a second heading rather than as prose belonging to the header. Explanatory copy that describes one row belongs to that row, as settingsStyles.rowHint inside the card.

Cards inside a section sit closer than sections. Rows inside a card touch — only the divider separates them. The rhythm is page → spacious; section → spacious; card → tight.

Rows have generous vertical padding: roughly 16px of content plus 16px of vertical padding for settings rows, 8–12px for sidebar list items where many rows must fit. Compressing rows below the established density to fit more on the screen is wrong. Too many rows means more cards or more sections, not smaller rows.

The whitespace is the design.

8. Alignment

Things align to their glyphs, not to their boxes. A row's leading icon, its title, and the label of the button in its trailing slot sit on the same rails — the ink lines up, not the padding, not the touch target, not the hover background.

Pick the rails from the content, then hold them. A settings card establishes a leading rail at the icon's left edge and a trailing rail at the last glyph's right edge; every row in that card uses the same two. A row whose icon is absent still starts its title on the leading rail. Indentation is a new rail, not an arbitrary offset.

The pressable is bigger than the glyph, and that is fine. Hit areas grow outward from the aligned content — they never move it. A button that looks two pixels off because its padding is asymmetric is misaligned even though its box is correct.

Optical alignment beats arithmetic when a glyph disagrees with its bounding box. Icons with visual weight on one side, chevrons, and single-character labels usually need a small nudge to look centered. Trust the eye, then leave a comment saying the offset is optical.

One row off the rail makes the whole card look unconsidered.

9. Responsiveness

Compact-first. The small case is designed; the large case adds chrome around it.

The list+detail pattern is canonical and reused across surfaces. The settings shell (packages/app/src/screens/settings-screen.tsx) and the projects screen (packages/app/src/screens/projects-screen.tsx) implement it identically:

On compact: full-screen list with at the top. Tapping a row pushes a full-screen detail with its own that returns to the list.
On desktop: a 320px sidebar on the left holds the list with surfaceSidebar background. The content pane on the right holds the selected detail with <ScreenHeader>, <HeaderIconBadge>, and <ScreenTitle>.

The branching is one useIsCompactFormFactor() check at the top of the screen component. The list and the detail are the same components in both layouts; only the framing changes.

The workspace screen (packages/app/src/screens/workspace/workspace-screen.tsx) follows a different but parallel rule: tabs collapse on compact, panes split on desktop. The sidebar (packages/app/src/components/left-sidebar.tsx) is overlaid on compact and pinned on desktop.

On a narrow desktop route, app navigation yields to the rendered content topology when the remaining width cannot preserve its center target: Settings keeps its 320px list + 400px detail split, and a workspace Explorer keeps its current visible width plus a 400px center pane. That is a topology decision at the app container, not a second compact breakpoint. Temporary width clamps are render-only; widening restores the user's saved sidebar widths.

Electron window controls are top-corner obstructions, not a compact-layout condition. Rendered surfaces declare which top corners they physically occupy; only those corners receive clearance. Full-window overlays redeclare both corners. A focused split pane owns both corners; if focus restoration temporarily exposes the full split tree, the split boundary reserves one top strip instead of assigning a control rectangle to an arbitrarily narrow leaf. The 720px desktop breakpoint preserves the default 320px sidebar and target 400px center width when the Explorer is closed; it is product policy, not an obstruction gate.

Windows and Linux controls are fixed window chrome, outside scrolling header content. A tab rail that reaches them ends at their obstruction and shows the shared overflow fade. On macOS, the Explorer toggle occupies a fixed top-right window slot so opening and closing Explorer does not move the pointer target.

A new list+detail feature copies the settings shell. A new workspace-shaped feature copies the workspace shell. Inventing a third shape happens in design review, not in a PR.

10. Copy and voice

Sentence case. "Pair a device", "Danger zone", "Restart daemon", "Inject Paseo tools", "No sessions yet", "Load more". Proper nouns retain casing — Paseo, Beta, Stable, Local. Title case is wrong.

No trailing periods on row titles, labels, or buttons. No trailing period on a single-clause hint: "What happens when you press Enter while the agent is running" (packages/app/src/screens/settings-screen.tsx:271-272). Periods exist inside multi-sentence prose: "Restarts the daemon process. The app will reconnect automatically."

Empty-state strings are short noun phrases or short sentences: "No projects yet", "Select a project", "No sessions yet" (packages/app/src/screens/sessions-screen.tsx:74-76), "Host not found".

Buttons are imperative: Save, Cancel, Restart, Remove, Update, Install update, Add host, Load more. In-flight labels are present-participle with a literal three-dot ellipsis: "Saving...", "Restarting...", "Removing...", "Loading...".

Error copy is direct. "Unable to remove host" (packages/app/src/screens/settings/host-page.tsx:697), not "Sorry, we couldn't remove the host." Recovery instructions are concrete: "Wait for it to come online before restarting." Errors describe state; they do not editorialize.

Terminology:

Workspace, never "checkout".
Host, except where the user-facing concept is the daemon process itself ("Restart daemon").
Project, not "repo" or "repository".
Provider, not "model provider".
Session and agent are distinct: a session is a historical entry in sessions-screen.tsx; an agent is a live entity in the workspace.

11. States

Loading is inline by default. <LoadingSpinner size={14} color={foregroundMuted} /> sits next to the thing it relates to (packages/app/src/screens/settings/providers-section.tsx:227-231). Page-level loading is a centered <LoadingSpinner size="large"> (packages/app/src/screens/sessions-screen.tsx:69-72). Card-level loading is a single short line, not a spinner. In-row dropdown items use <DropdownMenuItem status="pending" pendingLabel="Removing...">; the menu item handles its own pending state.

Screen-level empty states use a centered, muted noun phrase and at most one ghost button (packages/app/src/screens/sessions-screen.tsx). Sidebar list empty states use a quiet bordered card with a left-aligned sm title, a muted sm description, and xs `` actions. Use secondary for the primary action and outline for a secondary action (packages/app/src/components/sidebar/empty-states.tsx). Keep both forms short and free of illustrations.

Inline errors are a single sentence in palette.red[300] xs, sitting under the field or inside the card it relates to (packages/app/src/screens/settings/providers-section.tsx:115-119).

Page-level alerts — informational notices, success confirmations, warnings, or recoverable errors that need a small visible block on the page — use <Alert> (packages/app/src/components/ui/alert.tsx). Variants: default, info, success, warning, error. The chrome is quiet by design: a 1px tinted border, transparent background, a small variant-tinted icon, the title in the variant accent, the description in foregroundMuted. Actions go in the children slot as `` — recovery actions are low-frequency and outline keeps them quiet alongside the alert's accent (packages/app/src/screens/project-settings-screen.tsx). One <Alert> at a time per region.

Sidebar callouts — cross-cutting alerts that apply across the whole app, like worktree setup, Rosetta install, and desktop update available — register through useSidebarCallouts() and render in the left sidebar via <SidebarCallout> (packages/app/src/components/sidebar-callout.tsx). The chrome (top-border-only, full-width action buttons) is tuned for that ~280px column. Canonical sources: packages/app/src/components/worktree-setup-callout-source.tsx, packages/app/src/desktop/updates/rosetta-callout-source.tsx, packages/app/src/desktop/updates/update-callout-source.tsx. Never import <SidebarCallout> into a page — that's what <Alert> is for.

Imperative errors are Alert.alert("Error", "Unable to ...") (the React Native Alert API, not this component) for failures that interrupt the flow and have no place on the page.

Disabled state is opacity: theme.opacity[50] on the outer pressable. Color changes for disabled state are wrong; a disabled button is the same button, dimmer.

Partial failure (a list mostly fine but one source errored) is a bordered banner above the list, listing each failure in red-300 xs (packages/app/src/screens/projects-screen.tsx:151-159). The list still renders.

State surfaces at the smallest scope it affects. Field error stays under the field; page error is a banner; flow-stopping error is an Alert.

Changing state must not move the layout. A row that grows when its badge arrives, a card that reflows when a count resolves, a list that jumps as data streams in — all wrong. Reserve the space the loaded state will need, so the skeleton, the spinner, and the content occupy the same box. A surface that shifts under the user stops feeling calm.

12. List rows

The row anatomy is a content column with an optional trailing slot. Inside a card the row is settingsStyles.row. Inside a sidebar list the row carries its own padding and borderRadius.lg per item (packages/app/src/components/sidebar-workspace-list.tsx:2614-2625).

Rows that drill into a detail lead with a chevron in the trailing slot (ChevronRight, iconSize.sm, foregroundMuted). The whole row is the ``. Pair-device row (packages/app/src/screens/settings/host-page.tsx:644-668), provider row (packages/app/src/screens/settings/providers-section.tsx:92-132), project row in the projects list. A fixed right chevron means navigation. An expandable row uses a trailing right chevron that rotates down when expanded (SettingsCollapsibleRow); pressing the row reveals its child rows in place.

Kebab menus (<DropdownMenu> with <MoreVertical size={14} /> trigger) are for actions on the row, not navigation. Trigger style: padding: 2, borderRadius: 4, hover background surface2. Menu position: align="end". Items use <DropdownMenuItem leading={} ...>. Visibility is isHovered || isTouchPlatform — hover-revealed on web, always visible on native (packages/app/src/components/sidebar-workspace-list.tsx:684-770).

A row may carry both a chevron and a kebab when both navigation and row-level actions apply. Chevron sits at the end; kebab sits before it.

Switches and segmented controls also sit in the trailing slot. A row that both navigates and toggles is a `` with a <Switch> in the trailing slot — the switch calls event.stopPropagation() so the row press does not fire (packages/app/src/screens/settings/providers-section.tsx:92-132). Sidebar items that hold a status dot, a count, and a kebab follow the same rule (packages/app/src/components/sidebar-workspace-list.tsx).

Selected state on rows in a desktop list+detail uses surfaceSidebarHover as the background (packages/app/src/screens/projects-screen.tsx). Selected state on rows in the sidebar list uses surface2 (packages/app/src/components/agent-list.tsx:563-571).

13. Status pills and badges

There is exactly one token per status signal — statusSuccess, statusDanger, statusWarning, statusMerged — and every status surface uses it: PR state icons, CI check icons and pies, diff stats, file-change icons, status pills, usage bars. A surface does not get a quieter or louder variant because of where it sits. If a dense list feels loud, that is a density or weight problem; fix the density, not the color. The tokens are generated, not hand-picked — see the rule in packages/app/src/styles/theme.ts and regenerate rather than nudging one value. The level is set by the densest consumer, the sidebar workspace list.

Status dots are the one exception, and they are a family of their own — statusDotSuccess, statusDotDanger, statusDotWarning, statusDotRunning, read only by getStatusDotColor (packages/app/src/utils/status-dot-color.ts). Same hues and the same generation rule, but their own band: 90% of gamut chroma against the status family's 55–60%. A dot is a few points of solid color with no shape to read and no label attached, and the running one pulses, so at the status band's chroma the dots read dimmer than the metadata beside them — backwards, since the dot is the row's state. Lightness is set by hue separation rather than by distance from the surface: at 6pt four dark hues on a light surface all read as one dark blob no matter how much contrast they have. So the light band runs as bright as the contrast floor allows at L=0.62, the last step where all four clear 3:1 against the sidebar's surface2; the dark band sits at L=0.72, where danger turns pink above. All four move together; regenerate the set, never one hue.

Status pills use the status token for text on the shared surface3 and border shell. The neutral shell keeps the signal legible without manufacturing translucent colors outside the theme. The <StatusBadge> primitive (packages/app/src/components/ui/status-badge.tsx) is canonical; a pill never reaches into palette.

Status dots — the small filled circles next to a host or agent name — are borderRadius.full filled with the status token. Which token a given agent state maps to is owned by getStatusDotColor (packages/app/src/utils/status-dot-color.ts); a row, a group header, and a project icon all call it rather than restating the mapping. They sit in the trailing slot of a sidebar row or as a leading marker on a status pill.

Identity badges — the project icon, the sidebar host badge, and the PR-panel participant avatar — do not use the theme palette. They draw from the fixed ten-color identity table in packages/app/src/styles/identity-colors.ts, whose hexes are held to one contrast band so a color identifies rather than ranks. Project icons and PR avatars use it as a fill with a white letter — that is identityColor, one theme-independent hex per identity. Host badges use it as a foreground on both the glyph and the label, which is a different contrast problem that the fill table cannot solve: no single hex clears 4.5:1 against both a near-white and a dark sidebar. Foregrounds therefore come from identityForeground(name, colorScheme), one set per scheme, hue unchanged. That set is generated on the status family's lightness and chroma fraction, because a meta row puts a host badge beside a CI check and a diff stat, and two families at different lightness make the brighter one shout. Change the status band and this one changes with it. A host with no color assigned falls back to foregroundMuted. The table is theme-independent by design; do not fork it per theme, and do not add hexes to it without recomputing the band.

New status pills use <StatusBadge>. Identity, shortcut, and interactive link badges remain separate because color does not encode status there.

14. Forbidden

fontWeight.medium on row titles, body text, button labels, badge text, or <SidebarCallout> titles. Medium is reserved for the structural-label tier described in §3 — section labels, modal/sheet titles, dense metadata emphasis, and tight action labels. Anything else is normal. <ScreenTitle> is responsive 400/300 and is never overridden.
wrapping `<Text>` to make a button. exists.
Importing Pressable or a Touchable* outside components/ui/. A raw pressable has no standard press or hover feedback, so every one drifts. paseo/no-raw-pressable reports it; the files on its burn-down list in .oxlintrc.json may only leave it.
Bare <Text> for a section header inside settings. <SettingsSection> exists.
A muted paragraph between a section header and its card. Section-level explanation is the header's info tooltip (§7).
A "Settings" CTA on a detail page. Detail pages are settings; settings is reached from the sidebar, the host entry, or a row's kebab menu.
The word "checkout" in UI strings or identifiers. The term is "workspace".
New color tokens or hardcoded hex outside the palette. The identity color table is the documented exception (§13), not a license.
Placeholder text dimmed beyond foregroundMuted. No extra opacity, no italics, no ghost-text.
onPointerEnter and onPointerLeave. They do not fire on native iOS. Hover uses Pressable's onHoverIn/onHoverOut gated with isHovered || isCompact || isNative.
Raw DOM APIs without an isWeb guard.
Spacing values outside the scale. padding: 20 and gap: 10 are wrong.
Color changes for disabled state. Opacity only.
Destructive actions without confirmDialog. Restart, remove, and future destructive actions are confirmed. Archive workspace is confirmed only when its worktree backing reports uncommitted changes or unpushed commits; otherwise it archives immediately.
Bespoke status pills. <StatusBadge> is the pill primitive.
Raw Modal for a focused task. <AdaptiveModalSheet> is the modal primitive.
Importing ActivityIndicator directly. <LoadingSpinner> is the loading primitive.

15. Canonical surfaces by pattern

Pattern	Reference
List+detail (compact stack, desktop sidebar+pane)	`packages/app/src/screens/settings-screen.tsx`, `packages/app/src/screens/projects-screen.tsx`
Detail card+row	`packages/app/src/screens/settings/host-page.tsx`, `packages/app/src/screens/settings/providers-section.tsx`
Section grouping inside a card list	`packages/app/src/screens/settings/settings-section.tsx`
Form modal (label + input fields, primary + cancel)	`packages/app/src/components/add-host-modal.tsx`, `packages/app/src/components/pair-link-modal.tsx`, `packages/app/src/components/project-picker-modal.tsx`
Destructive confirmation	`confirmDialog` invoked from `packages/app/src/screens/settings/host-page.tsx:541-547`
Centered hero / first-run	`packages/app/src/components/welcome-screen.tsx`
Sidebar list (workspaces, hosts)	`packages/app/src/components/sidebar-workspace-list.tsx`, `packages/app/src/components/left-sidebar.tsx`
Live list of items with sections (agents)	`packages/app/src/components/agent-list.tsx`
Historical list (sessions)	`packages/app/src/screens/sessions-screen.tsx`
Workspace pane (multi-tab, split)	`packages/app/src/screens/workspace/workspace-screen.tsx`
Composer / message input	`packages/app/src/components/composer.tsx`, `packages/app/src/components/message-input.tsx`
Pane chrome with single bottom border	`packages/app/src/components/git-diff-pane.tsx`, `packages/app/src/components/file-explorer-pane.tsx`, `packages/app/src/components/terminal-pane.tsx`
Page-level alert (info / success / warning / error)	`packages/app/src/components/ui/alert.tsx`, `packages/app/src/screens/project-settings-screen.tsx`
Sidebar callout (cross-cutting alert)	`packages/app/src/components/sidebar-callout.tsx`, `packages/app/src/contexts/sidebar-callout-context.tsx`, `packages/app/src/components/worktree-setup-callout-source.tsx`, `packages/app/src/desktop/updates/rosetta-callout-source.tsx`, `packages/app/src/desktop/updates/update-callout-source.tsx`
Searchable picker	`packages/app/src/components/ui/combobox.tsx`, `packages/app/src/components/branch-switcher.tsx`
Trigger-anchored menu	`packages/app/src/components/ui/dropdown-menu.tsx` (used in `sidebar-workspace-list.tsx`, theme picker)
Right-click / long-press menu	`packages/app/src/components/ui/context-menu.tsx` (used in `sidebar-workspace-list.tsx`)
Headers (back, screen, menu)	`packages/app/src/components/headers/back-header.tsx`, `screen-header.tsx`, `menu-header.tsx`

Development (`docs/development.md`)

Development

Prerequisites

Node.js (see .tool-versions for exact version)
npm workspaces (comes with Node)

Running the dev server

bash

npm run dev:server
npm run dev:app
npm run dev:desktop

Root checkout dev is intentionally split across terminals:

npm run dev:server runs the daemon on 127.0.0.1:6768.
npm run dev:app runs Expo on http://localhost:8081 and connects to the dev daemon.
npm run dev:desktop runs its own Electron-flavored Expo server on the first free port from 8082 through 8089. It never claims port 8081.

Desktop dev launches its desktop-managed daemon with PASEO_NODE_ENV=development,
so development-only providers such as Mock Load Test are available. Packaged
desktop launches always force the daemon to production mode.

The web and desktop dev launchers pass the current Git branch to Metro as
EXPO_PUBLIC_PASEO_DEV_BUILD_LABEL. The expanded desktop sidebar shows it in
the titlebar row. Production builds leave the variable unset and show no label.

npm run dev is only a shorthand for npm run dev:server. Keep 127.0.0.1:6767 for the packaged app and production-style ~/.paseo state.

Nix desktop package

The flake exposes packages.<system>.desktop on Linux and macOS:

bash

nix build .#desktop

Linux produces the paseo-desktop launcher and desktop entry. macOS produces
Applications/Paseo.app plus the paseo-desktop launcher. Both use the nixpkgs
Electron runtime and the checkout's built daemon, client, and renderer rather
than downloading a published desktop release.

PASEO_HOME

PASEO_HOME is the directory that holds runtime state (agents, worktrees, workspace config, sockets, daemon log). Resolution rules:

The server itself (e.g. when launched by the desktop app or npm run start) defaults to ~/.paseo (see packages/server/src/server/paseo-home.ts).
Repo dev scripts default to $ROOT/.dev/paseo-home, where $ROOT is the current checkout or worktree root. This keeps all dev state scoped to the checkout instead of the packaged desktop app.
npm run cli -- ... runs through the same dev-home wrapper as the dev scripts, so the in-repo CLI automatically targets the current checkout's .dev/paseo-home and configured dev daemon endpoint.
Paseo-created worktrees seed $PASEO_WORKTREE_PATH/.dev/paseo-home from $PASEO_SOURCE_CHECKOUT_PATH/.dev/paseo-home by copying durable JSON metadata. Runtime files like pid files, sockets, and logs are not copied.
This repo's worktree setup also best-effort seeds packages/app/ios and the newest .dev/ios-build entry from the source checkout so iOS simulator services can reuse native project and Xcode cache state when it is safe enough to do so.

Override knobs:

bash

PASEO_HOME=~/.paseo-blue npm run dev          # explicit home
PASEO_DEV_SEED_HOME=/path/to/home npm run dev # seed from a different source home
PASEO_DEV_RESET_HOME=1 npm run dev            # clear and reseed the derived worktree home

Daemon endpoints

Stable daemon launched by the desktop app: localhost:6767.
Root checkout dev daemon: localhost:6768.
Root checkout Expo: http://localhost:8081.
Root checkout desktop dev Expo: first free port from 8082 through 8089.
npm run dev (Windows): localhost:6767 for the daemon.

In Paseo-managed worktree services, use the injected service environment rather than hardcoded root checkout ports.

Expo Router

Route ownership, startup restore, and native blank-screen gotchas live in
expo-router.md. Read it before changing packages/app/src/app,
startup routing, remembered workspace restore, or active workspace selection.

iOS simulator preview service

Paseo worktrees expose the native iOS dev app through the ios-simulator service in paseo.json. The service URL serves the simulator preview at /.sim, so the preview link is ${PASEO_URL}/.sim.

Prerequisites (macOS only). The service shells out to the Apple toolchain, so beyond the npm ci that worktree setup runs you must install:

Xcode (the full app, not just the Command Line Tools) — install it from the Mac App Store, or from developer.apple.com/download for a specific version. It provides xcodebuild and xcrun simctl; accept its license and let first-run component installation finish before starting the service.
An iOS Simulator runtime with at least one iPhone device type. Recent Xcode versions may not bundle a runtime — add one via Xcode → Settings → Components (older Xcode: "Platforms"). The service targets iPhone 16 Pro by default (override with PASEO_IOS_DEVICE_TYPE) and falls back to any iPhone; it fails with No iPhone simulator device type is installed when none exist.
Homebrew — CocoaPods itself installs automatically: expo prebuild runs pod install on a cold worktree, and when the CocoaPods CLI is missing the runner installs it for you. It tries gem install cocoapods first and falls back to Homebrew (brew install cocoapods), so having Homebrew available lets that fallback succeed without a manual step.

serve-sim, Expo, and Metro come from npm ci, and CocoaPods installs itself on the first prebuild as described above.

The service is designed for concurrent worktrees: it derives a deterministic simulator identity from the worktree path, uses the worktree's assigned PASEO_PORT, pins serve-sim to that simulator UDID, and only tears down that worktree's helper/simulator state. It must not rely on the globally booted simulator or any fixed Metro port.

Worktree setup best-effort seeds the generated iOS project and newest native build cache from the source checkout before the service runs. The service still validates the native project by running Expo prebuild and Xcode; the seed only avoids paying all setup/build cost from a cold worktree every time.

Starting the service must not create, focus, reveal, or leave behind macOS Simulator.app windows — a guard hides Simulator.app every 250ms, so the native window vanishes if you focus it. The user-visible surface is the interactive /.sim preview: a serve-sim stream (60 FPS MJPEG + a WebSocket control channel) that Metro mounts at basePath: "/.sim" (packages/app/metro.config.cjs) and that forwards taps and gestures, so first-launch prompts like "Open in PaseoDebug?" are answered there, not in the native window. Open the ${PASEO_URL}/.sim link the service prints — not serve-sim's raw stream port (:3100), which is view-only. Because the stream sits behind the daemon proxy it is convenient for remote viewing but laggy up close; for fast local dev at the Mac, use the native simulator path below.

Troubleshooting. If xcrun simctl fails with unable to find utility "simctl", the active developer directory is still the Command Line Tools even though Xcode is installed. Point it at Xcode: sudo xcode-select -s /Applications/Xcode.app/Contents/Developer, then confirm with xcrun --find simctl.

Running the iOS app on a local simulator

For fast, native, interactive iOS dev at the Mac — as opposed to the remote /.sim preview above — skip the service and build the dev client directly:

bash

npm run ios        # → expo run:ios (packages/app): builds and launches the app in the real Simulator.app

expo run:ios starts its own Metro and gives you the normal Simulator.app window (full speed, native touch, no stream).

Pointing the app at a daemon. The client resolves its local daemon from EXPO_PUBLIC_LOCAL_DAEMON (packages/app/src/runtime/host-runtime.ts); when unset it falls back to localhost:6767, the production ~/.paseo daemon. To target a worktree's dev daemon instead, set it on the build command:

bash

EXPO_PUBLIC_LOCAL_DAEMON=localhost:${PASEO_SERVICE_DAEMON_PORT} npm run ios   # worktree daemon running as a Paseo service
EXPO_PUBLIC_LOCAL_DAEMON=localhost:6768 npm run ios                          # standalone `npm run dev:server`

The iOS simulator shares the Mac's loopback, so localhost: reaches the host daemon directly.

Gotcha — EXPO_PUBLIC_* is inlined into the JS bundle at Metro bundle time, not read at runtime. Set it in the same shell that starts Metro. If the app still connects to the old daemon, Metro served a cached bundle; re-bundle clean with cd packages/app && EXPO_PUBLIC_LOCAL_DAEMON=… npx expo start -c and reload the app.

Desktop renderer profiling

npm run dev:desktop starts Electron with Chromium remote debugging enabled so
renderer CPU profiles can be captured through CDP. By default it passes
--remote-debugging-port=0, so Chromium atomically asks the OS for an available
port and prints the selected DevTools endpoint. Set
PASEO_ELECTRON_REMOTE_DEBUGGING_PORT when a QA workflow requires a validated,
fixed port.

Desktop dev also scopes Electron userData to the current dev root. This prevents
desktop-only environment inherited by terminals opened inside Paseo from coupling
a new worktree instance to the parent desktop instance's profile or single-instance
lock.

The desktop workspace script execs the dev runner so the terminal owns the runner
PID. Terminal shutdown reaches the runner as SIGHUP; the runner stops Metro and
asks Electron to quit through its normal app lifecycle. Do not add an npm wrapper or
detach Electron: either change leaves an orphan holding the worktree's single-instance
lock and broken output pipes.

With desktop dev running, verify the real BrowserWindow, titlebar clearance, fullscreen
transition, and 751-pixel settings split with:

bash

npm run verify:electron-cdp --workspace=@getpaseo/desktop

The verifier reads the same EXPO_PORT and
PASEO_ELECTRON_REMOTE_DEBUGGING_PORT environment names as desktop dev. Set an
explicit remote-debugging port for verifier runs, and set both when testing an
isolated instance on non-default ports.

When running a dedicated Electron QA instance against a non-default Expo port, set
EXPO_DEV_URL explicitly. Desktop main defaults to http://localhost:8081, so
PASEO_PORT=57928 alone starts Metro on 57928 but Electron still loads 8081.

React render profiling

The app has a gated React render profiler in
packages/app/src/utils/render-profiler.tsx. Wrap the component boundary you want
to measure with RenderProfile, then open the app with ?renderProfile=1. When
the query param is absent, RenderProfile returns children directly and records
nothing.

Captured samples are exposed on globalThis.__PASEO_RENDER_PROFILE__. Call
globalThis.__PASEO_RESET_RENDER_PROFILE__?.() after warm-up and before the
interaction you want to measure. If a memo comparator or subscription boundary
needs explanation, call recordRenderProfileReasons(id, reasons) while profiling;
reason counts are exposed on globalThis.__PASEO_RENDER_PROFILE_REASONS__.

Use this workflow for any render investigation:

Add stable RenderProfile boundaries around the suspected root and expensive
children. Keep IDs specific enough to compare before and after.
Reproduce against real app state, not toy fixtures, whenever practical.
Record an idle baseline first. If idle is noisy, fix or account for that
before optimizing the interaction.
Warm up the route, reset profiler samples, run the exact interaction, then
compare actualDuration, render counts, and per-commit samples.
When a memo boundary still renders, record reasons before changing code. Do
not guess from object identity alone.
Keep changes that move the measured profile. Remove probes or memo wrappers
that do not move the number.

What this caught during the workspace tab investigation:

A large apparent workspace cost was real interaction work, not daemon noise;
the idle baseline stayed near zero.
The expensive stream rerender was mostly prop identity churn from pane context
callbacks and capability objects, not new stream data.
Stabilizing provider actions at the pane boundary helped because every mounted
panel consumes that context.
Comparing value-shaped capability flags beat preserving object identity through
unrelated stores.
Some plausible fixes did not pay off: memoizing the tab row and composer draft
object barely moved the profile, so they were removed.

Existing scenario script: workspace agent/terminal tab switching. Start Expo on
web, keep a daemon available, then run:

bash

PASEO_PROFILE_SERVER_ID=<server-id> \
PASEO_PROFILE_WORKSPACE_ID=<workspace-path> \
PASEO_PROFILE_AGENT_ID=<agent-id> \
  npm run profile:workspace-tabs --workspace=@getpaseo/app

This script opens the app with ?renderProfile=1, creates a temporary terminal
tab, switches between a real agent and that terminal, prints aggregated React
Profiler timings, then removes the temporary terminal. It is an example of the
workflow above, not the only way to use the profiler. Useful knobs:

bash

PASEO_PROFILE_APP_URL=http://localhost:19010 # Expo web URL
PASEO_PROFILE_SWITCH_COUNT=1                # number of agent/terminal switch pairs
PASEO_PROFILE_SWITCH_WAIT_MS=250            # delay after each click
PASEO_PROFILE_IDLE_WAIT_MS=3000             # idle baseline before switching
PASEO_PROFILE_DUMP_COMMITS=1                # include per-commit profiler samples

For warm workspace switching, point the benchmark at an app backed by seeded
daemon state:

bash

PASEO_PROFILE_APP_URL=http://localhost:19010 \
  npm run profile:workspace-switching --workspace=@getpaseo/app

The benchmark first warms Cmd+1 through Cmd+7, then records a rapid seven-workspace
burst. It separately warms the three-entry workspace deck LRU and records Cmd+1 through
Cmd+3 without waits between keys. Both scenarios report keydown-to-activation latency and
React commits on the same browser clock. Set PASEO_PROFILE_WORKSPACE_DIGITS,
PASEO_PROFILE_WORKSPACE_LRU_SIZE, or PASEO_PROFILE_WARM_QUIET_MS to change the shape. Set
PASEO_PROFILE_DUMP_COMMITS=1 to include the nested component breakdown for every commit.
Set PASEO_PROFILE_RETAINED_REPEATS=5 to repeat the retained-LRU burst for a less noisy sample.
Set PASEO_PROFILE_CPU_PATH=/tmp/workspace-switch.cpuprofile to run a separate retained-LRU
capture after the latency scenarios and write a raw CDP CPU profile without contaminating their
timings.
Set PASEO_PROFILE_TRACE_PATH=/tmp/workspace-switch.trace.json to run another separate retained-LRU
capture and write a Chromium Performance trace with User Timing marks and screenshots. Open the
trace in the Chrome DevTools Performance panel. Set PASEO_PROFILE_TRACE_INVALIDATIONS=1 only for a
focused invalidation capture; React Native's generated stacks make that mode highly intrusive.
Set PASEO_PROFILE_TRACE_FOCUS=1 to include focus targets, durations, and JavaScript call stacks in
the scenario report. This mode wraps HTMLElement.focus, so use it only for diagnosis.

For the desktop Explorer sidebar toggle, run the app against the root checkout's daemon and use:

bash

npm run profile:explorer-toggle --workspace=@getpaseo/app

The harness verifies port 6768, opens the Paseo workspace, creates and warms the Explorer pane,
records an idle control, then measures settled and 50 ms burst Cmd+E toggles. It reports
input-to-DOM and input-to-paint latency, React commits, mounts, unmounts, and DOM mutations. Set
PASEO_PROFILE_TRACE_PATH=/tmp/explorer-toggle.trace.json or
PASEO_PROFILE_CPU_PATH=/tmp/explorer-toggle.cpuprofile for separate Chromium captures. Override
the app URL, daemon port, workspace, or server with the corresponding PASEO_PROFILE_* variables.

For sustained composer typing, run the paired composer-versus-textarea benchmark against a seeded
daemon:

bash

PASEO_PROFILE_APP_URL=http://localhost:19010 \
  npm run profile:composer-typing --workspace=@getpaseo/app

The benchmark opens the first workspace, preserves its existing draft, and dispatches 300 printable
keys at a fixed 16 ms cadence without waiting for each key to paint. It measures renderer
keydown to the next paint opportunity, verifies that every character survived, alternates the
composer and plain-textarea control across three runs, then restores the original draft. The report
includes percentiles, frame coalescing, input processing, React work, long tasks, slow samples, and
Playwright dispatch lateness. Set PASEO_PROFILE_TYPING_KEYS, PASEO_PROFILE_TYPING_CADENCE_MS,
PASEO_PROFILE_TYPING_REPEATS, or PASEO_PROFILE_WORKSPACE_DIGIT to change the scenario. Optional
PASEO_PROFILE_CPU_PATH and PASEO_PROFILE_TRACE_PATH captures run separately after the latency
measurements so profiling overhead does not contaminate them.

Set PASEO_PROFILE_TYPING_SCENARIO=height-growth to alternate Shift+Enter and printable input.
That report includes input and composer height changes plus React work grouped into composer,
stream, and ancestor/root scopes. Ancestor/root timings include descendant work because the Profiler
boundaries are nested. A printable key after an empty newline should not change either height.

Preview Windows and Linux window controls on macOS

Desktop development can replace native macOS traffic lights with Paseo's custom controls:

bash

PASEO_DESKTOP_WINDOW_CONTROLS=windows npm run dev:desktop
PASEO_DESKTOP_WINDOW_CONTROLS=linux npm run dev:desktop

The override is rejected in packaged builds. Restart the desktop process when changing it.

Desktop macOS compositor watchdog

macOS display sleep can leave Chromium's GPU-process display link — the vsync
source that drives frame production — stuck on a stale display. The compositor
then stops producing frames and the window looks frozen: unresponsive to clicks
and keys even though the renderer and every process stay alive. It self-recovers
after a few minutes, which is too long for a foreground app.

setupDarwinCompositorWatchdog
(packages/desktop/src/window/compositor-watchdog/index.ts) guards against
this. It polls the renderer for frame production every couple of seconds and,
after a sustained stall while the window is visible and unlocked, restarts the
GPU process so Chromium rebuilds the display link. The probe is skipped while
the screen is locked or the window is hidden or minimized, since a window
legitimately stops producing frames then.

The watchdog deliberately leaves background throttling enabled. Calling
webContents.setBackgroundThrottling(false) would keep the compositor producing
frames non-stop, pinning ProMotion displays at 120Hz forever and draining the
battery while the app is idle — so do not re-add it. The probe's visibility
guards already prevent throttling from causing a false stall.

Desktop Linux hidden-window fallback

On Wayland (seen on ChromeOS Linux) a window created with show: false can sit
forever without a single compositor frame: the renderer loads and runs, but
ready-to-show never fires, so the window is never shown and the app looks like
it did not start while every process is alive. showWindowWhenReady
(packages/desktop/src/window/show-when-ready.ts) shows the main window when
the document finishes loading if the event has not arrived. The fallback is
Linux-only; macOS and Windows keep waiting for ready-to-show.

Run the startup regression on Linux with an isolated display:

bash

xvfb-run -a npm run test:e2e:window-startup --workspace=@getpaseo/desktop

Daemon logs

Check $PASEO_HOME/daemon.log for daemon logs. The default level is info; set
PASEO_LOG_LEVEL=trace before launching the daemon when you need full provider,
session, and agent-manager traces for stuck-state debugging.

The supervisor rotates daemon.log. Persisted log.file.rotate settings in
$PASEO_HOME/config.json win first. Without persisted config, the optional
PASEO_LOG_ROTATE_SIZE and PASEO_LOG_ROTATE_COUNT env vars override the
defaults. The default rotation is 10m x 3 files everywhere.

Git process pressure

If Git refreshes consume too much CPU, disk, or antivirus capacity, especially on Windows, reduce
the daemon-global Git process limits in $PASEO_HOME/config.json:

json

{
  "daemon": {
    "git": {
      "maxProcessesPerSecond": 5,
      "maxProcessConcurrency": 4
    }
  }
}

Reload the daemon with paseo reload. Environment-variable overrides still require a restart because
the launch environment remains authoritative. Lower values reduce machine pressure but make Git-backed workspace state and
Git RPCs wait longer. See Git process limits for defaults,
semantics, and environment-variable overrides.

Agent Tool Catalog Measurement

Measure the MCP tools/list payload that Paseo injects into agents with:

bash

npm run measure:agent-tools --workspace=@getpaseo/server

The command reports compact JSON bytes, estimated tokens, field totals, largest
tools, and the browser-tools delta. It defaults to the agent-scoped catalog; use
-- --scope=top-level for the unaffiliated /mcp/agents shape and -- --json
for machine-readable output.

Worktree starting refs

A new worktree starts from the current branch's upstream, or the local branch when it has no
upstream. This keeps unpushed local commits out of new workspaces by default. The picker collapses
identical refs; divergent local or non-origin refs remain explicit, qualified choices.

The daemon sends the exact upstream ref because the remote and branch names cannot be inferred.
Worktrees retain that ref for comparisons and updates from base while exposing its branch name to
the UI. Merging into base requires a mutable local target: origin/main maps to local main, while
another remote fails closed until the worktree records an explicit local target. Older daemons omit
the optional field and retain the previous local-first behavior; older worktree metadata without the
exact ref also resolves through its stored branch name.

Worktrees inherit committed Git state only; uncommitted source-checkout changes are not copied.

paseo.json service scripts

worktree.setup and worktree.teardown accept either a multiline shell script or an array
of commands. Both run sequentially.

Lifecycle commands run in the worktree through a stable script shell: bash
resolved from PATH on macOS/Linux, and PowerShell with -NoProfile on
Windows. They inherit the daemon environment plus Paseo's lifecycle variables;
login and interactive shell startup files are not loaded, and Bash's BASH_ENV
hook is unset. ACP single-string terminal commands use the same non-login Bash
behavior on macOS/Linux, but preserve their existing cmd.exe /c string semantics
on Windows. Service scripts are separate:
they launch in a terminal and receive the service environment described below.

Because the shell differs per platform, a lifecycle command that must run
everywhere cannot use POSIX-only syntax — VAR=1 cmd env prefixes, $VAR
expansion, cp/rm, or a ./scripts/*.sh entrypoint all fail under PowerShell,
and bash is not guaranteed to exist on Windows. Put that logic in a Node script
that reads what it needs from process.env and invoke it as
node ./scripts/<name>.mjs. This repo's own setup does exactly that in
scripts/seed-worktree-dev-state.mjs and scripts/seed-ios-native-cache.mjs.

json

{
  "worktree": {
    "setup": "npm ci\ncp \"$PASEO_SOURCE_CHECKOUT_PATH/.env\" .env\nnpm run db:migrate",
    "teardown": "npm run db:drop || true"
  }
}

Every scripts entry with "type": "service" receives these environment variables:

Variable	Value
`PASEO_SERVICE_<NAME>_URL`	Proxied URL for a declared peer service. Prefer this for peer discovery; it survives peer restarts.
`PASEO_SERVICE_<NAME>_PORT`	Raw ephemeral port for a declared peer service. Use only as a bypass escape hatch; it can go stale if that peer restarts.
`PASEO_URL`	Self alias for `PASEO_SERVICE_<SELF>_URL`.
`PASEO_PORT`	Self alias for `PASEO_SERVICE_<SELF>_PORT`.
`HOST`	Bind host for the service process.

Service proxy hostnames use the double-dash shape: web--feature-auth--project.localhost or, on the default branch, web--project.localhost. Optional public aliases use the same leftmost label under the configured public base host.

<NAME> is normalized from the script name by uppercasing it, replacing each run of non-A-Z0-9 characters with _, and trimming leading or trailing _. For example, app-server and app.server both normalize to APP_SERVER; that collision fails at spawn time with an actionable error.

PORT is not injected by default. If a framework requires PORT, set it in the command:

json

{
  "scripts": {
    "web": {
      "type": "service",
      "command": "PORT=$PASEO_PORT npm run dev:web"
    }
  }
}

Service ports use OS ephemeral allocation by default. Set worktrees.servicePorts in
$PASEO_HOME/config.json, or replace it for one project with worktree.servicePorts in
paseo.json. The block accepts an inclusive range such as "3000-4000" or a portScript
executable. Since portScript is executed directly without a shell, it must point to a real executable (e.g., a binary or a script with a proper shebang like #!/bin/sh) rather than an inline shell command or shell pipeline. For inline shell commands or pipelines, wrap them in a small script. portScript runs in the workspace directory with four arguments: service name,
workspace ID, branch name, and worktree path. A missing branch is passed as an empty string. The same
values are available as PASEO_SCRIPTNAME, PASEO_WORKSPACE_ID, PASEO_BRANCH_NAME, and
PASEO_WORKTREE_PATH. The script must print one valid TCP port. Paseo trusts the external allocator,
so the port may already be bound. portScript takes precedence when both values are present.

Bundled daemon web UI

The user-facing guide for this feature (enabling it, reverse proxy, TLS, tunnels, security) lives at public-docs/web-ui.md. This section is the contributor/build reference: how the artifact is produced, bundled, and excluded from desktop packaging.

The daemon can optionally serve the browser web client from the same HTTP server. This is disabled by default.

Enable it in persistent configuration:

bash

paseo daemon config set features.webUi.enabled true
paseo daemon start

Or set the environment variable:

bash

PASEO_WEB_UI_ENABLED=true paseo daemon run

Or persist it in config.json:

json

{
  "features": {
    "webUi": {
      "enabled": true
    }
  }
}

When enabled, opening the daemon HTTP origin (for example http://localhost:6767/) serves the web app. The same HTTP server continues to serve /api/*, /mcp/*, /public/*, the WebSocket upgrade, and service-proxy routes. Static files load without daemon bearer auth; API and WebSocket calls still enforce auth.

The served app auto-bootstraps a connection to the same origin, so opening http://localhost:6767/ directly usually skips the Add Host step.

Build the artifact for packaging or measurement with:

bash

npm run build:daemon-web-ui

This exports the normal browser web app (not the Electron-flavored desktop renderer) and copies it into packages/server/dist/server/web-ui, precompressing .html, .js, .css, and JSON assets as .br and .gz.

Measured bundle size for a standard Expo web export:

raw: 10.77 MiB
gzip: 2.55 MiB
brotli: 1.93 MiB

The desktop-managed daemon disables the bundled web UI by default (PASEO_WEB_UI_ENABLED=false) because the desktop app already ships the renderer as app-dist. Shipping the same assets again inside @getpaseo/server would duplicate the ~10.8 MiB install. Desktop packaging also excludes node_modules/@getpaseo/server/dist/server/web-ui/** from the packaged app.

Built workspace packages

Package imports resolve through package exports to compiled dist/ output, not sibling src/ files. This is true in local dev and in published packages: the app, daemon, CLI, and SDK consumers should all exercise the same runtime paths.

npm run dev:server builds the server-side workspace packages once, then keeps @getpaseo/protocol and @getpaseo/client fresh with TypeScript watch builds while the daemon runs. If you change protocol schemas or client code outside that watch workflow, rebuild the producer before trusting runtime behavior.

Use the named root build targets instead of remembering workspace dependency chains:

bash

npm run build:client       # protocol -> client
npm run build:server-deps  # highlight -> relay -> protocol -> client
npm run build:server       # server-deps -> server -> cli
npm run build:app-deps     # highlight -> protocol -> client -> expo-two-way-audio

Use npm run build:server whenever you have changed any daemon/server-facing package and need clean cross-package types or runtime behavior.

The app Metro config disables Watchman and uses Metro's node crawler for exports. Keep that invariant unless you have verified production app exports on machines with and without Watchman installed; distro Watchman builds can differ in capabilities and change Metro's crawl behavior.

For tighter loops, you can rebuild a single workspace:

Changed packages/protocol/src/* or packages/client/src/*: npm run build:client.
Changed packages/server/src/*, packages/cli/src/*, packages/relay/src/*, or packages/highlight/src/*: npm run build:server.
Changed app build dependencies: npm run build:app-deps.

Dependency patches

patches/*.patch are applied by scripts/postinstall-patches.mjs on every install. A patch only
runs when its package is actually present, so add the package to that script's patchedPackages
list when you introduce a new patch — otherwise the file sits in patches/ and never applies.
patch-package cannot apply a patch that changed after an earlier version was applied, so the
script removes that package and fails the install; the next npm install reinstalls it clean
with the current patch. Regenerate a patch with npx patch-package after editing node_modules/, and
patch every build the consumers use: Metro resolves the react-native field of a package
(src/*.ts for react-native-svg), while Node and Vitest resolve main/module
(lib/commonjs, lib/module). Patching only lib/ leaves the app bundle unfixed.

ACP provider catalog versions

The in-app ACP provider catalog pins package-runner entries (npx, npm exec,
and uvx) to exact package versions. Run the drift checker regularly — and
before releases — so catalog installs do not sit on stale agent versions:

bash

npm run acp:version-drift        # report stale/non-exact package pins
npm run acp:version-drift:check  # same, exits non-zero on drift
npm run acp:version-drift:update # rewrite catalog pins to latest exact versions

The checker updates only package-runner catalog entries. Providers that use a
preinstalled binary such as opencode acp, cursor-agent acp, or goose acp
are reported as skipped because their versions are owned by the user's local
install.

CLI reference

Use npm run cli to run the in-repo CLI from source (npx tsx packages/cli/src/index.ts). The script wraps the CLI with scripts/dev-home.sh, so it automatically uses this checkout's .dev/paseo-home and dev daemon endpoint unless you pass an explicit override. The globally installed paseo binary on macOS is a symlink into the installed Paseo desktop app, not this checkout — use it to drive the desktop's built-in daemon, but use npm run cli when you want to talk to the CLI you are editing.

Canonical automation uses paseo project create/ls/rename/delete, paseo workspace create/ls/rename/archive, paseo heartbeat create/update/delete, and the full paseo schedule group. MCP heartbeat automation is intentionally smaller: create and delete only. Detach remains an explicit user lifecycle action rather than an agent tool. paseo run --new-workspace local|worktree composes workspace creation with agent creation. The old paseo worktree and paseo run --worktree forms are hidden compatibility aliases.

bash

npm run cli -- ls -a -g              # List all agents globally
npm run cli -- ls -a -g --json       # Same, as JSON
npm run cli -- inspect <id>          # Show detailed agent info
npm run cli -- logs <id>             # View agent timeline
npm run cli -- agent open <id>       # Focus an existing agent in Paseo Desktop
npm run cli -- daemon status         # Check daemon status
npm run cli -- clone owner/repo --dir ~/workspace # Clone GitHub repo and register project

Use the global --host option to point the CLI at a different daemon:

bash

npm run cli -- --host localhost:7777 ls -a
npm run cli -- --host ssh://user@host ls -a

Set PASEO_HOST to use the same target across invocations. An explicit
selector overrides both environment selectors. With both PASEO_HOME and PASEO_HOST set, pass an explicit selector. See CLI target selection.

In an SSH URI, the URL port is the SSH server port. The remote daemon defaults to 127.0.0.1:6767; use ?daemonPort=7777 to override it. The transport runs non-interactively through the local OpenSSH client and never installs, starts, or configures the remote daemon. User-facing setup and troubleshooting live in public-docs/connectivity.md.

Desktop integrations can focus an existing agent without creating one or
sending a message. Use paseo://h/<server-id>/agent/<agent-id>, or run
paseo agent open <agent-id>. The CLI reads the local daemon's server ID by
default; pass --server <server-id> when targeting another server.

Agent state

Agent data lives at:

text

$PASEO_HOME/agents/{cwd-with-dashes}/{agent-id}.json

Find an agent by ID:

bash

find $PASEO_HOME/agents -name "{agent-id}.json"

Find by content:

bash

rg -l "some title text" $PASEO_HOME/agents/

Provider session files

Get the session ID from the agent JSON (persistence.sessionId), then:

Claude:

text

~/.claude/projects/{cwd-with-dashes}/{session-id}.jsonl

Codex:

text

~/.codex/sessions/{YYYY}/{MM}/{DD}/rollout-{timestamp}-{session-id}.jsonl

Testing with Playwright MCP

Point Playwright MCP at the running Expo web target. For root checkout dev, npm run dev:app reserves http://localhost:8081. For Paseo-managed worktree app services, use the service URL or port shown by Paseo for that worktree.

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 breaks state.

App web deploys

packages/app exports a single-page Expo web app and deploys the dist/
directory to Cloudflare Pages with npm run deploy:web --workspace=@getpaseo/app.

PWA install metadata lives in packages/app/public/manifest.json and is linked
from packages/app/public/index.html. Keep the install icons in public/ so
Cloudflare serves them from stable root URLs after expo export.

Do not add service-worker caching casually. Paseo is a live control surface for
agents, and an aggressive service worker can strand installed users on stale web
code. If offline behavior becomes a product requirement, add it deliberately
with an update strategy and test the installed-app upgrade path.

Expo troubleshooting

bash

npx expo-doctor

Diagnoses version mismatches and native module issues.

Typecheck

Always run typecheck after changes:

bash

npm run typecheck

Docker (`docs/docker.md`)

Running Paseo in Docker

Paseo publishes a container image for running the daemon on a server, VM, NAS,
or homelab box. The image also serves the bundled browser web UI, so one
container gives you both the daemon API and a self-hosted UI.

The image source lives in docker/.

How it works

The official image:

builds @getpaseo/server and @getpaseo/cli from source-built workspace tarballs
runs the daemon as the non-root paseo user
listens on 0.0.0.0:6767 inside the container
enables the bundled daemon web UI with PASEO_WEB_UI_ENABLED=true
stores daemon state and agent credentials under /home/paseo
leaves agent CLIs out of the base image

Open the container's HTTP origin, for example http://localhost:6767, to load
the web UI. The served app receives a same-origin connection hint and connects
back to that daemon. Static UI files load without daemon auth; API and
WebSocket requests still require PASEO_PASSWORD when one is configured.

Host-side CLI commands select the container explicitly, for example paseo project ls --host 127.0.0.1:6767. Without an endpoint selector the CLI looks for a local home’s supervisor. Container environment settings are deployment overrides; worker restart preserves them. Your container manager owns full supervisor replacement.

Quick Start

bash

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

Then open:

text

http://localhost:6767

If you set PASEO_PASSWORD, enter the same password when adding the direct
daemon connection in the web UI or another Paseo client.

Docker Compose

Use docker/docker-compose.example.yml:

bash

cp docker/docker-compose.example.yml docker-compose.yml
$EDITOR docker-compose.yml
docker compose up -d

Minimal example:

yaml

services:
  paseo:
    image: ghcr.io/getpaseo/paseo:latest
    restart: unless-stopped
    ports:
      - "6767:6767"
    environment:
      PASEO_PASSWORD: "change-me"
    volumes:
      - ./paseo-home:/home/paseo
      - ./workspace:/workspace

Installing Agents

The base image does not preinstall Claude Code, Codex, OpenCode, Copilot, Pi, or
other agent CLIs. That keeps the default image small and avoids coupling Paseo
releases to third-party agent release cycles.

Create a child image for the agents you use:

dockerfile

FROM ghcr.io/getpaseo/paseo:latest

USER root
RUN npm install @openai/codex @anthropic-ai/claude-code opencode-ai

Build it:

bash

docker build -f Dockerfile -t paseo-with-agents .

Then use image: paseo-with-agents in Compose.

Leave the child image user as root. The base entrypoint uses root only for
first-run directory setup, then drops the daemon and launched agents to the
non-root paseo user.

An example child image is in
docker/Dockerfile.agents.example.

You can also mount credentials from the host or run agent login once inside the
container:

bash

docker exec -it --user paseo paseo codex
docker exec -it --user paseo paseo claude

Agent credentials and config persist in /home/paseo, alongside daemon state.
Provider environment variables such as OPENAI_API_KEY, ANTHROPIC_API_KEY,
OPENAI_BASE_URL, or ANTHROPIC_BASE_URL can be passed through docker run -e
or compose.environment; Paseo passes them to launched agents.

Volumes

Mount	Purpose
`/home/paseo`	Paseo state under `.paseo` plus agent config such as `.codex`, `.claude`
`/workspace`	Code that Paseo and launched agents can read and write

The image defaults:

Variable	Default
`HOME`	`/home/paseo`
`PASEO_HOME`	`/home/paseo/.paseo`
`PASEO_LISTEN`	`0.0.0.0:6767`

If you bind-mount host directories on Linux, make sure the container user can
write them. The built-in paseo user has uid/gid 1000:1000. For a different
host uid/gid, either adjust ownership on the mounted directories or run the
container with Docker's --user / Compose user: option.

Reverse Proxies

When serving Paseo behind a reverse proxy, forward normal HTTP requests and
WebSocket upgrades to the same daemon port.

Caddy example:

caddy

paseo.example.com {
  reverse_proxy 127.0.0.1:6767
}

Nginx example:

nginx

server {
    listen 443 ssl;
    server_name paseo.example.com;

    location / {
        proxy_pass http://127.0.0.1:6767;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

If you reach the daemon by DNS name, set PASEO_HOSTNAMES so host-header
validation allows that name:

yaml

environment:
  PASEO_HOSTNAMES: "paseo.example.com,.lan"

IPs and localhost are allowed by default.

Security

Set PASEO_PASSWORD for any published port or network-reachable deployment.
Prefer HTTPS at the reverse proxy for direct browser access.
Use the official Paseo relay for
untrusted networks or mobile access when you do not want to expose the daemon
port directly.
The container is the isolation boundary for agents. Agents can read and write
whatever you mount into /workspace and whatever credentials you place in
/home/paseo.
The bundled web UI static files are public on the daemon origin. The daemon
API and WebSocket remain protected by password auth when configured.

See SECURITY.md for the daemon trust model.

Building Locally

bash

docker build -f docker/base/Dockerfile -t paseo:local .

To assert the source tree version while building:

bash

docker build \
  --build-arg PASEO_VERSION=0.1.102 \
  -t paseo:0.1.102 \
  -f docker/base/Dockerfile \
  .

The Docker workflow builds the image on pull requests and on main as a
non-publishing check. Stable vX.Y.Z tag pushes publish
ghcr.io/getpaseo/paseo:X.Y.Z and ghcr.io/getpaseo/paseo:latest. Beta tags
publish only the exact prerelease tag, such as
ghcr.io/getpaseo/paseo:0.1.102-beta.1, and do not update latest.

To replace a Docker image in place without rebuilding desktop, APK, or EAS
mobile release artifacts, dispatch the Docker workflow manually instead of
pushing a v* release tag:

bash

gh workflow run docker.yml \
  --ref main \
  -f paseo_version=0.1.102-beta.1 \
  -f publish=true

Manual Docker publishes require an explicit paseo_version. The workflow builds
from the checked-out source tree and publishes only the exact prerelease image
tag for prerelease versions.

The published image is multi-arch for linux/amd64 and linux/arm64.

Troubleshooting

The web UI loads but cannot connect: if PASEO_PASSWORD is set, add a
direct connection with the same password.
403 Host not allowed: set PASEO_HOSTNAMES to the DNS names you use.
Provider not available: install that agent CLI in a child image or mount a
runtime where the binary is on PATH.
Permission errors in /workspace: make the mounted directory writable by
uid/gid 1000:1000, or run the container as the host uid/gid.
Logs: inspect docker logs paseo or
/home/paseo/.paseo/daemon.log inside the container.

The Explorer sidebar and the side pane share panel implementations, but they have different shell
contracts.

Surface	Purpose	Lifecycle
Explorer sidebar	Files and Changes navigation	Cmd+E shows or hides the dedicated dock
Side pane	Ordinary workspace content	Created and closed like any workspace pane
Sheets	Compact look-ups	One tab each, on the app-wide sheet stack

Panel host contract

Every panel registers its supported PaneHost values and presentation. Launchers derive
fixed-target labels and icons from that registration, filter by host, and never substitute one
panel type for another. Tab moves reject unsupported destinations, and placement resolves only to
a compatible pane.

Files and Changes are the Explorer defaults. Their panel manifests mark them as singletons,
so a pane’s + menu omits each while that pane already contains it. Closing one makes its menu
item available again. Other compatible tabs, including agents, terminals, files, and diffs,
can move between Explorer and main panes.
Keep panel implementations independent of either shell. WorkspacePanelHost owns mounting and
retention. The shared Explorer owns its tab rail; its shared frame owns visibility, activity and
close-gesture lifetime. Platform adapters own resizing and inset geometry.
The host keeps three recently used tabs plus modified tabs; unmodified tabs beyond that budget
can remount. Native retained content stays live, while web chat uses its existing deferred Freeze.

Sheets

On compact layouts, files and subagents open in a sheet over the workspace, so the tab switcher
keeps only agents and terminals. A panel kind opts in with compactSheet in its manifest
(packages/app/src/panels/panel-manifest.ts), and the layout store's openTab decides between
sheet and tab, so callers open targets the same way on every layout. Each such sheet holds one
ordinary WorkspaceTab (SheetTab in the store) and is an IsolatedBottomSheetModal like every
other sheet in the app, so it sits on the one app-wide stack: a sheet opened from any sheet, a
subagent chosen from the subagents list included, lands on top of it, and closing the top sheet
(drag, Close, backdrop, or Android Back) uncovers the one below. The list stays open under the
sheet it opened; see menus.md for the row contract.

The store keeps sheetsByWorkspace in opening order and never reorders it, because moving a sheet
remounts its panel. Revealing a target that already has a sheet uncovers that sheet by closing the
ones above it, except ones holding unsaved work, which stay where they are. Opening a sheet as a tab
dismisses the sheets above it, since the tab would sit under them. The stack is not persisted.

Sheets are modal and cover the whole compact workspace, including the header and Explorer. A sheet's header is its drag
handle, because the panel scrolls on its own and content panning would fight it. Its trailing rail
holds icon buttons only (SheetHeaderIconButton): Open as tab is the full-screen glyph beside
Close, so the title keeps its width. The sheets present
from the shared workspace's SheetHostScope, so their panels read the navigator and every
workspace provider an ordinary pane has without a context bridge
(floating-panels.md Gotcha 6).

A sheet holding unsaved work is never implicitly displaced; only its guarded close removes it.
Moving its tab to another host remounts the panel, and the file editor keeps unsaved text in the
mounted view, so the move would drop it. Widening the layout is the known exception: it still moves
the sheet's tab into a pane, and edits the autosave has not started writing are lost.

packages/app/src/workspace-tabs/explorer-sidebar.ts owns show, hide, toggle, and view selection.
One Explorer host stays beside the center column across compact overlays and docks. Keep its
providers and gesture roots at the same React position when width or appearance changes. The
workspace route preserves panel ancestry during appearance updates. Appearance-dependent leaves
subscribe to theme changes; the file editor reconfigures its existing editor theme compartment.
Ordinary leaf routes retain the stack appearance policy.
The shell is outside the workspace split canvas so it divides the full workspace, including the header. It has its own persisted width and resize handle. Main-pane splits
never read or modify that width.

packages/app/src/workspace-tabs/open-supporting-view.ts owns semantic Changes and pull-request
opens. Compact and wide native layouts select the matching workspace tab in Explorer. Desktop Changes opens
follow the shared diff preference. Desktop pull requests use their Main panel, On the side, or
Explorer sidebar setting. Automatic PR discovery follows that preference once per workspace without
interrupting the user's work. Closing the tab opts that workspace out of future automatic opens,
even for a different PR; moving or reordering it remains the user's choice.
Callers request the content and never choose the shell.
The composer Changes pill is a two-stage desktop action: it first reveals Explorer on Changes, then
routes later presses to the working diff through the shared diff preference.

The persisted layout still contains the Explorer pane so tabs survive reloads. The renderer removes
that pane from the workspace split tree and docks it separately. Persisted identifiers retain the
literal "explorer" pane id and explorerPaneIdByWorkspace key for compatibility.

Explorer uses the shared workspace tab row and ordinary tab context menus. Files and Changes
hide their close buttons through the panel manifest; close them from the tab context menu.
Other tabs reveal the close control on hover. Compact layouts show no inline close on any tab,
since a narrow X beside the label is easy to hit by accident; the long-press menu closes it.
Compact tabs also keep their natural width and the rail scrolls as soon as they overflow, while
pointer layouts shrink tabs toward the clickable minimum first. A rail that scrolls never truncates.
The + menu opens compatible panels in the dock, including Agent and terminal profiles. Compact
layouts omit Diff from it because compact Changes shows each file's diff inline.
Web also supports dragging agents and terminals into Explorer.
Bulk-close actions apply only to the dock's tabs. Explorer tabs can be reordered and dragged
between compatible panes, but the dock cannot be split or maximized. Selecting an Explorer tab
does not change workspace focus. Web dragging shares the workspace drag scope; compact layouts
accept only reordering inside the source pane.

Cmd+E shows or hides Explorer without changing its selected view. All layouts use the same
workspace tabs, launcher, and panel host. Below 600 points the shell is the swipeable Explorer
overlay; at 600 points and above it reserves width beside the workspace. Native docking keeps its
touch resize handle. Full workspace splits remain a separate web-only capability.

The dock reserves at least 240 points and the workspace 360. App navigation yields when it cannot
share the remaining width with both. This keeps a portrait tablet from rendering three unusably
narrow columns; widening restores navigation without changing its saved open state.

Compact panel gestures own overlay visibility; the workspace layout owns its tab selection and
contents on every platform. Explicit pane destinations bypass compact sheet placement, so choosing
a panel in Explorer's + menu keeps it there. Ordinary compact file and subagent look-ups still use
the sheet policy. Resolving an existing main tab reveals center immediately; a new file sheet
keeps Explorer underneath and closing the sheet uncovers it. Semantic navigation resolves the
actual destination before revealing it, including deduplicated targets.

Compact overlay selection and saved dock visibility are independent. Folding changes geometry,
not either mode’s visibility intent. Native workspace retention remains one workspace; web retains
up to ten with its existing inactive TTL.

PR discovery belongs to the active workspace: split layouts discover while active, and other
layouts discover while Explorer is active. The rail requests summary status; selected visible PR
content also requests timeline data. Inactive consumers read cached data without request demand.
Discovery uses ordinary PR tabs and their existing once-per-workspace close opt-out.

Side pane

packages/app/src/workspace-tabs/open-beside.ts owns content opened beside the user's work. The
layout store remembers one ordinary pane per workspace. The first side open creates a full-height
right split around the workspace root; later side opens reuse it. Only the split-panes layout
mode opens beside. Compact and single-pane layouts (touch tablets) open the same target in the main
pane, so callers never check whether splits render.

Removing a pane clears its remembered id; a later side open creates a new pane. The last visible
ordinary pane stays when its final tab closes and shows the New launcher. An empty workspace does
not automatically create an agent draft tab; choosing Agent opens one. Explorer cannot replace the
workspace canvas, even when visible. Restoring a saved layout enforces the same rule while preserving Explorer and saved
tab content. There is no hidden side-pane lifecycle.

Placement intent still controls existing tabs:

Mode	New target	Existing target
`pane`	opens in the requested pane	moves to the requested pane
`prefer`	opens in the requested pane	stays where the user placed it
`focused`	opens in the focused pane	focuses it where it already lives
`ambient`	opens in a compatible pane	focuses it where it already lives

Explicit Open to Side uses pane. Implicit opens use prefer, so a preference affects only a
new target and never yanks an existing tab out of a user-selected pane.

Routing preferences

Desktop Settings → Layout → Open location has independent Main panel or On the side choices for
Explorer Files, diffs, chat files, files opened from diffs, and subagents. They default to Main
panel. Mobile ignores them.

Pull requests have a three-way open location: Main panel, On the side, or Explorer sidebar. Explorer
sidebar is the default. Compact layouts always open pull requests in Explorer regardless of this
desktop preference.

Panels request an implicit open through the narrow openPreferredTarget(target, source) pane
contract. Entry points outside panels use openPreferredWorkspaceTarget. Do not branch on a
specific shell inside a panel.

Expo Router (`docs/expo-router.md`)

Expo Router

Paseo's mobile route tree is fragile because Expo Router and React Navigation do
not fail loudly when a nested native route is mounted under the wrong layout. The
usual symptom is a white or blank native screen with no JavaScript crash.

Read this before changing packages/app/src/app, startup routing, remembered
workspace restore, or active workspace selection.

Ownership

Each layout owns only the routes directly inside its directory.

The root layout registers h/[serverId].
The root layout does not register host leaf routes such as
h/[serverId]/workspace/[workspaceId], h/[serverId]/open-project, or
h/[serverId]/index.
packages/app/src/app/h/[serverId]/_layout.tsx owns the host leaves with
relative screen names: index, workspace/[workspaceId]/index,
agent/[agentId], sessions, open-project, settings,
plugin/[pluginId]/[surfaceId], and
plugin/[pluginId]/[contributionKind]/[contributionId].

Expo Router warns with [Layout children]: No route named ... when a layout
registers grandchildren. Treat that warning as a route-tree bug. On native, that
shape can leave a nested index route mounted without its local dynamic params and
render a blank screen.

Startup

The root / route chooses a host boundary. It does not jump directly into a host
leaf.

Good: / -> /h/[serverId]
Bad: / -> /h/[serverId]/workspace/[workspaceId]

/h/[serverId] is the host home route. The host index restores the last
remembered workspace for that host after the remembered selection has hydrated
and the workspace has not been proven missing. If there is no restorable
workspace, it goes to global /open-project.

This restore is based on the last navigated workspace, not current connection
status. Do not redirect to another online host just because the remembered host
is still connecting or offline; the workspace screen owns that offline/loading
state.

This split is deliberate. The host layout must mount first so native local
dynamic params exist before any nested workspace leaf is selected.

Error Recovery

The root error boundary lives above ExpoRoot in src/root-app.tsx. Reload
remounts the router at /open-project, preserving saved workspace layouts and
the remembered selection. Do not move the boundary inside the root layout:
catching a render error there unmounts the navigator, so the recovery button
cannot reliably dispatch a navigation reset. Starting recovery at / would
restore the same workspace and could repeat the crash.

App-Wide Route Hops

When app-wide routes such as /new, /settings, or /sessions navigate back
into a host workspace, use navigateToWorkspace(). Do not make the caller
branch on its current route.

Pass only serverId and workspaceId for normal attention-aware navigation.
When the action names a specific tab, pass it as target; that explicit choice
is authoritative. Callers should not choose between separate route and tab
navigation APIs.

The root stack owns h/[serverId]; the host stack owns
workspace/[workspaceId]/index. Repeated global-route hops must POP_TO the
root host route and pass the nested workspace screen when a host route is
already mounted, or Expo Router can append extra hidden workspace deck entries.
The workspace navigation helper inspects the mounted navigation state to make
that decision; if no host route is mounted yet, it falls back to ordinary route
navigation. Both paths wait for the root navigation container to be ready. The
workspace navigation owner keeps the latest pending intent across ref
re-registration and applies it on the container's ready event; routes must not
add their own readiness retries.

Those hidden entries are not harmless: composer floating panels can measure
against the wrong deck and disappear offscreen. Follow the
retained panel measurement rules
for components that intentionally remain mounted while hidden.

Hidden host routes may keep their local params while an app-wide route is
foregrounded. Active-workspace observers must prefer the current pathname and
only use local param fallback during cold mount (/ or empty pathname), or a
hidden workspace can overwrite the remembered workspace before Settings or
History returns.

Plugin settings use the distinct settings/hosts/[serverId]/plugins/[pluginId]/[screenId] leaf;
Back returns to that host's Plugins page.

Settings detail routes are separate siblings on purpose. Keep
settings/[section], the host routes, the projects index, and project detail as
distinct route names. router.dismissTo() ultimately matches stack entries by
route name. A single catch-all Settings route would make project detail and the
projects index the same route; Back would update params in place and leave a
phantom detail entry underneath. The host routes also stay outside the
store-ready protected group so a cold host deep link can survive daemon startup.
Do not collapse this topology with a catch-all, getId, or
dangerouslySingular workaround.

Agent Targets

Notifications and agent URLs name a host and agent. Both use
navigateToAgent(), which reads the agent's current workspace from the store
or routes through /h/[serverId]/agent/[agentId]. The agent route waits for
the named host, demands its directory, and waits for workspace and layout
hydration before opening the tab. Keep the stable agent URL free of a workspace
hint. Notifications owns tap delivery and native lifecycle
constraints.

When a workspace target cannot open yet, navigateToWorkspace() records a
pending open in the layout model under that host and workspace key. The owning
workspace screen consumes it once after hydration. Archived-workspace recovery
reads the same pending target, so startup redirects cannot discard it and a
retained screen cannot consume another workspace's request.

Legacy ?open= links seed this model state at the matched route boundary and
then lose the query parameter. Internal navigation does not use the query as a
handoff. Read matched route params locally; global search params let retained
workspace screens observe requests for other workspaces.

Params

Required dynamic params belong to the matched route.

Do not paper over missing required params by reading global params in the leaf.
If useLocalSearchParams() misses a required param, fix layout ownership or the
startup route shape.

Use the host route context for host-owned leaves that need the host id after
h/[serverId]/_layout.tsx has matched. Do not make a leaf recover from an
unmatched tree by guessing from global state.

App Directory

Keep non-route modules out of src/app. Expo Router treats ordinary .ts and
.tsx files there as routes, which produces missing the required default export warnings and pollutes the route tree.

Put shared route policy in src/navigation, src/utils, stores, or another
non-route directory.

Native Stack

Keep workspace identity and retention outside native-stack getId and
dangerouslySingular. Expo Router maps dangerouslySingular to React
Navigation getId, and getId has broken Android native-stack/Fabric by
reordering an already-mounted workspace screen.

Use ThemedStack from packages/app/src/navigation/themed-stack.tsx for every
Expo Router stack. React Navigation otherwise paints each native stack screen
with its light default background. A screen-level wrapper can hide that surface
while settled, but Android may expose it for one frame when navigation crosses
from a nested stack to its parent stack. This is especially visible when an
app-wide route such as /new opens from a dark workspace.

Do not read the active theme with useUnistyles() in a layout to build
screenOptions. ThemedStack keeps that third-party prop theme-reactive through
a small withUnistyles boundary without subscribing the route tree itself to
every Unistyles runtime update.

Navigators keep their identity across appearance changes. ThemedStack remounts
each ordinary screen's content below the native stack when appearance tokens change.
Workspace screens own retained panel lifetimes and update appearance at their
leaves through screenOwnedAppearance (Explorer). A
keyed wrapper above a stack remounts the stack itself, and Android crashes when
that happens while a FragmentManager transaction is running, which settings
hydration at startup makes likely. A screen that mounts a nested navigator (the
root stack's h/[serverId]) is passed in nestedNavigatorScreens so the nested
stack owns its own screens. See unistyles.md.

Regression Shape

Pure helper tests are useful but not enough. The failure mode here is native
route-tree state, so a real regression should launch native with seeded persisted
state:

Seed paseo:last-workspace-route-selection with a valid
{ serverId, workspaceId }.
Launch the native app cold.
Assert a real screen is visible, not the blank tree.
Assert no [Layout children] warning appears.

The pure policy tests should still enforce the boundary split:

root startup with a saved workspace returns /h/[serverId];
host index with the same saved workspace returns
/h/[serverId]/workspace/[workspaceId];
host index with no restorable workspace returns /open-project.

Checklist

Before landing route changes:

Did you change packages/app/src/app? Re-read this file.
Did you touch remembered workspace restore? Keep root on /h/[serverId].
Did a route return to a workspace? Use navigateToWorkspace() and pass a
target when the action names a specific tab.
Did you add a route? Register it in the layout that directly owns it.
Did useLocalSearchParams() lose a required param? Fix the route tree.
Did native show a blank screen without a crash? Suspect route ownership
before stores, themes, or rendering.

File Icons (`docs/file-icons.md`)

File Icons

The file explorer uses colored SVG icons from material-icon-theme (installed as a dev dependency in packages/app).

How it works

Two files:

packages/app/src/components/material-file-icons.ts — the vendor table. SVG_ICONS maps icon
names to SVG strings copied verbatim from the theme, EXTENSION_TO_ICON maps extensions to icon
names, and getRawFileIconSvg(fileName) looks one up with a generic fallback. Keep it a faithful
copy so re-copying an icon stays a mechanical edit.
packages/app/src/components/file-icon-svg.ts — getFileIconSvg(fileName), the only thing
anyone should import. It desaturates the vendor colours and caches the result.

Render with <MaterialFileIcon fileName size /> rather than reaching for SvgXml yourself.

Why the colours are toned down

material-icon-theme picks its palette for VS Code's file tree, where the icon is the only colour on
the row. Ours share rows with status dots, diff stats, and check badges, and a column of them at
full chroma is the loudest thing in the panel.

Every hex in the SVG is pulled toward neutral at the same perceived lightness (desaturateHexColor
in packages/app/src/utils/color.ts, OKLab — scaling HSL saturation instead would darken the
yellows and barely touch the blues). Hue survives, which is the only part of an icon's colour that
carries meaning at 16pt.

ICON_CHROMA in file-icon-svg.ts is the single knob. Move it; do not add per-icon overrides, or
we are back to hand-picking 53 colours.

Adding a new icon

Find the icon name in the material-icon-theme manifest:

bash

node -e "
const m = require('./node_modules/material-icon-theme/dist/material-icons.json');
console.log('fileExtensions:', m.fileExtensions['YOUR_EXT']);
console.log('languageIds:', m.languageIds['YOUR_LANG']);
"

Verify the SVG exists:

bash

cat node_modules/material-icon-theme/icons/ICON_NAME.svg

Add two things to material-file-icons.ts:
- The SVG string in SVG_ICONS:
  ts
```
"icon_name": `<svg ...>...</svg>`,
```
- The extension mapping in EXTENSION_TO_ICON:
  ts
```
"ext": "icon_name",
```
Run npm run typecheck to verify.

Currently included icons

53 unique icons covering these extensions:

Extension(s)	Icon
`ts`	typescript
`tsx`	react_ts
`js`	javascript
`jsx`	react
`py`	python
`go`	go
`rs`	rust
`rb`	ruby
`java`	java
`kt`	kotlin
`c`	c
`cpp`	cpp
`h`	h
`hpp`	hpp
`cs`	csharp
`swift`	swift
`dart`	dart
`ex`, `exs`	elixir
`erl`	erlang
`hs`	haskell
`clj`	clojure
`scala`	scala
`ml`	ocaml
`r`	r
`lua`	lua
`zig`	zig
`nix`	nix
`php`	php
`html`	html
`css`	css
`scss`	sass
`less`	less
`json`	json
`yml`, `yaml`	yaml
`xml`	xml
`toml`	toml
`md`, `markdown`	markdown
`sql`	database
`graphql`, `gql`	graphql
`sh`, `bash`	console
`tf`	terraform
`hcl`	hcl
`vue`	vue
`svelte`	svelte
`astro`	astro
`wasm`	webassembly
`svg`	svg
`png`, `jpg`, `jpeg`, `gif`, `webp`, `ico`	image
`txt`	document
`conf`, `cfg`, `ini`	settings
`lock`	lock
`groovy`	groovy
`gradle`	gradle

File Observation (`docs/file-observation.md`)

File observation

Use packages/server/src/server/file-observer for recursive filesystem observation. Create one observer service at the owning service boundary, subscribe roots through it, and close it during owner shutdown. Keep platform watchers, directory discovery, exclusion reconciliation, event batching, failure cleanup, diagnostics, and teardown inside the module. A consumer supplies a root and excluded subtrees; it must not branch on the platform or manage child watchers.

Do not replace the Linux implementation with fs.watch({ recursive: true }). Node 22 implements Linux recursion in JavaScript by walking the tree and watching every file and directory. Paseo's directory-only Linux watcher already exhausted resources before ignored-tree pruning and a watcher cap were added in #794.

Closing an observation must remain safe after its root is renamed or removed. Workspace archive removes owned worktrees while releasing observation references, so teardown cannot assume the watched path still exists.

unsubscribe() is an awaited barrier. Once it resolves, no scan, reconciliation, queued event, native handle, or callback may remain. updateIgnore() is the equivalent barrier for excluded paths: events queued below a newly excluded root cannot be delivered after it resolves. Treat path disappearance while scanning, attaching, or receiving a watcher error as rename/archive churn. Surface permission and resource errors so WorkspaceGit can enter bounded polling.

Linux topology repair is trailing-debounced and scoped to the renamed path. A file rename needs one classification stat; a new or moved directory scans only its subtree. Full-tree scans are reserved for startup and ignore-set replacement. The initial Linux scan conservatively emits existing files discovered before their directory watcher was installed; WorkspaceGit batches these into one refresh. Benchmark this startup cost with pre-populated trees.

Windows and macOS use one native recursive watcher plus an ignored-pruned, directory-indexed inventory. Native events deliver immediately. Named events trigger serialized shallow scans of their parent directories; known directory events also reconcile that subtree. This recovers concrete create and delete paths omitted by coalescing without walking the whole root for each edit. Classification is admission-controlled to 32 concurrent fs.stat calls, since fs.stat runs on the libuv threadpool the whole daemon shares. Startup and exclusion changes use an awaited full inventory barrier. Activity arms a full safety audit 30 seconds after it settles, with a 30-second minimum interval and a five-minute starvation bound; pathless native events also trigger an immediate shallow root scan. Observation fails into polling rather than retaining more than 250,000 file and directory entries per root. A repository that large is also expensive to poll, so degraded polling doubles its gap from 5 seconds to a 60-second ceiling while the workspace snapshot comes back unchanged, and resets to 5 seconds on the first change. Explicit reads still force a refresh; the ceiling only bounds how long an edit made outside Paseo stays undiscovered.

Read aggregate health from the owning observer service. Runtime metrics include active observations, native handles, tracked native files, pending events and immediate reconciliation work, scoped and full reconciliation activity and latency, and failure counts. nativeTrackedFileCount and other per-file counters are native-backend diagnostics only — the Linux backend keeps no per-file inventory and reports zero — so a cross-platform assertion belongs on delivered events, not those counters. Delayed safety audits do not count as pending work. Closing the service releases every subscription and clears its diagnostics. Do not add path lists, watcher handles, or platform-specific controls to this interface.

Git owns Git-ignore evaluation. The observer accepts absolute excluded roots and applies updates without replacing the observation or exposing its watcher topology. This keeps tracked files inside otherwise ignored directories observable and keeps Git policy out of the filesystem module.

Workspace Git verifies each repository metadata subscription with a one-shot canary inside the Git directory. If the event does not round-trip through the subscription callback, treat the watcher as unavailable and enter degraded polling. Refresh working-tree Git-ignore exclusions from ignore-file events, newly observed directories, and watcher recovery, never from a healthy-watcher timer. git ls-files reports an ignored directory only once it exists, so new directory topology is a trigger in its own right; the refresh is edge-triggered per directory and debounced so a dependency install collapses into a couple of Git runs.

The real-filesystem contracts and daemon auto-archive lifecycle run in the normal server test suite. Use the scripts only for manual performance and soak work: npm run measure:file-observer --workspace=@getpaseo/server measures burst and sustained-create behavior, and npm run repro:file-observer-teardown --workspace=@getpaseo/server runs the teardown soak.

Floating Panels (`docs/floating-panels.md`)

Floating Panels

Anchored popovers — tooltips, hover cards, dropdowns, autocompletes — that visually
float above an anchor element on iOS, Android, and web. This doc captures the
non-obvious traps. It is not a tutorial; it assumes you have seen the
canonical files and are trying to add or change one.

Canonical files

File	Use case
`components/ui/combobox.tsx`	Anchored picker with search; mobile falls back to bottom sheet
`components/ui/tooltip.tsx`	Non-interactive hover/long-press tooltip
`components/ui/hover-card.tsx`	Desktop-web hover card the pointer can move onto; Portal
`components/ui/autocomplete-popover.tsx`	Slash-command autocomplete anchored to the focused composer input

Each handles a different mix of concerns: combobox owns input focus, tooltip is
non-interactive, hover-card is web-only desktop, autocomplete keeps the composer
input focused while its scrollable list lives in a Portal. There is no shared
"floating panel" primitive yet — when a fifth use case shows up we can revisit;
until then prefer copying the closest file and trimming.

Combobox desktop popovers are never narrower than their trigger, and they grow
with content up to a ceiling that is never below the trigger:

const floor = Math.max(desktopMinWidth ?? 0, referenceWidth ?? 200);
const frameStyle = { minWidth: floor, maxWidth: Math.max(400, floor) };

desktopMinWidth is an explicit floor-raiser. It does not cap width, and the
trigger still wins when it is wider. Changing this default requires re-verifying
every consumer listed here.

Consumers: composer/agent-controls/mode-control.tsx,
composer/agent-controls/index.tsx, composer/index.tsx,
components/combined-model-selector.tsx, components/hosts/host-picker.tsx
(including components/hosts/host-filter.tsx), components/branch-switcher.tsx,
components/left-sidebar.tsx, components/ui/select-field.tsx (schedule form),
screens/new-workspace-screen.tsx plus screens/new-workspace/project-picker.ts,
components/import-session-sheet.tsx, screens/workspace/workspace-screen.tsx,
screens/settings-screen.tsx, and screens/project-settings-screen.tsx.

Gotcha 1 — Android touch hit-test by parent bounds

On Android, a child View whose bounds fall outside its parent's bounds renders
correctly (with overflow: visible, the default) but does not receive touch
events. ViewGroup.dispatchTouchEvent filters touches by the parent's hit
rect first, then iterates children. A touch in the overflowing region never
reaches the parent, let alone the child. iOS and web do not share this rule —
iOS hit-test descends into overflowing children, web uses standard CSS pointer
events. This is the bug that put autocomplete on this path: the popover was
positioned bottom: 100% of its parent and worked on iOS/web for months;
Android touches sailed straight through to the chat scroll view behind it.

Two escape hatches in the codebase:

Modal (combobox, dropdown menu and tooltip on native) — opens a new Android window, so
hit-testing starts fresh in that window. If its children use gesture-handler,
the Modal owner must wrap its content in a full-height GestureHandlerRootView:
the app's root does not span Android windows. React context alone does not
establish a native gesture root. Side effect: a Modal opening on
Android can detach the IME from an underlying TextInput. Fine for combobox
(it has its own input) and tooltip (no input). Not fine for autocomplete
(the composer's input must stay focused so the user keeps typing).
`` from @gorhom/portal (hover-card, autocomplete-popover) —
hoists the React subtree to a fixed mount point whose bounds cover the
screen. Same window, same IME, hit-test works because the new parent is
full-screen. This is the right default when you must keep IME attachment.
Choose the host by layer: app-global overlays use the root host; content
overlays can use the current FloatingPanelPortalHost so sliding sidebars
cover them.

Choose Modal vs Portal by whether the underlying input can lose its keyboard.

On web, dropdown menus render into the shared overlay-root, not React Native
Web's <Modal>/<dialog>. A browser top-layer dialog always paints above
ordinary portals regardless of z-index, which would hide app toasts and
tooltips behind the menu. The shared overlay scale keeps menus below toasts and
lets tooltip portals paint above both.

The shared overlay scale is relative for interactive surfaces: a base floating
panel is below a base modal, while a floating panel rendered from inside a modal
inherits that modal's layer and paints above it. Wrap portal content in
OverlayLayerProvider; do not assign one global menu z-index. Desktop web
comboboxes must use overlay-root too. Rendering them through React Native
Web's <Modal> puts them in the browser top layer, where no ordinary modal
portal can cover them.

Painting and keyboard ownership use the same relative layer model. Register
desktop modal, combobox, and dropdown focus scopes with useWebOverlayRegistration; the
highest painted scope alone receives overlay keys, traps focus, and restores
focus when it closes. Hover cards register with manageFocus={false}: they claim overlay keys without moving or trapping focus on pointer hover. Do not add component-local global Escape listeners: two
stacked overlays would both close on one keypress.

If an overlay is rendered by a global host rather than beneath its opener in
the React tree, carry the opener's current layer through the host store and
restore it with OverlayLayerProvider. Otherwise painting and keyboard
ownership silently reset at the app root. When the opener is a global keyboard
action and has no component context to carry, resolve the host layer with
useGlobalWebOverlayLayer on its closed-to-open transition. It captures the
current top registered layer before the new host joins the stack; do not give a
global dialog a fixed root-derived modal layer.

Gotcha 2 — Portal breaks lifecycle and coordinate-system inheritance

A Portal escapes Android's hit-test, but it also escapes two things you were
quietly relying on:

Lifecycle. The portal'd subtree mounts at the app root, not inside your
component's natural ancestor chain. When the user navigates away, your
component may stay mounted (offscreen, in a tab) — the popover stays with it.
Gate visible on a screen-focus signal. For panes inside agent-panel, the
isPaneFocused prop already exists and flips on pane switches; pass
visible={isYourOwnVisible && isPaneFocused}.
Transforms. KeyboardShiftProvider owns the canonical keyboard shift
SharedValue, and useKeyboardShiftStyle() only adapts that value into
translate/padding styles. The composer and chat content must both read that
provider-owned value. A portal'd popover is outside the composer tree — it
does not get that transform unless you apply it yourself.
Layering. The default root host renders after app content, so it sits
above compact sidebars. Content overlays that must sit below sidebars should
use the current FloatingPanelPortalHost.
Coordinate systems. measureInWindow gives window coordinates. A Portal
renders inside its host, not necessarily at window origin. Position anchored
content relative to the host: anchorRect - hostRect. This is what
measureFloatingPanelPortalHost() is for.
React context. @gorhom/portal is not a React portal — a real one keeps
context, this one does not. It stores the element and the host renders it, so
context resolves at the host's position. Everything provided between
PortalProvider in app/_layout.tsx and your sheet is invisible inside it.
This is why app-wide providers wrap PortalProvider rather than the reverse.

The fix for transforms is Gotcha 3. The fix for context is Gotcha 7.

Gotcha 3 — Keyboard layout and portal anchors

composer/dock owns the stationary viewport, bottom-anchored surface, composer
capacity, and keyboard motion for chat, workspace draft tabs, and New workspace.
Render <ComposerDock>{contentAbove}{composer}</ComposerDock> below the header.
The optional third child is an overlay that moves with the surface. New workspace
uses centered for its existing desktop/tablet form. Hosts never reserve keyboard
space or translate the composer themselves. Put the dismiss surface behind content
as a sibling, with pointerEvents="box-none" on its content wrapper. A Pressable
ancestor takes the JS responder on idle Android Fabric and intercepts the stream's
MOVE events before its native scroll view reaches touch slop. Streaming can hide
this failure by delaying the responder grant. Native scroll views retain their own
tap-to-dismiss behavior; unclaimed empty-space taps reach the dismiss sibling.
On iOS, decorative form containers also need box-none (and inert titles/spacers
need none); otherwise their empty padding blocks hit testing of that sibling.
The shared screen header uses the same dismiss surface. Keep the
header escape available when a capped draft clips all content above it, since
iPhone has no system keyboard-dismiss button. Child controls keep their touches,
and the stream keeps its existing flick-to-dismiss gesture.

The dock's private viewport and capacity model are extracted from chat. The
app-wide @/keyboard/shift module owns shared motion for the dock, portals, streams,
terminal, explorer, and dialogs. Import only its public entry point: the provider,
shift hooks, shift style, translate view, settled stream inset, and explorer padding
policy. Its contexts and reconciliation stay private. Keep KeyboardShiftProvider
at its root mount point outside the portal host when changing dock hosts.

KeyboardTranslateView owns visual keyboard motion inside @/keyboard/shift. Android uses the
controller's Reanimated signal. iOS uses its native-driver Animated.event
signal because the stock iOS Reanimated value changes at move start, while
writing a replacement Reanimated value every frame interrupts UIKit's hide
animation. Keep this platform choice inside the keyboard module's private platform-specific translate files.

ComposerDock always keeps the surface at full height and wraps it in
KeyboardTranslateView. The panel root clips it at the header edge, so rows
slide under the header on open and out from under it on close. Do not swap the
dock to keyboard padding at rest. Changing its height creates either a blank
band or a paused transition when the inverted list updates its viewport.

Do not animate a layout prop through the keyboard transition. On Android
Fabric, each animated layout update clones the shadow tree and runs Yoga over
the dock subtree. This measured about 10 ms per frame on the emulator and the
mounted layouts arrived in bursts every 2–4 frames. A transform does not dirty
layout. Preserve the translated dock's history scroll range with a far-end
content inset on the inverted stream list. Update that inset only when keyboard
motion settles; never drive it per frame.

The translated dock's height is not the composer's available height. Bound the
composer against the stationary space below the header inside
composer/dock, including its controls and attachments. Reserve the
keyboard destination at move start on the UI thread. Waiting for a settled JS
update lets a long draft disappear behind the header during opening. This is a
boundary-time layout change, not an animated layout prop. Keep the input's
native intrinsic sizing and internal scrolling. Keep the editing input's
defaultValue current on every edit: Fabric re-measures the Android input from
the JS text whenever its frame changed, so a stale prop inflates or collapses
the input (see packages/app/src/components/ui/text-input/text-input.native.tsx).

Closing the keyboard moves the composer; it does not enlarge its capacity. The
viewport keeps the last keyboard reservation until the next opening replaces
it, so a capped draft keeps one height through every keyboard transition
instead of expanding on close and shrinking again on open.

Fullscreen is a layout mode of the dock, not a second editor. ComposerDock fullscreen fills the stationary viewport with the composer slot over the
still-mounted content, paints its own surface under the safe areas, and turns
the surface translation off. The composer's single tree keeps the editing
surface at the same position in both modes, so the mounted editor, its native
buffer, selection, and focus survive the toggle and Send's clear always reaches
the live input. A viewport crossing the compact breakpoint still remounts it:
the app shell swaps its gesture wrapper and the workspace screen
mounts tabs in different trees, so every screen below remounts. The draft owner
restores the text and the editing session restores the caret. Focus restoration
is limited to mouse-driven UIs, using the same fine-pointer policy as autofocus.
New workspace keys its sessions by draft in the app-level store for the same
reason. The centered form honors fullscreen by style alone: no centering, no
translation, setup fields hidden, slot filling the stationary viewport. The
global exit action (Escape, hardware back) is registered only for the active
composer: a retained tab keeps its fullscreen editor mounted while hidden, the
sheet suspends pane focus, and the composer gives up input from the moment the
user asks for the compact agent list or explorer, before the panel's motion
settles. Pane focus itself stays put under those panels: the agent panel reads
it as "the user is in this chat" for attention clearing, and opening the agent
list must not clear the attention it shows. On mouse-driven UIs, focus restoration
follows pane focus, not the active composer. Keying it on the active composer
made sidebar dismissal look like a hidden-tab blur and refocused on close.
Native and touch-web navigation must not replay old editor focus, including
when blur arrives after pane deactivation or the editor unmounts before blur.
Fullscreen toggles keep the editor mounted and need no focus restoration.
The band beside the inline editor where the fullscreen glyph sits is the input's
own right padding, so a tap anywhere in it focuses the editor whether or not the
glyph shows. On web the slot is a fixed box over the visible viewport, which is
also what lets a zoomed mobile page pan under it. Inside the slot, ComposerFullscreenBody reserves the keyboard
height as a bottom margin at move start and end (boundary-time, like the
capacity reservation) while ComposerFullscreenFooter rides the keyboard per
frame with KeyboardTranslateView, so Send lands on the keyboard without a gap
and without animating the editor's height. The screen that owns the chrome
unmounts it: the workspace screen reads useComposerTabFullscreen for the
active tab and New workspace reads the mounted composer's session. Hosts that
render the dock pass the same ComposerEditingSession to the Composer so the
dock, chrome, and editor agree on one fullscreen state. Escape (web overlay
registration, focus untouched) and the Android back button leave fullscreen.

Keep setup fields out of the composer's shrink chain. New workspace supplies its
setup fields as the first dock child so they move up under the header as the draft
grows. Putting the fields and composer in one bounded, shrinkable column made
Yoga split the shortage between them: rows vanished behind the composer while
the input lost lines at the same time. Keep that separation inside the dock,
shared by every phone host. The centered tablet form caps the complete block
for header clearance, but reserves the composer's own capped height before
shrinking the setup scroll view. The form must not take editing space from the
composer.

Move the stream and composer together through ComposerDock. Do not translate
them independently.

KeyboardShiftProvider owns the normalized shift used for settled insets and
portal geometry, plus the isMoving worklet value. It reconciles native
animation-end events because the controller can retain a nonzero value after
the keyboard closes.

Measure portal anchors while the dock is at rest. If a popover opens during
motion, re-measure when isMoving settles. measureInWindow includes the
dock's current layout and transform. Snapshot the shift at measurement time and
apply only the subsequent shift delta to the animated bottom. Adding the full
shift moves the portal twice and can place it over the composer controls.

The provider also reconciles iOS from the controller's native onEnd event.
The controller's stock iOS shared values update at move start and during an
interactive move, but not at the terminal event, so JS contention can otherwise
leave the last height/progress pair stuck in either the open or closed state.
Keep that terminal reconciliation on the UI thread; a later focus or blur must
not be required to repair the offset.

Gotcha 4 — Host-relative positioning before platform offsets

The generic anchored-overlay rule is:

Measure the anchor with measureInWindow.
Measure the Portal host with measureFloatingPanelPortalHost(hostName).
Position with anchor coordinates relative to the host:

left = anchorRect.x - hostRect.x;
bottom = hostRect.height - (anchorRect.y - hostRect.y) + offset;

Do this before adding any platform offset. The app draws edge-to-edge on Android, so
measureInWindow, touch pageY, and a full-screen Modal all share one coordinate
space that starts at the screen top. Do not add StatusBar.currentHeight to an anchor:
React Native 0.86 stopped subtracting the status bar from window coordinates under
edge-to-edge, and the old compensation now lands every menu, tooltip, and context menu
one status bar below its trigger.

Gotcha 5 — The two-measurement flash

If your popover needs top (or left) computed from both:

the anchor's screen position (anchorRect from measureInWindow), and
the popover's own size (contentSize from onLayout),

then a naïve implementation will flash through three positions on every open:

Frame 1 — render with top: -9999 (or any placeholder) while waiting
for either measurement. Wrapper has no width, so the inner content lays
out at its natural (often narrow) intrinsic width.
Frame 2 — anchorRect lands. Wrapper now has width: anchorRect.width.
But the stale onLayout from frame 1 has already set contentSize to the
narrow-width dimensions. top = anchorRect.y - wrongHeight - gap — visible
at the wrong spot.
Frame 3 — real onLayout fires with the correct width. contentSize
updates. Position snaps to the right place.

The visible jump in frame 2 is the flash. Two pieces solve it, and you need
both:

Do not mount the floating content until anchorRect is set. Return
null until then. This prevents the bad-width onLayout from happening at
all.
Once anchorRect is set but contentSize isn't, render the wrapper with
the final width but opacity: 0. The first visible paint is at the
correct position. This is the combobox pattern —
shouldHideDesktopContent at combobox.tsx:481, 876. Do not use
top: -9999 as the placeholder; the layout work still happens at -9999 and
any subsequent state-flash is visible when you flip back.

The "render invisible to measure, then reveal" pattern is the canonical
solution to chicken-and-egg positioning in this codebase. Reach for it before
anything fancier.

Gotcha 6 — Bottom sheet refs are not lifecycle truth

@gorhom/bottom-sheet modals churn their imperative ref while presenting and
dismissing. Do not treat ref != null as permission to call present(), and do
not treat ref == null as the sheet being closed. The user-visible lifecycle is
the desired visible prop plus the sheet callbacks (onChange(-1),
onDismiss).

If a user closes a sheet with the backdrop or a pan gesture, the sheet may detach
and reattach before React state has acknowledged visible=false. Re-presenting
on that attach races Gorhom's dismiss path and leaves the modal unable to reopen.
Track an explicit phase (closed / presenting / presented / dismissing) and
ignore ref churn while dismissing.

Do not treat onChange(-1) as a close by itself. In a stacked
BottomSheetModal, -1 can also mean the sheet is temporarily hidden under
another pushed sheet. Close React state from onDismiss; use onChange only to
track phase.

All sheets use the app-wide Gorhom modal provider through IsolatedBottomSheetModal, with no
exceptions: one stack means a sheet opened from any sheet lands on top of it and uncovers it on
close. This includes native centered dialogs: separate React Native Modals cannot present a
root-owned sibling dialog over an existing iOS presenter. A sheet that must draw inside a subtree
(the sheet tabs draw inside the compact workspace column so their
panels read the workspace providers) presents from inside a SheetHostScope, which moves the
portal host and container measurement while the sheet still joins the same stack. That export is
what patches/@gorhom+bottom-sheet+*.patch adds.

A sheet whose owner may veto the close (unsaved work) passes enableDismissOnClose={false}. Every
close path then parks the sheet at index -1 with its content mounted; the owner hears
onChange(-1), runs its guard, and either snaps back to 0 or drops its state, which unmounts the
sheet and takes it off the stack. Calling dismiss() on such a sheet bypasses the guard and
unmounts it, so its backdrop and Back press call close().

The wrapper must give Gorhom an object ref. Gorhom accepts a callback ref at the React boundary
but stores it in the modal queue and later reads .current; provider dismissal, replacement,
and restoration then silently do nothing. Callers may use callback refs on the wrapper, which
forwards commands to the current Gorhom handle.

Request a backdrop with backdropOpacity; do not install a caller-owned backdrop. On web,
Gorhom's default backdrop closes its own sheet, even when another modal is above it. Its animated
pointer-event changes can expose a lower backdrop during a transition. The shared web backdrop
keeps its press target until portal teardown and asks the provider to dismiss the top modal
(a guarded sheet closes itself instead, see above). Gorhom's presentation queue remains the
authority; backdrop mount order is irrelevant. Native retains Gorhom's gesture backdrop and the
same push/replace presentation semantics.

Gotcha 7 — A sheet cannot read context from its call site

React cannot copy contexts reflectively, so the only way across the teleport in
Gotcha 2 is to render the providers a second time, with values captured on the
near side where they are still readable. IsolatedBottomSheetModal takes a
contextBridge for exactly that:

tsx

const contextBridge = useCallback<ContextBridge>(
  (content) => <ThingContext.Provider value={thing}>{content}</ThingContext.Provider>,
  [thing],
);

The prop is required, and null is a real answer. A sheet whose content
needs nothing local should have to say so, because the failure mode is silent
until someone adds a useContext deep inside and it throws on device only —
never on web, where the desktop path uses a real portal. menu-surface.tsx
bridges the menu's two contexts; the rest pass null.

Wrapping providers around the modal does nothing. They land on the wrong side.

Recipe for a new anchored panel

Before you write a new one, ask:

Can the underlying input lose its keyboard? If yes, use Modal (simpler).
If no, use Portal.
Does the panel need to dismiss on screen change? Almost always yes —
gate visible on an upstream focus prop (isPaneFocused or similar).
Is the panel rendered in a Portal host? Measure the host too. Never use
raw window coordinates as local Portal coordinates.
Does the panel sit above something that moves with the keyboard? If
yes, slave a Reanimated transform to the same SharedValue (Gotcha 3).
If no, you can probably skip the transform entirely.
Will the panel's content height vary? If yes, you need both
anchorRect and contentSize for positioning → apply Gotcha 5 (return
null until anchor, then opacity-0 until contentSize). If no — content has
a known fixed max height — you might be able to use bottom-anchored
positioning (bottom: windowHeight - anchor.y + gap) and skip the
contentSize round-trip entirely. But only if the height is genuinely
bounded. Verify before you commit.

Then copy the closest canonical file and trim.

Building a menu rather than a bare panel? Don't. Use the menu engine — it already solves
everything above, plus submenus, sheets, and hover intent. See menus.md.

Forge Providers (`docs/forge-providers.md`)

Adding a Git Forge to Paseo

Paseo's forge layer is a registry/manifest system. A forge is a runtime concern:
shared protocol messages carry neutral/open facts, the server adapter owns
behavior, and the app owns bundled presentation/runtime interpretation.

The maintainer litmus test is the rule of thumb:

Adding a new forge means adding files in a new directory/module that implement
an interface, plus one entry in the centralized registry/manifest for that
package.

The Three Registrations

For forge acme, the expected end state is:

Protocol manifest - optional, only when the forge should be presented by
shared manifest data. Add one ForgeDefinition to
packages/protocol/src/forge-manifest.ts.
Server adapter - add packages/server/src/services/acme-service.ts
implementing ForgeService, any adapter-owned fact types/guards/constants
beside it, and one defaultForgeRegistry entry in
packages/server/src/services/forge-registry.ts.
App modules - a forge splits into a pure logic half and a view half so
logic consumers (URL builders, merge-capability, native checks, and the
Node-based e2e harness) never pull the client rendering stack:
- packages/app/src/git/forges/acme.ts - logic: id, optional urlGrammar
  (source links and pasted issue/change-request reference paths), optional
  facts (schema, merge-capability, native-check fallbacks). No
  React/React-Native imports. Register in CLIENT_FORGE_LOGIC_MODULES in
  packages/app/src/git/forges/index.ts.
- packages/app/src/git/forges/acme.view.tsx - view: icon (SVG component
  under packages/app/src/components/icons/), optional brandColor, optional
  paneContributions. Register in CLIENT_FORGE_VIEW_MODULES in
  packages/app/src/git/forges/view.ts.

There should be no protocol typed-union arm, no central app icon/color/url/facts
map, and no central server union of known forge facts.

Protocol

forgeSpecific on PR status is an open envelope:

z.object({ forge: z.string() }).passthrough();

The forgeSpecific.forge field is a facts-family tag, not the workspace
brand id. Gitea, Forgejo, and Codeberg can all emit forgeSpecific.forge === "gitea" when they share the same facts shape, while top-level status.forge
keeps the brand id ("gitea", "forgejo", "codeberg").

Protocol does not validate per-forge fact fields. Consumers that understand a
facts family validate at runtime with their own schema/guard. Unknown or
schema-mismatched facts render neutrally instead of failing the whole message
parse. This is the version-skew win: an old client can receive facts from a
newer forge and still show the PR/MR in a neutral state.

Check results keep a stable normalized status for aggregation and an optional
open traits: string[] for composable forge-neutral refinements such as
manual, action_required, and warning. Consumers ignore unknown traits and
fall back to status; rawStatus preserves provider-native detail. Do not add
provider vocabulary to the normalized status union. Producers and the
presentation layer share the trait constants in
packages/protocol/src/check-traits.ts — use those instead of string literals
so classification and emission cannot drift apart.

Shipped GitHub compatibility stays separate:

The forge compatibility layer first shipped in v0.2.0-beta.1. Its initial
six-month cleanup target is 2027-01-17, after supported client and daemon
floors reach stable v0.2.0.
status.github remains accepted for released peers.
The server keeps the COMPAT(forgeSpecific) mirror that copies GitHub facts
into status.github for older clients.
Do not add a compatibility shim unless a released peer (<= 0.1.102) can
actually produce the state.

Server

The server-wide status type only promises:

type ForgeSpecificStatusFacts = { forge: string } & Record<string, unknown>;

Adapter-owned files define the typed shapes and guards, for example
github-facts.ts, gitlab-facts.ts, and gitea-facts.ts. The adapter can keep
strong internal types for construction and command guards, but shared server
code must not grow a central list of forge fact arms.

createService
matchesHost from manifest cloudHosts
probeHost when self-hosted/Enterprise detection is supported

Current change-request lookup uses two identities deliberately:

An open PR/MR belongs to the checkout when its head branch and head repository
match. Its remote head SHA may differ because the checkout can be ahead,
behind, or contain commits that have not been pushed yet.
A merged or closed PR/MR belongs to the checkout only when its recorded head
SHA exactly matches the checkout's current HEAD. Branch names are reusable;
selecting the newest terminal request by branch alone can silently attach an
old promotion or feature request to new work.

Thread the checkout head SHA through adapter cache and poll identities as well
as the lookup itself. Otherwise a commit made on the same branch can inherit the
previous commit's cached terminal status until the cache expires.

Cloud hosts in the manifest are a bounded public-host list, not a self-host
allowlist. Self-hosted detection is a trust gate: Paseo only talks to a forge
host that is either a known cloud host or one the CLI is already authenticated
to. Adapter probes must not make anonymous HTTP requests to remote-derived
hosts, and adapters must not route credentials to an unauthenticated host.

App

Each app forge splits into two modules so pure logic never imports the client
rendering stack:

acme.ts exports a ClientForgeLogicModule:

id
optional urlGrammar (including referencePaths for composer auto-attachment)
optional facts registration (schema, merge-capability, native-check fallbacks)

acme.view.tsx exports a ClientForgeViewModule:

id
icon
brandColor (null for neutral; GitHub intentionally uses null)
optional paneContributions

Two registries live under packages/app/src/git/forges/:
CLIENT_FORGE_LOGIC_MODULES (index.ts) drives URL grammar, merge-capability
derivation, and native fallback checks; CLIENT_FORGE_VIEW_MODULES (view.ts)
drives icon/color lookup and PR-pane contributions. Logic consumers must import
the logic registry only — importing the view registry (or a .view.tsx module)
from a logic path pulls react-native and breaks the Node-based e2e harness.

Per-forge brand colors live on the module, not in styles/theme.ts. Use the
Unistyles-safe pattern from docs/unistyles.md: no useUnistyles(). Brand icon
call sites use withUnistyles and a uniProps mapping such as:

(theme) => ({ color: theme.colorScheme === "light" ? colors.light : colors.dark });

Facts modules use one source of truth: a Zod schema. Helpers like
defineForgeFacts, defineNativeFallbackCheck, and definePaneContribution
derive guards from schema.safeParse and re-parse before invoking typed
derivers/renderers. That keeps typed derivers away from the open wire envelope.

Checklist

To add acme:

Add acme to FORGE_DEFINITIONS if the shared manifest should know its
label, nouns, icon kind, sign-in CLI, or cloud hosts.
Add acme-service.ts implementing ForgeService.
Add acme-facts.ts beside the adapter if it reports native facts.
Add one defaultForgeRegistry entry.
Add packages/app/src/git/forges/acme.ts (logic) and
packages/app/src/git/forges/acme.view.tsx (view).
Add one CLIENT_FORGE_LOGIC_MODULES entry (index.ts) and one
CLIENT_FORGE_VIEW_MODULES entry (view.ts).
Add/update the icon component only if the client bundle should show a brand
mark.
If the forge's CI/data model does not fit an existing required
ForgeService field, widen the shared interface (plus the protocol schema
and its guards) instead of faking a value — e.g. Gitea Actions runs carry no
check-run id, so GetCheckDetailsOptions.checkRunId became optional with
workflowRunId as the alternative address. Expect this step to touch
forge-service.ts, messages.ts, and the call-site guards of the other
adapters. Widening a shared field is not forge-local: it also affects the
already-shipped forges/GitHub call sites and the capability-gated RPC (e.g.
forgeCheckDetails), so verify every consumer rather than assuming the change
only reaches the new adapter.
Run targeted tests: manifest/registry/resolver, the adapter test, protocol
checkout PR schema, app forge URL/presentation tests, app merge capability,
and any PR-pane native data tests touched.

Run npm run typecheck after each implementation slice. If protocol or client
declarations are stale, run npm run build:client; if server/CLI declarations
are stale, run npm run build:server.

Gotchas

GitHub is a normal registry entry plus released compatibility shims. Keep all
real shims tagged with COMPAT(name).
Gitea-family facts use forgeSpecific.forge === "gitea" even when the
top-level brand is Forgejo or Codeberg.
Gitea's legacy Actions task endpoint cannot filter by commit, may enforce a
page size below the requested limit, and omits rerun-attempt numbers. Walk a
bounded number of pages using total_count and filter locally. Preserve
ambiguous same-run tasks: display names are not stable job identities, so
name-based deduplication can hide a real failure.
A blocked Gitea Actions task is not necessarily manual: only add the
action_required trait when the matching run metadata reports
need_approval.
Brand icons are bundled React components, so they cannot come from protocol
manifest data.
Source URL grammars are app-side because blob/tree path syntax is
forge-specific. If a forge has no grammar, omit the "Open on ..." source link
rather than constructing a wrong URL.
Pasted issue/change-request URL recognition is also app-side and registry
driven. Put the forge's route infixes in urlGrammar.referencePaths; the
neutral extractor matches the pasted host and full repository path against
the current remote before it invokes cwd-routed forge search. Do not add a
central forge switch or guess a self-hosted Gitea-family brand from URL shape.
GitLab pipeline status constants belong to the GitLab adapter/client module,
not protocol.
GitLab manual jobs need allow_failure to distinguish optional gray jobs
(manual) from blocking jobs (manual plus action_required). A failed
allowed-failure job carries the warning trait, and canceling remains active
until GitLab reports a terminal status.
GitHub PR polling owns one account-wide GraphQL budget. Coordinate retained
targets per host, batch their reads, and stop until GitHub's reset time when
the reserve is exhausted. Never add a per-target GitHub request to the poll
path. Resolve fork PRs through their parent repository without abandoning the
shared batch.

Forms (`docs/forms.md`)

Forms

The paved road for building forms in the app. The schedule form is the golden
example; when building or fixing any form, copy its shape, not the shape of
whatever screen you happen to be near.

Golden example files:

packages/app/src/schedules/schedule-form-model.ts (+ .test.ts) — the model
packages/app/src/schedules/use-schedule-form-model.ts — model lifetime adapter
packages/app/src/schedules/use-schedule-form-provider-snapshot.ts — async input adapter
packages/app/src/components/schedules/schedule-form-sheet.tsx — render + intent dispatch
packages/app/src/schedules/aggregated-schedules.ts / hooks/use-schedules.ts — load-state gating
packages/app/e2e/schedules-*.spec.ts — the behavioral contract

The form model

Every non-trivial form gets a plain TypeScript model — zero React imports:

openXxxForm(snapshot) constructs a fresh instance from declared inputs
(mode, the record being edited, hosts, defaults). Edit mode seeds every value
AND display from the snapshot — never from a previous instance.
Commands mutate (setHost, setProject(value, display), setModel, …).
Derived state (disclosure, canSubmit, displays) is recomputed inside the
model on every publish.
close() destroys the instance. subscribe/getState feed one
useSyncExternalStore in the component.

The component renders state and dispatches intent. That is all it does.

Lifecycle rules (each one killed a real shipped bug)

Fresh mount per open. The sheet returns null when not visible and
mounts the open form with a key derived from mode + record identity.
A long-lived component instance shared across create/edit is how edit
contaminated create.
Construct the model ONCE per mount — useState(() => openXxxForm(snapshot)).
NEVER useMemo(() => open(...), [snapshot]): the snapshot's identity depends
on live data (projects, hosts, preferences), and any background churn — e.g.
a scheduled run creating a workspace — would reconstruct the model and wipe
the user's in-progress input.
Late data is an explicit model input, not a reconstruction.
applyProviderSnapshot(serverId, …), applyProjectTargets(…),
applyHosts(…). Adapters pipe identity changes into these with mechanical
effects. Input plumbing is fine; orchestration effects are not — the sheet
itself has zero useEffect/useRef, and that is the target for every form.
Resolution is explicit model state, per host (idle | pending | complete), keyed off the opened snapshot's serverId. Waiting for data is a
state you can render, not an effect race.
Displays are owned state. The selected option's label is captured at
selection/seed time (setProject(value, display)), never re-derived from a
live options list — list churn must not flicker or blank a selection.
Disclosure is derived in the model from user intent
(host → project → model → thinking/mode), so fields cannot pop in from
cache timing.

Form kit

Compose Field / SelectField / FormTextInput / SegmentedControl /
Switch from components/ui/. Geometry (heights, padding, radii, focus/hover
states) is owned by components/ui/control-geometry.ts — controls never
declare their own, and screens never nudge global component styles to align
a row.
Every text field consumes EditingTextInput, directly or through a UI
wrapper. The editing surface owns in-progress text; React observes committed
edits through onChangeText, and programmatic mutations use the input's
replaceText command. Its props omit value and defaultValue, web IME
candidates stay unpublished until composition commits, and lint rejects raw
React Native TextInput imports outside the primitive.
The form declares one size for all fields: sm on desktop, md compact
(useIsCompactFormFactor).
Availability hierarchy: a field whose capability doesn't apply is hidden
(isolation on a non-git project — same gating as New Workspace), not rendered
disabled with an explanation. Disabled-with-a-reason hint is only for
transient states the user can resolve.
Copy is opt-in and rare. No hint/subtext unless the maintainer approved the
exact string; validation errors are the exception. State a fact (like the
timezone) once — never in a preview line AND a helper line.
useUnistyles is banned (see docs/unistyles.md); lint enforces.

Settings rows

Use the named components from @/components/settings for settings cards and controls.
SettingsCard owns row separators; SettingsRow accepts custom content. Heading-only screens
can import SettingsGroup and SettingsSection directly from their modules in
@/components/settings/headings/.
The plugin UI entry exposes the same components; keep them independent of storage and routing.

Data gating

Aggregate hooks return a discriminated load state:

type AggregateLoadState<T> =
  | { status: "connecting" } // an answer may still be pending
  | { status: "loading" }
  | { status: "loaded"; data: T[] };

Empty states are only typeable inside loaded — a fetch that "succeeded"
before hosts connected is connecting, not empty. Query keys carry real fetch
inputs (host set, connection statuses), never synthetic version counters.

Anti-patterns (reject in review on sight)

useEffect choreography impersonating construct/hydrate/resolve/destroy.
One mounted form instance serving create and edit.
useMemo-keyed model construction on live-data identity.
Selected labels derived from live query lists.
isLoading/isEmpty boolean bags where a load-state union belongs.
Conditional mounting of hint/error rows that shifts layout (subtext renders
only when present, but the pattern for that lives in Field, not ad hoc).

Glossary (`docs/glossary.md`)

Paseo Glossary

Authoritative terminology. UI label wins. Don't invent synonyms; use what's here.

Project — A stable, exact selected-root record. Its host-local projectId is an opaque prj_<16 hex> value. Its persisted projectKey is an opaque equivalence key that may group the logical project across hosts. A normalized Git remote is the current key producer, but consumers must not parse or rederive it. Git facts can update mutable kind and grouping metadata but never the ID, root, or default display name. UI: "Project" / "Add project". Forbidden: "Repo", "Repository" as UI label.
Workspace — One concrete cwd on one daemon, with git state; belongs to exactly one project. Its id is opaque workspace identity; its cwd is the filesystem directory. UI: "Workspace". Code: WorkspaceDescriptorPayload (packages/protocol/src/messages.ts:2178). Don't confuse with: Branch (one branch can back many workspaces via worktrees). Forbidden: "Folder", "Directory" as UI label.
Archive workspace — Removes one workspace from active use and archives everything it owns. UI, CLI, and MCP always say "Archive workspace", regardless of backing. The daemon leaves ordinary directories intact and removes a Paseo-owned worktree only when no active workspace still references it.
Workspace kind — "directory" | "local_checkout" | "worktree". The git-derived, persisted property of a workspace, used across its lifetime (archive safety, sidebar, grouping). Derived from the cwd's git reality by deriveWorkspaceKind in workspace-registry-model.ts, not stored from a user choice. Don't confuse with Isolation (the create-time intent).
Isolation — Create-time choice for a new workspace: reuse the existing checkout (Local) or cut a dedicated git worktree (New worktree). A transient setup input, also remembered as a create-form preference; it is not a workspace property. UI: "Isolation" control on the New Workspace screen. Code: isolation ("local" | "worktree"), useWorkspaceIsolation (packages/app/src/screens/new-workspace-screen.tsx); persisted as FormPreferences.isolation (packages/app/src/create-agent-preferences/preferences.ts). Distinct from Workspace kind, which is the git-derived property the intent produces (Local → local_checkout or directory by git-ness; New worktree → worktree). On the wire it is the create request's source.kind (directory | worktree, packages/protocol/src/messages.ts:1693).
Agent — See Agent session. UI still says "Agent" / "New Agent" in places, but moving toward Agent session as the canonical term. Code: AgentSnapshotPayload (packages/protocol/src/messages.ts:608). Forbidden: "Task", "Job", "Run".
Daemon — Local Paseo server process; identified by serverId. UI: "Daemon" (system contexts only). Code: serverId in ServerInfoStatusPayloadSchema (packages/protocol/src/messages.ts:1936), DaemonClient (packages/client/src/daemon-client.ts).
Host — Client-side connection profile pointing at a daemon; bundles one or more HostConnections. UI: "Host" / "Add host" / "Switch host". Code: HostProfile (packages/app/src/types/host-connection.ts:37). Forbidden: "Connection" (means HostConnection, not host).
Host badge — The item on a sidebar workspace row's meta row naming which host that workspace lives on. Three things gate it, and they compose as a lattice rather than competing: the sidebar must span more than one host (automatic), Show → Host in the sidebar's display preferences must be on (global, all hosts at once), and then that host's own display mode decides how it draws — Name / Icon only / Hidden. Name, color, and display mode are per-host, per-device, and live client-side on HostProfile.appearance; nothing about it reaches the daemon. Never add a fourth way to hide it. UI: the "Appearance" group on a host's settings page, and the "Show" submenu in the sidebar's display preferences. Code: selectHostBadges (packages/app/src/hosts/appearance.ts) takes the first two as its enabled input; WorkspaceMetaRow (packages/app/src/components/sidebar/workspace-meta-row/index.tsx) draws it. Don't confuse with Status pill, which reports state rather than identity.
Project host entry — One row in a project for a single (project, daemon) pair, aggregating that daemon's workspaces in the project. Internal. Code: ProjectHostEntry (packages/app/src/utils/projects.ts:11). Don't introduce "Checkout" as a synonym.
Placement — One workspace's stable foreign-key relationship to its project plus its git checkout snapshot. Internal. An explicit creation projectId is authoritative when active.
Branch — Plain git branch. UI: "Switch branch". Code: currentBranch in WorkspaceGitRuntimePayloadSchema (packages/protocol/src/messages.ts:2136); BranchSwitcher (packages/app/src/components/branch-switcher.tsx).
Forge — Git hosting service behind Paseo's change-request features: GitHub, GitLab, Gitea, Forgejo, or a future registered adapter. Code: ForgeService, forge-registry, forge-resolver. Use forge for internal abstraction and registry IDs; use concrete forge names only when a behavior or RPC is forge-specific.
Change request — Forge-neutral term for a proposed branch-to-branch code change. UI normally renders the forge noun instead: GitHub/Gitea/Forgejo "PR", GitLab "MR". Code: forge_change_request attachments, checkoutSource: { kind: "change_request" }, and PR/MR status payloads.
MR — GitLab merge request. UI label for GitLab change requests only; do not use MR for GitHub/Gitea/Forgejo.
Worktree — Paseo-managed git worktree (~/.paseo/worktrees/{name}); also a workspaceKind value. User-facing creation treats it as the worktree workspace isolation choice. Code and paseo.json retain worktree terminology for git lifecycle implementation. Forbidden: "Checkout" as a product synonym.
Repository / Remote — Internal Git observations. They may produce mutable kind, branch, and project-grouping metadata but never the host-local project ID, root, display name, or workspace membership. No UI label.
Sidebar items — The configurable entries of the app sidebar, in two sections. Header: the rows at the head of the sidebar — New workspace, History, Search, Schedules, and plugin header items. Footer: the full-width rows between Add project and the footer icon row — Usage and plugin footer items. Add project and the icon row (Hosts, Help and support, Settings) are fixed and are not sidebar items. A plugin item may render several rows, such as one per bot; it is still one item that moves and hides as a block. Each section's order and visibility is one per-device preference (AppSettings.sidebarNavItems, AppSettings.sidebarFooterItems); every item may be off. UI: the Header and Footer cards on the Sidebar settings page. Code: packages/app/src/sidebar-nav/model.ts resolves a section, and the sidebar (components/sidebar/sidebar-nav-rows.tsx, the footer in components/left-sidebar.tsx) and the settings page (screens/settings/sidebar/sidebar-nav-section.tsx) read it through useSidebarNavItems(section). Never hardcode one of these entries or add a second place that decides which ones show. Don't confuse with Explorer sidebar.
Explorer sidebar — The dedicated navigation dock containing the Files and Changes trees. UI: "Explorer sidebar". Code: packages/app/src/workspace-tabs/explorer-sidebar.ts; persisted pane identifiers retain the explorer spelling. See explorer-sidebar.md.
Sheet — Any bottom sheet; there is one kind and one app-wide stack, so a sheet opened from a sheet lands on top of it and closing it uncovers the one below. Code: IsolatedBottomSheetModal (packages/app/src/components/ui/isolated-bottom-sheet-modal). Forbidden: "Workspace sheet", "modal sheet" as a distinct kind. See floating-panels.md.
Sheet tab — A compact-layout sheet holding one file or subagent tab over the workspace without adding it to the tab switcher. UI action: "Open as tab". Code: SheetTab and sheetsByWorkspace in packages/app/src/stores/workspace-layout-store.ts, SheetTabs (packages/app/src/screens/workspace/sheet-tabs.tsx). See explorer-sidebar.md.
Side pane — An ordinary right-side workspace pane used for content opened beside the user's work. It closes and participates in workspace splits like every other main-host pane. See explorer-sidebar.md. Forbidden: "Side panel".
Directory-backed surface — A right-sidebar surface whose content is determined by the workspace's cwd, so two workspaces on the same directory see identical content: git diff/status, forge change-request info, file preview/explorer contents. Keyed by (serverId, cwd), never workspaceId. See architecture.md.
Workspace-owned state — Per-workspace state that never leaks to a same-cwd sibling: tabs, agents, terminals, panes, title, plus review drafts, diff-mode overrides, composer attachments, and file-explorer open/expand state. Keyed by workspaceId (cwd only as a fallback for old payloads). See architecture.md.
Last prompt — Sidebar workspace sort by the most recent human prompt recorded by an agent in that workspace, including archived agents. Agent output, agent-to-agent messages, scheduled prompts, and opening a workspace do not count. A workspace without a human prompt uses its creation time.
Workspace status bucket — Aggregate activity signal for a workspace row. Same-cwd workspaces intentionally share agent and terminal status buckets, while tab, agent, and terminal visibility remains scoped by workspaceId.
Agent session — One running instance of an agent inside a workspace (one provider, one model, one cwd, one timeline). The conceptual unit; in the UI this opens as a tab. Moving toward this as the canonical term over "Agent". Code: AgentSnapshotPayload (packages/protocol/src/messages.ts:608).
Session — Two senses: (a) per-client connection to a daemon, internal; (b) user-facing agent session, see Agent session. Code: Session (packages/server/src/server/session.ts) for (a). Don't confuse with: provider-side agent session log.
Profile — Internal name for the persisted shape of a host. Code: HostProfile (packages/app/src/types/host-connection.ts:37). Never user-facing. Three other things are called "profile" in this codebase, so always qualify: Agent profile, Terminal profile, and the provider aliases in custom-providers.md. Bare "profile" is forbidden in UI copy.
Agent profile — A named launch bundle: provider, model, mode, thinking option, feature values, and free-text notes. Applying one writes those values into the Agent controls and is then forgotten — there is no selected profile, no default profile, and no drift tracking. The notes are written for orchestrating agents and are what the list_profiles MCP tool surfaces. Stored host-wide in daemon config as agentProfiles. UI: "Agent profiles". Code: AgentProfile (packages/protocol/src/messages.ts:161). Carries no system prompt, because a per-agent system prompt can only be set at creation. Forbidden: "Favourite", which this replaced.
Terminal profile — A named shell command a terminal can launch. Stored host-wide in daemon config as terminalProfiles. UI: "Terminal profiles". Code: TerminalProfile (packages/protocol/src/messages.ts:135), resolveTerminalProfiles (packages/protocol/src/terminal-profiles.ts). Also selectable as a New Workspace launch target, where the alternative is the chat agent.
Provider — Agent backend (Claude Code, Codex, Copilot, OpenCode, Pi, Oh My Pi). UI: "Provider". Code: ProviderSnapshotEntry (packages/protocol/src/messages.ts:198).
Usage source — Plugin registration that discovers accounts and fetches plan usage. Code: UsageSourceRegistration (packages/plugin/src/server/usage.ts).
Report ID — Stable daemon-composed identity for one source account: :<accountKey>. The source owns the account key; clients treat the whole ID as opaque. Code: UsageReportEntry.id (packages/protocol/src/messages.ts).
Usage report — A source's normalized usage for one account, including status and optional windows, balances, and details. Its entry carries the Report ID, account label, and fetch time. Each report renders as one card in the Usage modal, in host Settings, and in an agent's context window details (a hover card on desktop web, a tooltip on native wide screens, a sheet on compact ones), which show only the account that agent runs under, without pins. The hover card and the sheet have Refresh; the native tooltip takes no presses. Code: UsageReport (packages/plugin/src/server/usage.ts), UsageCard (packages/app/src/usage/card.tsx), AgentUsage (packages/app/src/usage/agent-usage.tsx).
Usage (sidebar item) — The sidebar footer item showing each pinned window's source icon and percent, hidden while no pinned window has data (the footer's Usage icon remains available); both entry points open the Usage modal over the current screen: a dialog on wide layouts, a bottom sheet on compact ones. Usage has no route of its own. Off until the user turns on Summary in sidebar (Usage Settings) or the Usage row in Settings > Sidebar; window rows pin only while it is on, and saved pins come back when it is turned on again. A pin is { sourceId, windowId } and shows once per account of that source. Pins and the used/remaining choice are one per-device preference (AppSettings.usage) that every usage surface follows. It reads the active workspace's host, else the first connected host with usage sources. Code: packages/app/src/usage/sidebar-item.tsx, usage/usage-modal.tsx, usage/pinned.ts, usage/preferences.ts.
Model — A specific LLM offered by a provider. UI: "Model" / "Select model". Code: AgentModelDefinition (packages/protocol/src/messages.ts:187).
Tab — UI surface representing one session inside a workspace. Not a conceptual unit; use Agent session when talking about the model. Code: WorkspaceTabDescriptor (packages/app/src/screens/workspace/workspace-tabs-types.ts).
Terminal — Workspace-scoped PTY shell streamed over the binary mux channel. UI: "Terminal". Code: TerminalStreamFrame (packages/protocol/src/terminal-stream-protocol.ts).
Workspace script — A named command a workspace can run, declared in paseo.json. Two types: service and script (a command that runs and finishes). UI: "Scripts" for the panel and the menu, both of which list either type. Code: WorkspaceScriptPayload (packages/protocol/src/messages.ts:3126). Don't confuse with Service, which is one of the two types rather than a synonym for the pair.
Service — A workspace script of type service: long-running, may bind a port, and carries health of healthy | unhealthy | null once the daemon has observed it. The only type a sidebar workspace row reports, because a running plain script says nothing about whether the workspace is up; the row names the service and turns danger when its health fails, and where several run the failing one takes the row's single slot. UI: "Services" in the sidebar's display preferences (Show → Services). Code: selectWorkspaceServiceSummary (packages/app/src/components/sidebar/workspace-meta-row/service-summary.ts), WorkspaceScriptHealthSchema (packages/protocol/src/messages.ts:3124). Forbidden: "Service" as a label for the Scripts panel, which lists both types.
Schedule — Cron-style trigger that creates new agents. UI: CLI/MCP (paseo schedule, create_schedule). Don't confuse with: Heartbeat (cron prompt back into the same agent).
Heartbeat — Ephemeral cron prompt sent back into the same agent/conversation. Agent surfaces expose create, update cron, and delete only. Use for reminders and babysitting where status should return inline.
Mode — Provider-specific operational mode (plan, default, full-access, …). UI: icon-only. Code: modeId in AgentSessionConfig (packages/protocol/src/messages.ts:257).
Attachment — External or local context bound to an agent prompt: forge issue/change request, review context, uploaded file, text, or image. UI: "Attach issue or PR/MR". Code: AgentAttachment (packages/protocol/src/messages.ts:782).
Composer — The whole prompt surface for sending work to an agent. Code: Composer (packages/app/src/composer/index.tsx). Don't call this "message input" except for the text-entry subcomponent.
Composer input — The text-entry surface inside the composer. Code: MessageInput (packages/app/src/composer/input/input.tsx).
Composer toolbar — The bottom control row inside the composer input. Contains agent controls, attachment button, voice controls, and stop/send controls. Code: leftContent, beforeVoiceContent, and rightContent slots in MessageInput (packages/app/src/composer/input/input.tsx). Forbidden: "Status bar".
Agent controls — Provider, model, mode, thinking, and provider-feature controls for an agent or draft agent. Code: AgentControls / DraftAgentControls (packages/app/src/composer/agent-controls/index.tsx). Forbidden: "Agent status bar".
Composer footer — Optional area rendered below the composer input but still inside the keyboard-shifted composer layout. Code: Composer.footer (packages/app/src/composer/index.tsx).
Composer track — A contextual lane at the foot of a pane, by the composer input. Specific tracks use the track form: Queue track, Subagents track, Tasks track. The subagents and tasks tracks are pills floating over the transcript, each opening a panel with its rows; the queue track is a lane inside the composer itself. Code: queue track inside Composer (packages/app/src/composer/index.tsx), pill and panel frame in packages/app/src/composer/tracks.tsx, SubagentsTrack (packages/app/src/subagents/track.tsx), AgentTaskList (packages/app/src/composer/task-list/index.tsx).
Steer — A follow-up admitted into an agent's already-running turn instead of interrupting it. Interrupting the turn discards steers the provider has not read yet; there is no take-back short of that, and no provider offers one. The stop button and Escape both interrupt. A steer the provider never read keeps its transcript row, matching Codex. Sending while the agent waits on a permission denies that request first, so the message reaches the same turn instead of stalling behind it. UI: "Send and steer". Code: steerActiveTurn (packages/server/src/server/agent/agent-sdk-types.ts). Don't confuse with Queue track, which holds messages client-side until the turn ends and never enters the running turn. Forbidden: "Delivery", "Queued prompt".
Subagent — User-facing term for an agent session related to a parent agent session. Use subagents in UI copy and docs. Internal daemon/provider plumbing may say "child agent" or child_session, especially for provider-managed imports; do not surface "child agent" as a product term.
Attachment tray — The selected-attachments row inside the composer input, above the text input. Code: renderAttachmentTray (packages/app/src/composer/index.tsx). Forbidden: "Attachment bar".
Fork — Starting a NEW agent session seeded with a copy of another session's curated chat history. The history rides along as a chat_history composer attachment on a draft; the fork does not resume or branch the provider-side session, and the source session keeps running untouched. Two targets, one surface, one RPC (agent.fork_context, gated on the agentForkContext host feature). UI: the fork menu lives in the assistant turn footer and offers "Fork in a new tab" / "Fork in a new workspace". On a completed turn it sits beside the copy button and pins a boundary to that turn, so the fork stops where the turn ended. On the in-flight turn it sits beside the progress loader and elapsed timer, and omits the boundary entirely — selectForkContextRows projects the whole timeline when no boundary is given, so the fork captures everything up to now, including the response still streaming. That omission is what makes mid-run forking work; pinning a boundary there would silently drop the live response. Forbidden on provider-subagent (read-only) panes. Code: useForkAgent (packages/app/src/hooks/use-fork-agent.ts), selectForkContextRows (packages/server/src/server/agent/activity-curator.ts). Don't confuse with: git fork (unrelated; Paseo has no such concept), Worktree (filesystem isolation, not history copying).
Conflict — Two distinct senses; do NOT use the bare word in UI copy without qualifying which: (a) stale-write conflict on paseo.json ("Config changed on disk", code stale_project_config, packages/app/src/screens/project-settings-screen.tsx:593); (b) git merge conflict (no current UI string).
Product discussion — Where non-bug product talk goes: GitHub Discussions and #product in Discord. Covers workflows, features, and product direction. The container term; the ask inside it is always a workflow — what you're doing, how you do it today, where Paseo gets in the way. Issues are bugs only. Forbidden: "Feature request" as a Paseo surface, label, or invitation; the phrase is only used when answering someone who arrived with it. Don't invent "feature discussion", "idea", or "workflow thread" as synonyms. See CONTRIBUTING.md.

Inconsistencies (documented, not papered over)

CLI --host <host> description "Daemon host target" (packages/cli/src/utils/command-options.ts:5) blurs daemon/host; the app keeps them distinct.
WorkspaceDescriptorPayloadSchema.workspaceKind accepts legacy "checkout" on the wire (packages/protocol/src/messages.ts:2187) while PersistedWorkspaceKind does not (packages/server/src/server/workspace-registry-model.ts:8).

Hover (`docs/hover.md`)

Hover

Read this before writing any hover code. Every hover regression we ship is one of the three failure modes below, and every one of them is solved by the same canonical pattern. The pattern is hardwon — it survived every other shape we tried — so copy it, don't reinvent it.

The pattern

The canonical implementation lives in packages/app/src/components/sidebar-workspace-list.tsx, in the workspace row (around line 1369). When in doubt, open that file and copy the shape.

tsx

//
//   ┌─ Plain View. Tracks hover via pointerenter/pointerleave.
//   │
<View
  style={styles.workspaceRowContainer}
  onPointerEnter={handlePointerEnter}
  onPointerLeave={handlePointerLeave}
>
  <Pressable                          // ┐ Separate inner Pressable.
    onPress={handlePress}             // │ Handles press only.
    onPressIn={...}                   // │ Never has onHoverIn/onHoverOut.
    onPressOut={...}                  // ┘
    style={workspaceRowStyle}
  >
    <View style={styles.workspaceRowMain}>
      <View style={styles.workspaceRowLeft}>…</View>
      <WorkspaceRowRightGroup isHovered={isHovered} />
      {/*                    └─ Reveals content based on hover state. */}
    </View>
  </Pressable>
</View>

Five things make this work. Every one of them matters.

Hover lives on a plain View, not a Pressable. Pressable carries its own internal hover state machine. Nested Pressables fight over it. A plain View just dispatches DOM events — no state machine, no fighting.
Press lives on a separate inner Pressable. Hover and press never share an element. The two state machines never see each other.
onPointerEnter / onPointerLeave are non-bubbling, mouseenter-style by W3C spec. They fire only when crossing the outer View's bounding box. Crossing into descendants — including descendant Pressables (the kebab menu's buttons, a copy button, a tooltip target) — does not fire pointerleave. This is why nesting Pressables inside is safe.
The row has a fixed minHeight. When content swaps in on hover (kebab replacing a diff stat), both occupy the same fixed slot. Zero layout shift, zero geometry flicker.
The outer View has nothing but position: relative. It exists only to be the hover target. All real layout lives on the inner Pressable. The hover-tracker is a sealed envelope around the row; layout changes inside it never leak out and re-enter through the side.

That's the whole pattern. Internalize it.

When you skip the pattern, here is what breaks

Failure mode 1 — Nested Pressables fight over hover state

If you put onHoverIn / onHoverOut on a Pressable that has another Pressable anywhere inside it (a copy button, an icon button, a nested action), the moment the cursor moves onto the inner Pressable, the inner one's hover state machine claims hover and the outer one's onHoverOut fires. Your reveal state flips off. The reveal hides. The cursor is no longer over the hidden reveal, so it ends up back over the trigger area. The outer's onHoverIn fires. Loop.

This is the most common hover bug shipped in this codebase, by a wide margin. It is what the workspace row is structured to avoid. The fix is not "be clever about handlers" — it's "don't put hover on a Pressable that contains other Pressables."

Rule: the hover-tracking element is a plain View with onPointerEnter / onPointerLeave. Any Pressables — including ones you forgot are Pressables, like TurnCopyButton, icon buttons, anything that handles a tap — live inside it.

Failure mode 2 — The hovered state changes the trigger's geometry

Symptom: you hover a button, it changes appearance, then flickers between hovered and not-hovered without the cursor moving.

Cause: the hover state changed the size or position of the trigger. The cursor was on the original element; the new layout shifts or shrinks it out from under the cursor; onHoverOut fires; state reverts; original layout returns; cursor is back over the trigger; onHoverIn fires; loop.

Common variants:

Hover state changes the trigger's width, height, padding, or borderWidth.
Hover state mounts/unmounts a child that pushes the trigger to a new position.
Hover state swaps the trigger for a different element type, remounting it.

Fixes, in preferred order:

Don't change the trigger's outer geometry on hover. Change colors, opacity, borders that don't take layout space (outlineWidth on web, absolutely positioned overlays), or child content that fits inside the same fixed box. Never change width, height, padding, or borderWidth of the hover target itself.
Hide with opacity + pointerEvents, not conditional rendering, when the hidden element lives inside the trigger. Mounting/unmounting on hover reflows the layout under the cursor.
Pin the hit area. Set a fixed minHeight / minWidth on the trigger so internal swaps (icon-A becomes icon-B on hover) leave the bounding box unchanged. The workspace row's minHeight: 36 is what makes the kebab/diff-stat swap stable.

Failure mode 3 — Revealed content lives outside the hover trigger

If hovering element A reveals element B, B must be inside A's hover trigger. If B is a sibling, the moment the cursor moves from A toward B it crosses out of A's bounding box, pointerleave fires, B disappears.

Wrong:

tsx

<View>
  <View onPointerEnter={...} onPointerLeave={...}>     {/* hover trigger */}
    <Bubble />
  </View>
  <TrailingRow />                                       {/* OUTSIDE — sibling, not child */}
</View>

Right:

tsx

<View onPointerEnter={...} onPointerLeave={...}>      {/* hover trigger */}
  <Bubble />
  <TrailingRow />                                      {/* INSIDE — child */}
</View>

Any gap between A and B (margins between siblings inside the same parent) is part of the parent's bounding box, so the cursor stays inside the hover region while crossing it. No bridge needed.

If A and B genuinely can't share a parent — B portals into a different layer, floats above other content — see Section: real gaps below.

A kebab that only exists while its row is hovered opens a menu, and that menu takes the pointer
off the row: a sheet slides up over it, a popover covers it. The row un-hovers, the trailing
overlay unmounts, and the trigger goes with it — taking the menu's open state, which lived
inside the trigger's subtree. The surface itself is already presented in a portal, so nothing
unmounts it and nothing is left that can close it. On a bottom sheet that means a full-screen
backdrop swallowing every click until reload.

Lift the menu's open state to whatever decides to render the trigger, and keep the trigger
rendered while the menu is up. useOpenKebabMenuVisibility
(packages/app/src/components/sidebar/use-open-kebab-menu-visibility.ts) is that shape for the
sidebar rows: it owns open, hands the menu its controlled props, and ORs open into the
row's own showKebab.

Native fallback

Hover doesn't exist on touch devices. Anything you hide behind hover must have a non-hover path on native and compact layouts:

tsx

const showControls = isHovered || isNative || isCompact;

isNative and isCompact come from @/constants/platform and @/constants/layout. Don't use Platform.OS === "ios" as a proxy.

onPointerEnter / onPointerLeave are DOM events. They do not fire on native. You do not need to gate them — on native, hover is unreachable anyway and visibility is driven by isNative / isCompact in your show-the-controls expression above. This is why the workspace row's pointer events are not wrapped in if (isWeb).

What about `Pressable.onHoverIn` / `onHoverOut`?

It's fine when a Pressable styles itself based on its own hover — for example, an icon button that changes color on hover. That's self-contained. The render-prop ...}> does the same thing more cleanly and is the preferred form.

It is not fine for tracking hover to drive state outside that Pressable (revealing a sibling, opening a tooltip, showing a kebab) when there is any other Pressable inside — because that's Failure Mode 1.

Heuristic: if your hover state is going to be useState'd and read by anything other than the same Pressable's own style, do not use onHoverIn / onHoverOut. Use the canonical pattern.

Real gaps with floating panels

Sometimes the revealed content can't live inside the trigger — a hover card portals into a different layer, a tooltip floats above other content, a popover renders into a Portal. There's a real visual gap the user has to cross with the cursor.

For a card whose content the user can point at or press, use HoverCard (packages/app/src/components/ui/hover-card.tsx). It is built on useHoverSafeZone (packages/app/src/hooks/use-hover-safe-zone.ts), which computes a rectangular "bridge" across the gap between the trigger and the content, whether the card sits beside, above, or below the trigger. While the pointer is inside trigger, content, or the bridge, the card stays open. A short grace timer absorbs jitter at the edges. Tooltip takes no pointer events and closes as soon as the pointer leaves the trigger. If the trigger has no focusable child, give HoverCardTrigger focusable and an accessible label so keyboard users can open the same content.

Don't roll your own. The math is annoying, the edge cases (pointer leaves window, drag in progress, content unmounts) are subtle, and we already paid for the hook.

Pre-PR checklist

Before opening a PR that touches hover:

Hover-tracking is on a plain View with onPointerEnter / onPointerLeave, not on a Pressable that wraps anything pressable.
Any press behavior lives on a separate inner Pressable that does not have onHoverIn / onHoverOut.
The hover trigger's bounding box contains every element the user might mouse into while interacting with the feature.
Hovered state does not change the trigger's outer geometry (width, height, padding, borderWidth, mount/unmount of siblings that shift it). Internal swaps fit inside a fixed minHeight / minWidth.
Revealed content inside the trigger uses opacity + pointerEvents, not conditional rendering, if mounting it would reflow the trigger.
Visibility on native and compact layouts works without hover (isHovered || isNative || isCompact).
A menu opened from the revealed trigger keeps the trigger rendered while it is open, so losing hover can't strand it.
If the revealed content sits in a separate layer (portal, floating panel) and the user can point at it, it is a HoverCard.
You opened the dev server, hovered the trigger, and slowly moved the mouse along every revealed element — including any visible gaps — without losing hover state.

Hub (`docs/hub.md`)

Paseo Hub relationship

Paseo Hub is an explicit opt-in connection from one Paseo daemon to one Hub. Running a daemon does
not register it with a Hub. The relationship begins only when a user runs
paseo hub connect [url] from the daemon machine with an explicit API key or matching stored CLI login.

The human CLI login and daemon relationship are separate identities. paseo hub login [url] stores a durable organization-scoped CLI credential keyed by normalized Hub origin under PASEO_HOME. Interactive login optionally connects the local daemon, then points to the Hub UI for trigger configuration; it does not scaffold or deploy configuration. paseo hub init remains the explicit triggers-as-code scaffold: it writes one self-contained organization trigger under .paseo/triggers/, validates it through the trigger API, and optionally installs it. paseo hub deploy validates and installs every trigger in that directory; passing --project keeps deploying the legacy project bundle instead. paseo hub export [directory] writes the active organization's current triggers in the same layout, using the active login unless another Hub or API key is selected. Origin resolution uses explicit command input, PASEO_HUB_URL, active login, then https://hub.paseo.sh. Connect uses exact-origin authority to request a one-time enrollment token, then passes only that token to the daemon. The daemon generates and persists its own relationship credential.

Connection and authority

The daemon enrolls over HTTP(S), then opens and maintains a direct outbound WebSocket to the Hub.
The Hub never discovers or acquires the daemon through Paseo's relay. The relay remains an optional
encrypted path for normal Paseo clients and has no role in Hub enrollment, authentication, dispatch,
or reconnects.

The daemon persists a relationship ID and private connection credential before enrollment. The
relationship is independent of its current transport, so a future transport can replace the direct
WebSocket without pairing again. The current foundation supports one Hub relationship per daemon.

Normal authenticated daemon sessions may manage the daemon's Hub relationship and permissions.
Hub connections have no daemon permissions by default. Connecting gives Hub machine identity and
presence but no execution authority. The hub.execute permission lets workflows triggered from
GitHub, Slack, Discord, Linear, and other integrations create workspaces and run agents. Grant it
during interactive login or later with paseo hub permissions grant hub.execute. Relationships
created before this split migrate their legacy execution scope to hub.execute. Hub sessions cannot
manage their own relationship or permissions.

Session grants and agent operations

Hub uses the same authenticated, resumable Session protocol as other clients. Its persisted
hub.execute permission authorizes ordinary agent creation, workspace titling, messaging,
cancellation, archival, agent/workspace observation, timeline subscriptions, and workspace recovery. This authority is
daemon-wide; it is not limited to agents created by that Hub. Daemon configuration, terminals,
browser control, and permission management still require their own permissions. See
permissions.md.

Creating an agent may create a directory workspace. The same hub.execute session can title that
workspace through workspace.title.set.request without workspace.manage.

Clients using this contract check server_info.features.hubAgentRpc and
server_info.features.agentRequestReceipts once. An older host must be upgraded; do not silently
fall back to creating a fresh agent when continuation was requested.

Hub owns conversation keys, trigger policy, execution records, and the mapping to workspace/agent
IDs. None of these routing concepts are part of the generic daemon RPCs. Creation accepts ordinary
provider configuration, exact MCP tool policy, environment, and workspace/worktree selection.
Private session configuration is persisted for recovery and is not exposed in agent snapshots.
Provider controls remain provider-native; see providers.md.

create_agent_request.idempotencyKey identifies one creation operation. With a key, omit
initialPrompt, persist the returned agent/workspace identity, then deliver the prompt using
send_agent_message_request with a stable messageId. Request IDs correlate individual attempts;
creation keys and message IDs identify the operation across attempts. A creation key is daemon-wide;
a message ID is scoped to its agent. Reusing either with different arguments is a conflict.
workspace.create.request.idempotencyKey provides the same creation guarantee for directory and
worktree workspaces; check server_info.features.workspaceRequestReceipts before using it.
Workspace creation keys and agent creation keys have separate namespaces. The app keeps these keys
for the lifetime of a draft and reuses the first message ID after failures.

The daemon journals the assigned agent ID before creation. Concurrent retries share one operation,
and a retry after a lost acknowledgement or restart returns the durable agent without creating a
workspace or starting a turn. Deleting that agent does not make its old creation key reusable.
Confirmed message delivery is also journaled, so retrying its message ID does not submit it again.
An unfinished delivery after restart reports agent_request_outcome_unknown: a provider can have
accepted a prompt before the daemon recorded success, so automatic resubmission could duplicate
work. Inspect the agent before choosing a new message ID. Receipts contain identity and request
hashes, never prompts, environment values, or credentials.

Before messaging an archived workspace, call workspace.recovery.inspect.request, then
workspace.recovery.restore.request and await success. The native message handler unarchives the
agent and loads its persisted provider session. activeTurnBehavior: "steer" uses the provider's
native steering behavior, including Paseo's existing behavior when that provider cannot steer.
Execution completion and arrival-specific output authority remain Hub responsibilities.

The older hub.execution.* RPCs remain accepted for existing clients. Their execution ownership
and create deduplication behavior are unchanged; new continuation work uses the ordinary RPCs.

Disconnect and revocation

Normal socket loss reconnects the active relationship with bounded exponential backoff and jitter.
Daemon restart loads the same relationship and credential and reconnects without another enrollment
ceremony.

Hub authentication rejection or close code 4403 permanently revokes the local relationship. The
daemon deletes its credential, stops reconnecting, and retains only the relationship ID, Hub origin,
scopes, and a sanitized reason for status reporting.

paseo hub disconnect disables socket reconnect and execution authority before making one bounded
remote revocation request. The daemon then removes the local relationship whether the request
succeeds or fails. A failed request returns a warning that server-side revocation may remain pending.
--force skips the remote request. Legacy persisted disconnecting records are removed on startup;
the daemon does not retry revocation in the background.

paseo hub logout removes only the active human CLI credential and preserves credentials for other origins. Interactive logout inspects and optionally disconnects a same-origin daemon before deleting the login; a failed requested disconnect preserves the login. JSON and noninteractive logout never prompt or disconnect implicitly.

Cross-repository compatibility

The consumer implementation lives in Paseo Cloud. Cloud owns its copy of the Hub wire schemas and
has no Paseo runtime or build dependency. Cross-repository end-to-end verification separately builds
a Paseo source checkout and exercises the real daemon, CLI, direct WebSocket, Cloud service, and
Postgres. That compatibility fixture is not a package dependency or fallback implementation.
Its hub-e2e ACP provider accepts only exact tool names on the injected hub MCP server. Other
custom ACP providers remain unsupported for unattended preapproval.

I18n (`docs/i18n.md`)

I18n

Paseo client UI translations live in packages/app/src/i18n. Website translations are in website-i18n.md.

Supported Locales

en
ar
es
fr
ja
ko
pt-BR
ru
zh-CN

The persisted app language setting is "system" | "ar" | "en" | "es" | "fr" | "ja" | "ko" | "pt-BR" | "ru" | "zh-CN". "system" follows the device or browser locale when it maps to a supported locale; unsupported system locales fall back to English. Japanese maps from system locales ja and Japanese regional locales. Korean maps from system locales ko and Korean regional locales. Brazilian Portuguese maps from system locales pt-BR and bare pt; other Portuguese regional locales remain unsupported until explicitly added.

Translation Scope

Translate client-owned UI copy: labels, buttons, empty states, confirmation text, and local status/error wrappers.

Do not translate agent output, daemon output, terminal contents, file paths, provider names, model names, command names, user-authored text, code blocks, logs, or raw protocol/server error text.

Adding Copy

English source strings live in packages/app/src/i18n/resources/en.ts. Each supported locale has a matching resource in packages/app/src/i18n/resources.

For migrated screens and components, use useTranslation() and pass translated text into UI primitives. Low-level primitives such as `` do not import translation state unless they own the text they render.

Keep resource keys grouped by product surface, not component mechanics.

Run:

bash

npx vitest run packages/app/src/i18n/resources.test.ts --bail=1

The parity test catches missing keys across English and every supported locale resource.

Forge-Variant Copy

Strings that vary by git forge follow a two-tier rule:

Indeclinable tokens — brand names ("GitHub", "GitLab"), the PR/MR initialism, number prefixes (#/!) — are interpolated into a single key ("Refresh git and {{brand}} state"). These tokens stay latin and uninflected in every supported locale, so one string per locale suffices. The value comes from the forge manifest via getForgePresentation.
Sentences containing the full change-request noun ("pull request" / "merge request" inflects and takes gender/case in translation) use the i18next context mechanism: the base key carries the pull-request wording and an _mr sibling carries the merge-request wording (pullRequest / pullRequest_mr). Call sites pass t(key, { context: getForgePresentation(forge).changeRequestContext }); an undefined or unknown context falls back to the base key.

Keys scale per vocabulary family (PR vs MR), not per forge: a new forge picks an existing family in its manifest entry and needs zero locale edits.

Migration Order

Client UI translation is staged so each pass can migrate complete local copy clusters and keep reviews focused.

App shell and shared UI chrome: common actions, headers, sheets, command center, and client-owned toast status.
Composer and agent workflow: composer input, agent controls, permission prompts, plan approval, and agent panel wrapper states.
Settings expansion: Appearance, Shortcuts, Integrations, Permissions, Diagnostics, About, Project settings, Host settings, and provider diagnostics.
Workspace and panels: setup/file/browser/terminal wrapper copy, file explorer local states, import-session flows, and remaining local toast/error wrapper text.

Within a migrated surface, do not leave mixed-language neighboring labels when those labels are owned by the client. Move the whole local copy cluster together.

Progress

Batch 2 migrated Composer and agent workflow chrome: Composer input and attachments, agent controls, stream permission prompts, agent panel wrapper states, and draft panel descriptors. Provider/model names, provider-defined option labels, agent output, and protocol/server diagnostics remain untranslated.
Batch 3A migrated Settings Diagnostics/About, Appearance, Shortcuts, Integrations, and Desktop Permissions chrome. Host settings and Project settings remain for Batch 3B; raw runtime status/error details remain untranslated.
Batch 3B migrated Host settings, Provider diagnostics, and Project settings chrome. Provider/model names, project/host labels, script commands, diagnostic output, file paths, and raw runtime/server error details remain untranslated.
Batch 4A migrated workspace wrapper chrome for import sessions, file explorer, setup, browser, terminal, and file panels. File paths, URLs, commands, logs, terminal output, provider labels, and raw runtime/server errors remain untranslated.
Batch 4B migrated workspace tab shell, workspace scripts, Git actions/diff/PR chrome, worktree archive warnings, Open-in-editor controls, and inline review controls. Branch names, PR titles/bodies, check names, workflow names, file paths, diff contents, commands, terminal output, provider labels, and raw runtime/server errors remain untranslated.
Batch 4C migrated Sidebar project/workspace menus, hide/remove/archive confirmations, workspace rename chrome, New workspace ref picker/create flow, and Open project home tiles. Workspace/project names, branch names, PR titles, paths, provider labels, daemon output, and raw runtime/server errors remain untranslated.
Batch 4D migrated provider/model selector chrome, provider catalog install modal, add-connection method modal, and paste-pairing-link modal. Provider/model/catalog names, provider descriptions, pairing URLs, protocol parser errors, daemon connection details, and raw runtime/server errors remain untranslated.
Batch 4E migrated onboarding welcome chrome, direct-connection modal fields/actions/local failure guidance, QR scan permission/unavailable states, and desktop pair-device card. Pairing URLs, host/port placeholders, endpoint values, transport details, protocol parser errors, and raw runtime/server errors remain untranslated.
Batch 4F migrated realtime voice overlay accessibility labels, rewind menu chrome and fallback toast, DiffViewer default empty state, and service URL chooser copy. Shortcut key names, raw daemon errors, diff contents, URLs, and caller-provided override labels remain untranslated.
Batch 4G migrated the keyboard shortcuts help dialog to render section titles, row labels, and row notes through translation keys. Shortcut key names, shortcut combos, binding IDs, action IDs, and fallback registry labels remain untranslated.
Batch 4H migrated Sessions screen chrome and AgentList local UI copy: date section headers, local status labels, fallback session titles, badges, load-more/empty states, and the archive action sheet. Agent titles, project paths, provider icons/labels, host labels, relative timestamps, and raw runtime data remain untranslated.
Batch 4I migrated message utility chrome: image lightbox labels/errors, code and turn copy accessibility labels, dictation controls, question form fallback placeholders/actions, PlanCard fallback title, assistant image fallback errors, and todo list labels. Message bodies, plan text, todo item text, attachment labels, runtime dictation errors, and agent/tool output remain untranslated.
Batch 4J migrated workspace tab toast/empty chrome: copy failure messages, copied labels, resume-command availability errors, reload-agent local status, host-disconnected wrapper reuse, and split-pane empty state. Agent IDs, generated resume commands, workspace paths, branch names, and raw reload errors remain untranslated.
Batch 4K migrated sidebar/project list chrome: host picker fallback/search/title, footer actions and tooltips, Sessions row labels, mobile close label, New workspace tooltip/accessibility label, project-list empty states, and project settings host-load wrapper text. Host names, project names, workspace names, paths, branch names, and raw host errors remain untranslated.
Batch 4L migrated picker/file/detail utility chrome: project picker states, branch switcher labels/placeholders, file pane loading/empty/fallback errors, tool-call details section/empty labels, and open-file accessibility. Directory paths, branch names, file contents, file sizes, tool details, and raw file-load errors remain untranslated.
Batch 4M migrated hook/modal utility chrome: image attachment permissions/dialog/errors, copied toast wrappers, rename modal local validation/fallback errors, branch switcher stash/switch prompts and fallback toasts, and workspace setup local fallback errors. Copied labels supplied by callers, branch names, selected paths, raw dialog/API errors, and raw server errors remain untranslated.
Batch 4N migrated pure view-model/policy utility chrome: import-session fallback titles/previews/empty states and the worktree setup callout. Provider labels and IDs remain runtime values interpolated into translated wrappers.
Batch 4O migrated remaining small utility chrome: workspace route gate states/actions, compaction markers, archived-agent callout, web browser fallback, desktop quitting overlay, and image drop overlay. Host names, host status values, browser IDs, token counts, and raw route errors remain runtime values.
Batch 4P migrated provider-selection pure view-model utility copy to direct i18n.t(...) calls and removed the local labels parameter path. Provider/model labels, provider IDs, and provider snapshot error messages remain runtime values.
Batch 4Q migrated desktop update utility chrome: app update status text, update callout titles/actions, generic update errors, and install-error wrappers. Version labels, installer messages, raw update errors, release-channel data, and logs remain runtime values.
Batch 4R migrated desktop permission utility chrome: permission status details, permission request fallback errors, empty permission statuses, and desktop notification test wrappers. Browser permission states, exception names, and raw browser API error messages remain runtime values.
Batch 4S migrated desktop daemon settings chrome: built-in daemon status rows, daemon lifecycle toggles, logs/status modals, clipboard alerts, daemon management confirmations/errors, daemon status load errors, and desktop CLI/skills install wrapper errors. PIDs, log paths, log contents, CLI status output, version values, and raw IPC errors remain runtime values.
Batch 4T migrated remaining attachment/autocomplete utility chrome: user and composer review attachment labels, workspace hover-card accessibility, branch stash restore prompts/toasts, agent autocomplete loading/empty/fallback error text, older-history fallback toast, draft panel labels, and agent-control fallback labels. PR/issue numbers, browser element tags, branch names, provider labels, model labels, agent prompts, command/file names, and raw server errors remain runtime values.
Batch 4U migrated shared default utility chrome: Combobox and Autocomplete default placeholders/empty/loading labels, drag-overlay and subagent-track loading labels, sub-agent activity fallback headers, and file-preview fallback errors. Caller-provided labels, tab titles, subagent descriptions, file paths, and raw file-load errors remain runtime values.
Batch 4V migrated Git policy action chrome to direct i18n.t(...) calls: commit/pull/push/sync/PR/merge/auto-merge/archive action labels, pending/success labels, and unavailable reasons. Branch/base refs, PR URLs, GitHub merge-state enum values, runtime statuses, and raw Git/GitHub errors remain runtime values.
Batch 4W migrated remaining local wrapper states: workspace copy unavailable toasts, startup daemon-log loading/empty/load-failed text, and file-explorer workspace/host unavailable fallbacks. Workspace paths, branch names, daemon log contents/paths, checkout query details, and raw file/daemon errors remain runtime values.
Batch 4X migrated descriptor and command chrome: Pair-device modal header, workspace setup sheet title, terminal panel fallback labels, command-center action titles, and file-pane host-disconnected fallback. Provider/catalog names, command-center search keywords, terminal runtime titles, file paths, and raw read errors remain runtime values.
Batch 4Y tightened the translation boundary so React components and custom hooks use useTranslation() while pure helpers keep direct i18n.t(...) fallbacks, and migrated remaining small UI/accessibility fallbacks across message details, menu backdrops, startup errors, sidebar PR badges, settings/project accessibility labels, composer send/create/download fallbacks, client slash-command descriptions, terminal subscribe errors, and desktop update completion text. Provider catalog metadata, shortcut registry fallbacks, agent/daemon/protocol reasons, terminal contents, raw runtime errors, and user/project/workspace names remain untranslated.
Batch 4Z expanded the supported locale set to the six UN official languages: Arabic, Chinese, English, French, Russian, and Spanish. Arabic, French, Russian, and Spanish now have full client-owned UI resource coverage, with key parity, fallback-ratio, and interpolation-placeholder tests guarding the generated translations. Arabic does not enable RTL layout direction in this batch.
Batch 5A added Brazilian Portuguese (pt-BR) resource coverage, language selector labels, i18next registration, and system-locale mapping for pt-BR and bare pt. Non-Brazilian Portuguese regional locales remain unsupported until a matching resource is added.
Batch 5B added Korean (ko) resource coverage, language selector labels, i18next registration, and system-locale mapping for ko and Korean regional locales.

Markdown Renderer (`docs/markdown-renderer.md`)

Markdown rendering

Use MarkdownRenderer for chat replies, file previews, plans, pull requests and changelog content. It uses react-native-enriched-markdown on iOS, Android and web. Keep source adaptation and renderer configuration in components/markdown; consumers supply Markdown and, when needed, its file location.

Native selection belongs to the library's text view. Keep an assistant message in one row so selection can cross paragraphs, headings and lists. Code blocks and tables use the library's native views and their selection behavior. Web uses browser selection over semantic HTML. Once its WASM parser is initialized, the library parses synchronously for the first commit of each mounted row; an empty interim row would corrupt virtualized measurements and move the reader. Chat owns paced reveal, the web render cap, message identity and list measurement. Native renders completed messages together. While streaming, it keeps closed blocks in one head view and updates a separate tail, then reunites the text on completion. See native parsing cost for the boundary and pacing constraints.

Block spacing

Every block is separated by one gap, density.blockGap: 12 on compact layouts, 16 wider. Inside the library's text, every element style ends with that gap and the library drops it after the last block. Views stacked outside the library (Mermaid segments, streaming head and tail) use the same gap through MarkdownBlockStack. Do not give a block type its own margins; change the gap.

Links and images

Workspace file links use the shared file-link resolver. The workspace supplies its client, root and open-file action once; chat can supply the agent's more specific context. URLs use the same link press path. Recognized inline-code paths stay tappable. The library callback carries the tapped occurrence’s syntax context. Preserve it when opening files: explicit Markdown links decode URL escapes, while recognized inline-code paths preserve literal percent characters and use suffix lookup. Identical URL strings in different occurrences must stay distinct. Explicit absolute workspace links receive a relative hover title; existing authored titles remain intact.

Resolve workspace image paths over the existing session RPC, then give the library a cached native file URL or web blob URL. HTTP(S) images pass through unchanged. This preserves relay, SSH and local socket connections, which do not expose a daemon HTTP endpoint. Each mounted renderer owns its image acquisition identity, so a later reply reads a rewritten path again while the earlier mounted reply retains its snapshot. Image taps open the attachment lightbox. File previews resolve relative images against the Markdown file's directory. An image alone on its line becomes its own paragraph before the library sees it, so it renders as a block on every platform; the library only treats sole-child paragraph images as blocks, and with hard soft breaks every newline is a break node, which left own-line images inline on iOS and web. Images that share a line with text stay inline.

Engine constraints

The pinned nightly has the same React Native package and core source trees as upstream commit 73ac5085eb1fdc743973b3473d4dba65abad5261. Compatibility was checked with React Native 0.81.5. Native dependencies must be rebuilt when changing the highlighting configuration; JavaScript refresh cannot enable compiled grammars.

Math and video are disabled. Task lists and admonitions are enabled; task checkboxes are read-only. Source adaptation spaces adjacent empty GFM table delimiters before escaping prose spoiler delimiters and decodes entity text before the engine can discard it. Code spans and fences keep their literal source. Comment HTML is normalized to Markdown before parsing; details show their summary and body expanded.

Mermaid fences use the existing isolated diagram runtime and fullscreen viewer. Web dispatches them through the library’s code-block override. Native has no block-renderer hook, so the renderer extracts only Mermaid fences and places the existing WebView host between library-rendered segments. This is the only block exception; see native selection limitations for diagram grouping and leading inline images. Streaming keeps the last valid diagram visible while the next revision renders.

Native code blocks use the library's copy control and compiled grammars. Web code blocks use HighlightedCodeBlock through the library's renderers.codeBlock override. The patch also keeps the library's block spacing around the web code block override, preserves web list numbering and link titles, marks pending parses with aria-busy so Find waits for rendered text, and carries link syntax through native and web tap events. Web inline code inside a link inherits only the link colour; its code font, size and background stay intact. Keep link variants colour-only: native pills replace text runs and prevent paths from wrapping; Android pills also use the surrounding block’s font size. The package patch is tracked by upstream PR #997; remove the patch when the pinned release includes it.

The package patch also keeps overflowing native horizontal blocks in control of their drags: Android claims parent interception at touch-down and releases it for vertical drags so the chat list can scroll; iOS keeps its scroll recognizer active for outward drags at the leading edge. This prevents compact sidebar pans from taking block scrolling without changing sidebar swipes on prose or non-overflowing blocks. Native changes require a client rebuild.

Android measurements use a size-only, 512-entry LRU across view unmounts, matching the library’s existing iOS cache. Scrolling back through history can reuse layout sizes without parsing those rows again. Content, layout props and width identify each entry; font-scale changes and native layout invalidation discard affected sizes. The cache retains no views or spans.

The library determines how incomplete Markdown appears during streaming. Completed text uses the same component and engine as history. Find and scroll-to-message address source message ids; selection-copy understands semantic HTML and the web code component's copy metadata.

Verification

Follow QA and mobile testing. Exercise chat, file preview, plan and PR content on all three platforms. Include cross-paragraph selection, progressive streaming, a file-link tap, code copy/highlighting, a table and a workspace image. On iPad, repeat preview selection after opening and closing Explorer and after rotation. Check web find, selection-copy and source-message navigation after DOM changes.

Menus (`docs/menus.md`)

Menus

One engine, in packages/app/src/components/ui/menu/. dropdown-menu.tsx and context-menu.tsx
are wrappers over it and differ only in what opens them — a press, or a long press / right click.
Import the DropdownMenu* or ContextMenu* names as before; reach for @/components/ui/menu
directly only when you are building a third trigger shape.

Do not add a third menu implementation. The two that existed were byte-identical from
computePosition down, and the copies drifted: only one of them ever grew a sheet.

Two presentations

MenuRoot picks one from form factor, never from platform — a tablet in a narrow split view
sheets the same way a phone does.

Screen	Surface	Submenus
Wide	Popover anchored to the trigger	Flyout overlapping the row, opened by hover intent
Compact, `compactMode="sheet"`	Bottom sheet	The page is replaced in place, with a back header
Compact, default	Popover	Same as wide

compactMode defaults to "popover", so adopting the sheet is per-menu. That is deliberate:
flipping every menu in the app to sheets at once is not a change anyone can review. Opt a menu in
when you have actually looked at it on a phone.

ContextMenu is the exception: it defaults to compactMode="sheet" and enables native long press.
Disable mobile triggering explicitly on draggable rows, where long press belongs to drag instead.

When the items differ per form factor

A menu whose contents depend on what else is on screen gets one component per surface, not one
component with isMobile branches inside it. The workspace header menu is the example
(packages/app/src/screens/workspace/workspace-header-menu.tsx): compact has no tab strip, so it
carries new-tab actions, while wide leaves those to the strip's + menu and lists workspace
actions only. Items both surfaces share live in one component that each menu renders, from the same
callbacks, so the two can't drift.

Selecting an item on iOS

An item that closes the menu runs its action after a fixed grace period on iOS, not immediately:
a native presenter launched while UIKit is still tearing down the surface can hang. Both surfaces
unmount the moment the menu closes, so the wait is a timer rather than the surface's own dismissal
callback — a callback fired from inside a subtree that is being removed is racing its own removal,
and it loses. Selections used to be dropped entirely for exactly that reason.

The consequence for callers: an onSelect on iOS runs a beat after the press. Don't add a second
delay on top of it, and don't read state that the same press mutated.

This is why a row inside a menu surface goes through selectItem rather than calling its handler
from its own Pressable. MenuItem is not the only row shape on the engine — ComposerTrackRow
is another, with its own icons and hover-revealed actions — but both hand the press to the engine
and take closeOnSelect to say whether choosing them ends the surface. A row that owns its press
outright leaves the surface open behind whatever it opened, and skips the iOS wait.

A row whose result opens a sheet passes closeOnSelect={false}: the sheet stacks over the menu
sheet and uncovers it on close, so the menu is where the user lands next. A row that opens a tab
closes, because the tab replaces the pane the menu belongs to. The subagents track asks the layout
store which one a row is (useSubagentOpensInSheet), since the answer changes with the layout.

Pages

A submenu is a page, declared as data on the surface and reached by a MenuSubTrigger whose id
matches:

tsx

<MenuSurface pages={pages} sheetTitle="Display">
  <MenuSubTrigger id="grouping" value="Project">
    Grouping
  </MenuSubTrigger>
</MenuSurface>

Pages are data rather than nested children because the popover renders them as siblings of the
root surface — a flyout nested inside the root's box would be clipped by its overflow: hidden.
Declaring them separately is what lets one model drive both presentations.

menu-navigation.ts holds that model, and it is pure: the open flyout chain and the mobile push
stack are the same path, so the popover renders every entry in it and the sheet renders only the
last. Nothing else differs between the two.

Opening a submenu truncates the path to the depth of the trigger that opened it. Without that,
sliding the pointer across a row of triggers would stack up every flyout it passed instead of
swapping between them.

A page that takes input

A menu page can hold a small form — MenuTextField is the field for it, drawn as a row's own
fill so its text lands on the same rail as the labels above it. Two things have to be true for
that page, and both are set on the page definition rather than discovered later:

hoverIntent: false. A branch you skim is opened and closed by the pointer; a form is not.
Without this the page opens on a pointer that was only passing through, and dismisses itself —
draft and all — the moment your hands move to the keyboard and the mouse drifts off the flyout.
While such a page is open, the whole surface stops closing on hover, because the parent flyout
leads back to the same dismissal.
The compact presentation has to be a sheet. MenuTextField resolves to
BottomSheetTextInput on compact native, which reads the sheet's context and has none in a
popover.

The sheet keeps keyboardBehavior="interactive". extend grows a sheet to its largest snap
point, and with enableDynamicSizing that point is the content's own height — a short page does
not grow, and the keyboard comes up over the field you are typing into.

Hover intent

A flyout overlaps its parent by 5pt rather than sitting beside it. With a gap there is a strip
of backdrop between the two that belongs to neither surface, and every pixel of it is a chance to
dismiss the menu you are reaching for. Overlapping deletes the strip; don't reintroduce the gap
and try to cover it with a longer timer.

On top of that, a flyout opens after the pointer rests ~90ms, closes ~260ms after it leaves, and
cancels its own pending close while the pointer is inside it. The grace still matters because the
pointer crosses sibling rows on the way down into the flyout.

Hover lives on a plain View, never on a Pressable — see hover.md, which owns that
rule. Hover only fires on web, which is exactly where flyouts exist; everywhere else the page
opens on press.

Item states

selected and active are different questions and must not be merged.

Prop	Means	Draws
`selected`	This is the chosen value	A check, and nothing else
`active`	This row's submenu is open	The fill, and no check

selected also announces itself as aria-checked, so a multi-select page is audible as the list
of on/off things it is.

A selected row does not get a background. A check and a fill are two separate claims about the
same state, and showing both makes a chosen row compete with the row the pointer is actually on.
showSelectedCheck moves the check to a reserved leading column when a group needs to stay
aligned whether ticked or not; otherwise it sits at the trailing edge and the leading slot is free
for the option's icon.

Give options icons; leave the root rows without them. The root is labels and their current values,
and a column of icons there is decoration competing with the values you actually came to read.

Surface details

The hover fill is inset from the surface's edges and rounded — a chip inside the menu, not a
band across it. The inset is taken out of the row, never added to it: padding gives up what
margin takes, so labels sit at the same 13pt they always did. Insetting by growing the row is how
the menu ends up taller than it started.
A row is as tall as what is driving it — 28pt for a pointer, 40pt below md for a thumb. The
split is on breakpoint, not on presentation: the compact popover that compactMode defaults to
is worked with a thumb just as a sheet is, and sizing off the sheet would leave it at the desktop
height. md is where useIsCompactFormFactor divides, so row height and the popover/sheet choice
turn over together.
The desktop height only holds because the label's lineHeight is pinned — 18 line + 8 padding +
2 border is exactly 28. Leave it to the platform and content outgrows minHeight, which then does
nothing. Compact is the other way round: minHeight leads and the label centres in it.
A row owns its fill; MenuPage owns the spacing between rows. The vertical inset above the
first row and below the last, and the gap between rows, are the page's — one knob each,
MENU_ROW_GAP being the one a redesign turns. A row that carried vertical margin would be
serving both at once, and since margins don't collapse it would land as one unit at the edges and
two between rows, so shrinking the gap would eat the inset with it. Horizontal inset does stay on
the row: there is one left edge and one right edge, so nothing is doubling up.
MenuPage is also what provides a page's depth, so the popover and the sheet cannot disagree
about what a page is. Every entry point goes through it — root, flyout, pushed sheet page.
The gap reaches a page's direct children. A group of rows wrapped in a View of its own drops
out of it; at the current gap of zero there is nothing to lose, but anything above zero wants that
wrapper to carry the page style too.
The separator is the one row-level thing that asks for vertical space of its own, and now that
rows carry none, that is still one number controlling one gap. It takes no horizontal margin and
the page has no horizontal padding, so the rule runs the full width of the surface.
Separators use borderAccent, the same colour the surface outlines itself with. border sits
between surface1 and surface2, which put it within a hair of the hover fill and made
separators disappear against a hovered row.

When a decision earns a submenu

Put a decision behind a submenu

Docker & Self-Hosted Deployment Verified OCI

Technical Documentation: getpaseo/paseo

Overview (`README.md`) Copy Section

Paseo

Sponsors Copy Chapter

Plugins Copy Chapter

Getting Started Copy Chapter

Prerequisites Copy Section

Desktop app (recommended) Copy Section

Server Copy Section

Docker Copy Section

CLI Copy Chapter

TypeScript SDK Copy Chapter

Skills Copy Chapter

Development Copy Chapter

Support Paseo Copy Chapter

Related projects Copy Chapter

License Copy Chapter

Overview (`docker/README.md`) Copy Section

Paseo Docker Image

Overview (`packages/app/README.md`) Copy Section

Welcome to your Expo app 👋

Get started Copy Chapter

Get a fresh project Copy Chapter

Learn more Copy Chapter

Join the community Copy Chapter

Dictation debugging Copy Chapter

Overview (`packages/client/README.md`) Copy Section

@getpaseo/client

Runtime Copy Chapter

Stability Copy Chapter

Overview (`packages/expo-two-way-audio/README.md`) Copy Section

Speechmatics Two Way Audio

Installation Copy Chapter

Usage Copy Chapter

Notes Copy Chapter

Overview (`packages/protocol/README.md`) Copy Section

@getpaseo/protocol

Stability Copy Chapter

Overview (`packages/server/README.md`) Copy Section

Voice Assistant

Quick Start Copy Chapter

Architecture Copy Chapter

Development Copy Chapter

Project Status Copy Chapter

Environment Variables Copy Chapter

Tech Stack Copy Chapter

Testing Copy Chapter

License Copy Chapter

Overview (`packages/website/README.md`) Copy Section

Paseo website

Plugin install counts Copy Chapter

Overview (`plugin-examples/agent-configuration/README.md`) Copy Section

Agent configuration

Overview (`plugin-examples/buttons/README.md`) Copy Section

Header buttons and composer pills

Overview (`plugin-examples/catppuccin/README.md`) Copy Section

Catppuccin plugin example

Overview (`plugin-examples/inline-thinking/README.md`) Copy Section

Inline thinking timeline example

Overview (`plugin-examples/lifecycle-actions/README.md`) Copy Section

Lifecycle actions

Overview (`plugin-examples/lifecycle-logger/README.md`) Copy Section

Lifecycle logger

Overview (`plugin-examples/linear/README.md`) Copy Section

Linear plugin example

Overview (`plugin-examples/markdown-panel/README.md`) Copy Section

Markdown file panel example

Overview (`plugin-examples/modal-ui/README.md`) Copy Section

Modal UI example

Overview (`plugin-examples/pdf-panel/README.md`) Copy Section

PDF file panel example

Overview (`plugin-examples/provider-acp-transformer/README.md`) Copy Section

ACP provider transformer example

Overview (`plugin-examples/provider-direct/README.md`) Copy Section

Direct provider example

Overview (`plugin-examples/settings/README.md`) Copy Section

Settings example

Overview (`plugin-examples/timeline-items/README.md`) Copy Section

Pi tasks timeline plugin example

Overview (`README.md`)

Sponsors

Plugins

Getting Started

Prerequisites

Desktop app (recommended)

Server

Docker

CLI

TypeScript SDK

Skills

Development

Support Paseo

Related projects

License

Overview (`docker/README.md`)

Overview (`packages/app/README.md`)

Get started

Get a fresh project

Learn more

Join the community

Dictation debugging

Overview (`packages/client/README.md`)

Runtime

Stability

Overview (`packages/expo-two-way-audio/README.md`)

Installation

Usage

Notes

Overview (`packages/protocol/README.md`)

Stability

Overview (`packages/server/README.md`)

Quick Start

Architecture

Development

Project Status

Environment Variables

Tech Stack

Testing

License

Overview (`packages/website/README.md`)

Plugin install counts

Overview (`plugin-examples/agent-configuration/README.md`)

Overview (`plugin-examples/buttons/README.md`)

Overview (`plugin-examples/catppuccin/README.md`)

Overview (`plugin-examples/inline-thinking/README.md`)

Overview (`plugin-examples/lifecycle-actions/README.md`)

Overview (`plugin-examples/lifecycle-logger/README.md`)

Overview (`plugin-examples/linear/README.md`)

Overview (`plugin-examples/markdown-panel/README.md`)

Overview (`plugin-examples/modal-ui/README.md`)

Overview (`plugin-examples/pdf-panel/README.md`)

Overview (`plugin-examples/provider-acp-transformer/README.md`)

Overview (`plugin-examples/provider-direct/README.md`)

Overview (`plugin-examples/settings/README.md`)

Overview (`plugin-examples/timeline-items/README.md`)

Overview (`packages/app/maestro/README.md`)

iOS Sidebar Close Regression

iOS Sidebar Drag Cancellation Regression

New Workspace Android Flow

Overview (`packages/client/examples/README.md`)

Overview (`packages/protocol/codegen/README.md`)

Overview (`packages/app/modules/paseo-diff-prototype/README.md`)

Diagnostic interface

Overview (`packages/expo-two-way-audio/examples/basic-usage/README.md`)

Requirements

Run the app

Notes

Overview (`packages/expo-two-way-audio/examples/flow-api/README.md`)

Requirements

Run the app

Notes

Overview (`packages/app/e2e/mobile/composer-overlay/README.md`)

Overview (`packages/app/e2e/mobile/diff-tree/README.md`)

Reproduce the row shadow

Recorded verification

Overview (`packages/app/e2e/mobile/modal-sheet/README.md`)

Compact sheet gestures

Recorded verification

Tablet model selection