Paseo

Paseo — Agent Orchestration Platform

One interface for Claude Code, Codex, and OpenCode. Self-hosted daemon. CLI, mobile, desktop, web. By getpaseo/paseo (6.2k⭐).

Skills Indexed (7)

Auto-discovered via remote_repo from getpaseo/paseo:

sc skills search "handoff" --provider paseo
sc skills get paseo:paseo-handoff
sc skills get paseo:paseo-loop
sc skills get paseo:paseo-advisor
sc skills get paseo:paseo-committee
sc skills get paseo:paseo-epic
sc skills get paseo:paseo-orchestrate

Quick Start

npm install -g @getpaseo/cli
paseo daemon start                     # Start daemon
sc paseo daemon status                 # Check health
sc paseo agent run --detach "fix bug"  # Deploy agent
sc paseo agent list                    # List agents

Commands

Daemon

• sc paseo daemon start [flags] — start daemon (--port, --listen, --home, --foreground, --no-relay, --no-mcp, --no-inject-mcp)
• sc paseo daemon stop — stop daemon
• sc paseo daemon status — check daemon health
• sc paseo self version — print version
• sc paseo self mcp — register MCP server

Agent

• sc paseo agent run <prompt> — run agent with task (--detach, --title, --provider, --model, --thinking, --mode, --worktree, --image, --cwd, --label, --wait-timeout, --output-schema)
• sc paseo agent list [-a] — list agents (include archived)
• sc paseo agent send <id> [msg] — send message (--prompt, --prompt-file, --image, --no-wait)
• sc paseo agent logs <id> — view logs (--follow, --tail, --filter, --since)

Global Flags

• --host <host> — connect to remote daemon
• --json — JSON output
• -q, --quiet — minimal output

Requirements

• Node.js 18+
• npm install -g @getpaseo/cli (500+ deps, ~2 min install, proprietary license)
• At least one agent CLI: Claude Code, Codex, or OpenCode

Setup Guide

1. Install

npm install -g @getpaseo/cli

The install takes ~2 minutes with 500+ dependencies. Heavy but expected for agent orchestration.

2. Verify the CLI binary

paseo --version
# → 0.1.76

Caveat: If you also have the Paseo desktop AppImage installed, check that which paseo points to the CLI at ~/.nvm/versions/node/.../bin/paseo, NOT a desktop AppImage symlink at ~/.local/bin/paseo. The AppImage will fail with error: unknown command '...supervisor-entrypoint.js'.

3. Start the daemon

paseo daemon start --port 6767

The daemon starts in background automatically (daemonizes). Check status:

paseo status

4. Verify providers

The daemon auto-detects available agent CLIs:

Providers
  Claude   /path/to/claude (2.1.128)
  Codex    /path/to/codex  (0.112.0)
  OpenCode /path/to/opencode (1.14.50)

Voice / Speech Configuration

Config File

Edit ~/.paseo/config.json:

{
  "version": 1,
  "features": {
    "dictation": {
      "stt": { "provider": "local", "model": "parakeet-tdt-0.6b-v3-int8", "language": "en" }
    },
    "voiceMode": {
      "llm": { "provider": "claude", "model": "haiku" },
      "stt": { "provider": "local", "model": "parakeet-tdt-0.6b-v3-int8", "language": "en" },
      "tts": { "provider": "local", "model": "kokoro-en-v0_19", "speakerId": 0 }
    }
  },
  "daemon": {
    "listen": "127.0.0.1:6767",
    "mcp": { "injectIntoAgents": false },
    "autoArchiveAfterMerge": false,
    "cors": { "allowedOrigins": ["https://app.paseo.sh"] },
    "relay": { "enabled": true }
  },
  "app": { "baseUrl": "https://app.paseo.sh" },
  "agents": {
    "providers": {
      "copilot": { "enabled": false },
      "opencode": { "enabled": false },
      "codex": { "enabled": false }
    }
  }
}

Model Auto-Download

