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.
Índice
- 1. ¿Qué es Paseo y qué necesitas antes?
- 2. Tres formas de instalarlo
- 3. Tres palabras clave: Proyecto, Workspace y Sesión
- 4. Worktrees en paralelo y paseo.json
- 5. Revisar diffs, móvil por QR y 7 comandos CLI
- 6. Orquestación multi-agente, skills y plugins
- 7. Explorador de solución de problemas
- 8. Preguntas frecuentes (FAQ) y glosario
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
| Requisito | Detalle |
|---|---|
| 1+ CLI de código IA | Tener instalado y autenticado Claude Code, Codex, OpenCode, Pi, Antigravity o Muse Code (si responde en tu terminal, está listo) |
| Git + Carpeta de proyecto | El 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
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
npm install -g @getpaseo/cli
paseo3. 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ún | Realidad |
|---|---|
| 1 Workspace = 1 Chat | Falso. Un workspace es una sala que aloja múltiples chats, terminales y pestañas de navegador a la vez. |
| Archivar borra mi código | Las 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 previo | Ve 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:
- 1Crea la primera sala worktree
New workspace → Isolation: New worktree → Base: origin/main → elige tu agente (ej. Claude Code). Tu rama main original queda intacta.
- 2Indica qué hacer y cómo verificarlo
Pide 'Añade orden por precio y nombre y ejecuta los tests relacionados' para obtener resultados verificables.
- 3Abre una segunda sala para una tarea independiente
Crea login-polish desde my-app evitando solapar archivos (puedes incluso asignar otro modelo IA).
- 4Evita 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.
{
"worktree": {
"setup": "npm ci",
"teardown": "rm -rf .cache || true"
},
"scripts": {
"test": { "command": "npm test" },
"web": {
"command": "npm run dev -- --port $PASEO_PORT",
"type": "service"
}
}
}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 testen 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+ puerto6767) o conéctate a un servidor remoto con daemon activo mediantessh://user@host.
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
- Activa Ajustes → Mi Host → Agents → Enable Paseo tools (apagado por defecto).
- Abre una sesión nueva para que el agente reciba las herramientas.
- 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:
| Skill | Cuándo usarlo |
|---|---|
/paseo | Guía base de referencia sobre agentes, workspaces, schedules y heartbeats |
/paseo-handoff | Traspasa contexto completo (archivos, progreso, decisiones, criterios) a otra IA |
/paseo-committee | Pide análisis independiente a dos IAs distintas y consolida las conclusiones |
/paseo-advisor | Obtiene 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.
- 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?
P2. ¿Por qué mis skills como /grill-me no salen en la tarjeta Orchestration skills?
P3. Creé paseo.json pero el setup no corre al abrir una sala nueva.
P4. ¿Qué reglas de seguridad son obligatorias al autoalojar Paseo?
P5. ¿Están aislados en sandbox los plugins de Paseo?
Glosario esencial
| Término | Significado |
|---|---|
| Agente (Agent) | IA de programación que edita archivos y ejecuta comandos |
| Proveedor (Provider) | Adaptador que conecta Paseo con cada CLI de IA |
| Daemon | Motor en segundo plano (puerto 6767) al que conectan app, móvil y CLI |
| Worktree | Función de Git para separar carpeta y rama de un mismo repositorio |
| ACP / MCP | ACP estandariza comunicación entre clientes IA; MCP conecta herramientas externas |
| Orquestación | Coordinar 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.