hafuture

Guía de Paseo: Varios agentes de código IA en un workspace

Ejecuta Claude Code, Codex y OpenCode en paralelo con Git worktrees, móvil, CLI y orquestación multi-agente usando Paseo (paseo.sh). Guía completa.

PaseoAI Coding AgentsClaude CodeCodexGit WorktreeOrchestrationDeveloper Tools

Índice


1. ¿Qué es Paseo y qué necesitas antes?

Agentes como Claude Code, Codex, OpenCode o Gemini CLI ya editan código y ejecutan tests solos, pero suelen quedar encerrados en ventanas de terminal sueltas. Si lanzas dos tareas a la vez, es fácil mezclar ramas o perder resultados.

  • No te confundas: Paseo no es un modelo de IA. Envuelve los CLIs que ya instalaste e iniciaste sesión, conservando intactas tus suscripciones, configuraciones, servidores MCP y skills.

Requisitos previos

RequisitoDetalle
1+ CLI de código IATener instalado y autenticado Claude Code, Codex, OpenCode, Pi, Antigravity o Muse Code (si responde en tu terminal, está listo)
Git + Carpeta de proyectoEl trabajo paralelo usa Git worktrees, así que Git es prácticamente imprescindible
GitHub CLI (gh, recomendado)Permite abrir espacios por Pull Request y reconocer PRs
Node.js (solo versión CLI)No hace falta si instalas la app de escritorio

2. Tres formas de instalarlo

Elige el método de instalación de Paseo
App de Escritorio (★☆☆)

100% recomendada al empezar — daemon incluido

“Descarga, abre y listo”

Instalación
Descarga para tu SO en paseo.sh/download o GitHub Releases
Ventaja
Integra el motor en segundo plano (daemon) sin configuración extra
Móvil
Ajustes → Mi Host → Pair Device y escanea el QR
Servidor / CLI (★★☆)

Servidores remotos y flujos de terminal

“npm install -g @getpaseo/cli”

Instalación
Instalación global con npm y ejecuta paseo (datos en ~/.paseo)
Acceso remoto
Relay cifrado con QR, Tailscale, VPN o SSH
Web UI
Activable con paseo daemon config set features.webUi.enabled true
Docker / Autoalojado (★★★)

NAS y servidores domésticos siempre activos

“ghcr.io/getpaseo/paseo:latest”

Aviso
La imagen oficial no incluye CLIs de IA; añade los que quieras usar
Seguridad
Cambia PASEO_PASSWORD y usa HTTPS (Caddy/Nginx) antes de exponer
Primer paso
Comprueba primero http://localhost:6767 en local
bash
npm install -g @getpaseo/cli
paseo
Arranca el daemon y pregunta si activar el relay cifrado (emparejamiento QR). Los datos viven en PASEO_HOME (~/.paseo).

3. Tres palabras clave: Proyecto, Workspace y Sesión

La barra lateral de Paseo es una lista de lugares, no de chats. Recuerda Proyecto > Workspace > Sesión (Escuela → Aula → Estudiante):

  • Proyecto = Escuela: Registra un repositorio o carpeta sin copiarla. Borrarlo en Paseo jamás borra tu código local.
  • Workspace = Aula (Sala): Carpeta de trabajo donde ocurre la acción. Abrir un chat nuevo mantiene la sala intacta.
  • Sesión = Estudiante (Pestaña): Una unidad en ejecución (chat IA, terminal o navegador). Las sesiones de una sala comparten archivos, pero no memoria de chat.
Malentendido comúnRealidad
1 Workspace = 1 ChatFalso. Un workspace es una sala que aloja múltiples chats, terminales y pestañas de navegador a la vez.
Archivar borra mi códigoLas salas locales permanecen en disco. En salas worktree, archivar la última limpia esa carpeta temporal: revisa tus cambios antes.
Una sesión nueva continúa el chat previoVe los mismos archivos, pero arranca sin contexto previo. Pega un resumen o sigue en la sesión anterior.

4. Worktrees en paralelo y paseo.json