Models download automatically on daemon startup. The download is async — the daemon starts serving immediately and downloads in background.

Available models:

• parakeet-tdt-0.6b-v3-int8 — STT (speech-to-text), ~650MB
• kokoro-en-v0_19 — TTS (text-to-speech), ~30MB
• silero-vad — Voice Activity Detection, bundled

Storage path: ~/.paseo/models/local-speech/

To verify a model completed:

ls ~/.paseo/models/local-speech/
# Should see: kokoro-en-v0_19  sherpa-onnx-nemo-parakeet-tdt-0.6b-v3-int8  silero-vad

Verifying speech services

Check the daemon log for successful initialization:

grep "initialized\|completed" ~/.paseo/daemon.log | grep speech
# → Sherpa offline recognizer initialized
# → Sherpa offline TTS initialized
# → Speech provider reconciliation completed

All 4 services should show as local:

effectiveProviders: dictationStt=local, voiceStt=local, voiceTts=local, voiceTurnDetection=local

Daemon Management

Start

nohup paseo daemon start --port 6767 --foreground > ~/.paseo/daemon.log 2>&1 &

Stop

paseo daemon stop

Status

paseo status

Restart (for config changes)

Config is read at daemon startup. Changes to ~/.paseo/config.json require a restart:

paseo daemon stop && sleep 2 && paseo daemon start --port 6767

Logs

tail -f ~/.paseo/daemon.log

Web UI

Open https://app.paseo.sh in a browser. The web app connects to your local daemon automatically if running on the same machine.

For remote access via QR code/pairing: the daemon connects to wss://relay.paseo.sh:443 which enables the mobile app and remote desktop clients.

Caveats & Pitfalls

1. Voice features require audio hardware

app.paseo.sh and the desktop app show "requested device not found" if the machine lacks a microphone/speaker. This is a browser WebRTC limitation on headless servers. Voice mode (dictation, voice STT, voice TTS) only works on machines with actual audio hardware (laptops, phones).

2. AppImage overrides CLI binary

If you install both the Paseo desktop AppImage and the npm CLI, ~/.local/bin/paseo may symlink to the AppImage. The AppImage cannot run CLI commands like daemon start. Fix:

rm ~/.local/bin/paseo
# Now `which paseo` should resolve to the npm CLI binary

3. Model download can be slow

STT models are 650MB. First daemon startup will show STT/TTS as "unavailable" until downloads complete. This is normal — check `/.paseo/models/local-speech/.downloads/` for progress. The daemon continues working for non-voice features during download.

4. Model version matters

The config specifies model ID parakeet-tdt-0.6b-v3-int8. If the wrong version is specified (e.g. v2), the daemon will download the missing one automatically. But old downloaded versions accumulate in ~/.paseo/models/local-speech/ — clean up manually.

5. Config change requires restart

The daemon reads ~/.paseo/config.json only at startup. Edited config while running? Stop and restart.

6. Agents disabled via config must restart

Disabling providers ("opencode": {"enabled": false}) takes effect after daemon restart. The daemon detects installed CLIs on startup.

7. 500+ npm dependencies

npm install -g @getpaseo/cli is slow (~2 min) and pulls in heavy packages like @anthropic-ai/claude-agent-sdk, @agentclientprotocol/sdk, sherpa-onnx (speech models). Expected for an agent orchestration platform.

8. Web UI serves WebSocket, not HTTP

The daemon listens on :6767 for WebSocket connections. It does NOT serve an HTTP web UI. The web UI is at https://app.paseo.sh — it connects to your daemon via WebSocket.

9. GPU requirements for speech models

The sherpa-onnx STT model may need GPU acceleration for real-time performance. The daemon shows VAAPI version too old on machines without GPU support — speech works but may be slower.

10. MCP server registration

sc paseo self mcp registers the Paseo MCP server in ~/.supercli/mcp.json. The MCP server runs as a subprocess of the daemon and is accessible at localhost:6767/mcp/agents.