Imagina desarrollar ordenación de productos (sort-products) y mejora del login (login-polish) al mismo tiempo en my-app:

  1. 1
    Crea la primera sala worktree

    New workspace → Isolation: New worktree → Base: origin/main → elige tu agente (ej. Claude Code). Tu rama main original queda intacta.

  2. 2
    Indica qué hacer y cómo verificarlo

    Pide 'Añade orden por precio y nombre y ejecuta los tests relacionados' para obtener resultados verificables.

  3. 3
    Abre una segunda sala para una tarea independiente

    Crea login-polish desde my-app evitando solapar archivos (puedes incluso asignar otro modelo IA).

  4. 4
    Evita choques del puerto 3000 con paseo.json

    Define type: service usando $PASEO_PORT para que Paseo asigne puertos libres y URLs únicas como web--sort-products--my-app.localhost:6767.

json
{
  "worktree": {
    "setup": "npm ci",
    "teardown": "rm -rf .cache || true"
  },
  "scripts": {
    "test": { "command": "npm test" },
    "web": {
      "command": "npm run dev -- --port $PASEO_PORT",
      "type": "service"
    }
  }
}
Paseo lee el paseo.json commiteado en tu rama base (origin/main). Omite port y usa $PASEO_PORT para evitar conflictos.

5. Revisar diffs, móvil por QR y 7 comandos CLI

Comprobar antes de fusionar

  • Revisa los diffs en Changes (verde = añadido, rojo = eliminado) y pide ajustes puntuales.
  • Añade un agente revisor en la misma sala con New agent ("Revisa estos cambios sin editar archivos"). Recuerda: su visto bueno es solo una opinión—ejecuta npm test en Terminal y comprueba en la pestaña Browser antes de hacer commit.
  • Usa Cmd+K (Ctrl+K) para abrir el Command Center.

Continuar desde el móvil o por SSH

Un único daemon (puerto 6767) atiende a todos los clientes:

  • Relay móvil: En escritorio activa Ajustes → Mi Host → Pair a device → Enable relay y escanea el QR. Cifrado de extremo a extremo sin abrir puertos ni VPN; aunque cierres la app móvil, tu PC sigue trabajando.
  • Tailscale / SSH: Si el relay está bloqueado, usa Tailscale (tailscale ip -4 + puerto 6767) o conéctate a un servidor remoto con daemon activo mediante ssh://user@host.
Haz clic en cualquier comando CLI para copiarlo

Los 7 comandos esenciales de Paseo CLI

Servicios, proveedores y SSH remoto


6. Orquestación multi-agente, skills y plugins

Que una IA delegue en otra

  1. Activa Ajustes → Mi Host → Agents → Enable Paseo tools (apagado por defecto).
  2. Abre una sesión nueva para que el agente reciba las herramientas.
  3. Pide al agente principal lanzar un subagente revisor ("Lanza una segunda IA con Paseo para revisar esta rama sin tocar archivos"). Guarda Perfiles de Agente reutilizables y programa tareas con Schedules o Heartbeats.

Cuatro skills de orquestación integrados

Instálalos en Ajustes → Mi Host → Agents → Orchestration skills o con npx skills add getpaseo/paseo:

SkillCuándo usarlo
/paseoGuía base de referencia sobre agentes, workspaces, schedules y heartbeats
/paseo-handoffTraspasa contexto completo (archivos, progreso, decisiones, criterios) a otra IA
/paseo-committeePide análisis independiente a dos IAs distintas y consolida las conclusiones
/paseo-advisorObtiene una segunda opinión de solo lectura sobre un plan o diff

7. Explorador de solución de problemas

Aísla fallos siempre en este orden: ① ¿Está encendido el daemon? → ② ¿Apunto al daemon correcto? → ③ Proxy y red.