11. Voice Mode vs Dictation Mode — Critical Difference

Paseo has two different voice features:

Dictation mode only transcribes your speech to text. The agent responds as text (no audio). This is useful for hands-free text input but the agent never speaks.

Voice mode is full-duplex: you speak → STT transcribes → agent receives spoken input with instruction to use the "speak" tool → agent calls speak tool → TTS synthesizes response → audio played to you.

In the desktop/web UI, the microphone icon toggles dictation, while the voice mode toggle (often labeled "Voice" or a separate icon) enables full voice mode. If you only see text responses, make sure you've activated voice mode specifically, not just dictation.

12. Speak Tool Requires Agent Created AFTER Voice Mode Activation

The "speak" MCP tool that allows the agent to output speech is ONLY registered when:

1. Voice mode is enabled via set_voice_mode { enabled: true }
2. AND a new agent is created after that point

If you toggle voice mode ON but continue chatting with an already-running agent, that agent's MCP server was initialized without enableVoiceTools: true and the speak tool is NOT available. The agent will respond with text because it has no way to speak.

Workflow to get agent speaking:

1. Open the desktop app
2. Turn voice mode ON first (not dictation)
3. Create a new agent / start a new conversation (don't reuse an existing one)
4. Speak — the new agent should have the speak tool

The daemon log confirms voice mode is enabled with:

set_voice_mode enabling voice for agent → agent enable complete → Voice mode enabled for existing agent

But if no audio_output messages appear in the session metrics, the speak tool was never registered for that agent.

13. No Config or CLI Flag for Auto-Enabling Voice Mode

There is no config flag in ~/.paseo/config.json to auto-enable voice mode at daemon startup. Voice mode must be activated per-session from the app UI. The set_voice_mode message is sent via WebSocket — there's no equivalent CLI command.

The relevant source code in session.ts:

// voice mode must be explicitly enabled per-session
case "set_voice_mode":
    return this.handleSetVoiceMode(msg.enabled, msg.agentId, msg.requestId);

14. Agent Must Support MCP Tool Calling

The speak tool is an MCP tool registered by the Paseo daemon's agent MCP server. The agent (Claude Code, Codex, OpenCode) must support calling MCP tools. Some smaller models (like Claude Haiku) may not reliably invoke the speak tool even when instructed by the system prompt.

The voice mode system prompt explicitly tells the agent:

"Always use the speak tool for all user-facing communication."

But if the model doesn't follow tool-use instructions consistently, it will fall back to text responses. For the best voice experience, use a larger model (Claude Sonnet, GPT-4o, etc.) via voiceMode.llm.model.

15. Proven Working Voice Mode Config

This config is confirmed to make the agent speak back properly:

{
  "features": {
    "voiceMode": {
      "llm": {
        "provider": "opencode",
        "model": "opencode-go/deepseek-v4-flash"
      },
      "stt": {
        "provider": "local",
        "model": "parakeet-tdt-0.6b-v3-int8",
        "language": "en"
      },
      "tts": {
        "provider": "local",
        "model": "kokoro-en-v0_19",
        "speakerId": 0
      }
    }
  },
  "providers": {
    "local": {
      "modelsDir": "/root/.paseo/models/local-speech"
    }
  }
}

Key differences from broken config:

• voiceMode.llm.provider set to opencode (not claude)
• voiceMode.llm.model set to opencode-go/deepseek-v4-flash (MCP-aware model)
• providers.local.modelsDir explicitly points to the speech models directory

Claude's Haiku model does not reliably call the speak tool. OpenCode with deepseek-v4-flash does.

Tips

• Start daemon first, then run agents
• Use --detach to run agents in background (foreground waits for completion)
• Use --provider codex/gpt-5.4 to specify both provider and model in one flag
• Combine with 7 Paseo skills for multi-agent workflows (handoff, loop, committee, advisor, epic)
• On a headless server, disable voice features in config to avoid startup warnings
• For remote daemon access: paseo --host workstation.local:6767 run "task"