Referencia de resolución de problemas de Paseo9 casos
  • La lista de IA aparece vacía· Instalación · Detección IA

    Ejecuta claude o codex una vez en tu terminal para completar el login y vuelve a abrir Paseo.

    Solución:Instala e inicia sesión en el CLIÁrea:Instalación
  • El diagnóstico muestra 'command not found'· Instalación · Detección IA

    Revisa Providers → Diagnostic y escribe la ruta completa en agents.providers.<nombre>.command.

    Solución:Ruta absoluta en config.jsonÁrea:Instalación
  • 'Port already in use' en la segunda sala· Paralelo · Puertos · .env

    Pasa --port 3002 a mano o configura type: service con $PASEO_PORT en paseo.json.

    Solución:$PASEO_PORT + type: serviceÁrea:Worktree
  • El servidor falla en un worktree nuevo (falta .env)· Paralelo · Puertos · .env

    Añade .env a .worktreeinclude en la raíz y haz commit (manteniendo activo el plugin worktree-include).

    Solución:Commitea .worktreeincludeÁrea:Worktree
  • Escanear el código QR no hace nada· Móvil · Tailscale · SSH

    El relay viene apagado por defecto. Actívalo en Ajustes → Mi Host → Pair a device → Enable relay (CLI: paseo daemon pair).

    Solución:Activa Enable relayÁrea:Remoto
  • Tailscale agota tiempo o Paseo rechaza SSH· Móvil · Tailscale · SSH

    Comprueba Tailscale en ambos equipos y la IP del host. SSH no arranca el daemon por ti: ejecuta paseo daemon start en el servidor remoto.

    Solución:tailscale ip -4 / paseo daemon startÁrea:Remoto
  • Web UI en blanco/404 o carga sin conectar· Web UI · Proxy · Plugins

    Activa features.webUi.enabled y reinicia. En Nginx reenvía Upgrade/Connection, conserva Host, usa proxy_buffering off y timeouts largos (Caddy lo hace por defecto).

    Solución:webUi.enabled + cabeceras WebSocketÁrea:Servidor
  • 403 Invalid Host header o bloqueo de contenido mixto HTTPS· Web UI · Proxy · Plugins

    Añade tu dominio en daemon.hostnames y reenvía X-Forwarded-Proto: https junto con daemon.trustedProxies si aplica.

    Solución:daemon.hostnames / X-Forwarded-ProtoÁrea:Servidor
  • Los cambios de config no aplican o falta un plugin· Web UI · Proxy · Plugins

    Reinicia el daemon tras cambiar daemon.listen. Para plugins verifica Enable plugins, estado running y ejecuta paseo plugin logs <nombre>.

    Solución:paseo reload / plugin logsÁrea:Servidor

8. Preguntas frecuentes (FAQ) y glosario

P1. ¿Paseo incluye suscripciones de Claude o Codex?
No. Paseo es el espacio de trabajo que orquesta los CLIs de IA que ya tengas instalados y autenticados; tus planes y API keys siguen funcionando igual.
P2. ¿Por qué mis skills como /grill-me no salen en la tarjeta Orchestration skills?
Es normal: esa tarjeta solo gestiona los 4 skills oficiales /paseo. Tus skills globales de Claude Code siguen leyéndose automáticamente desde ~/.claude/skills/ cuando eliges Claude Code como proveedor.
P3. Creé paseo.json pero el setup no corre al abrir una sala nueva.
En el 90% de los casos falta hacer commit. Paseo lee paseo.json y .worktreeinclude desde la rama base commiteada (normalmente origin/main).
P4. ¿Qué reglas de seguridad son obligatorias al autoalojar Paseo?
Configura siempre contraseña con paseo daemon set-password (o PASEO_PASSWORD) antes de salir de localhost y coloca HTTPS (Caddy/Nginx) más daemon.hostnames si lo expones a internet.
P5. ¿Están aislados en sandbox los plugins de Paseo?
No. Se ejecutan sin aislamiento con permisos del daemon y acceso a la interfaz, así que instala solo plugins de fuentes en las que confíes plenamente.

Glosario esencial

TérminoSignificado
Agente (Agent)IA de programación que edita archivos y ejecuta comandos
Proveedor (Provider)Adaptador que conecta Paseo con cada CLI de IA
DaemonMotor en segundo plano (puerto 6767) al que conectan app, móvil y CLI
WorktreeFunción de Git para separar carpeta y rama de un mismo repositorio
ACP / MCPACP estandariza comunicación entre clientes IA; MCP conecta herramientas externas
OrquestaciónCoordinar varios agentes en paralelo y reunir sus resultados

Valida paseo.json y config.json localmente con Hafuture

Formatea y verifica la sintaxis de tus archivos JSON de Paseo directamente en el navegador—100% privado y sin subir nada.

Abrir Formateador JSON