En cuanto dejas de usar los proveedores "por defecto", te topas con un problema conocido:

Puedes ejecutar tu CLI favorita en tu ordenador.

Pero el flujo desde el móvil desaparece.

Esta guía trata de recuperar ese flujo desde el móvil:

• ejecutar en local tu propia CLI compatible con ACP
• seguir monitorizando las sesiones desde el móvil
• seguir gestionando aprobaciones y seguimientos

En resumen

1. Elige una CLI compatible con ACP que quieras ejecutar en local.
2. Defínela como backend de ACP personalizado (Custom ACP) (comando, detección y comprobación de autenticación).
3. Haz que su comportamiento sea predecible en el ordenador anfitrión:
   • verifica la ruta del binario
   • verifica las reglas del directorio de trabajo
   • verifica los comandos de detección y autenticación
4. Usa un ciclo corto desde el móvil: revisar → aprobaciones → un seguimiento → salir.

El problema

Las integraciones personalizadas fallan por motivos prácticos:

• ruta del binario incorrecta
• directorio de trabajo incorrecto
• autenticación ausente en el ordenador correcto

Así que el primer objetivo es que la integración sea predecible.

Enfoques habituales y sus contrapartidas

• SSH/tmux: funciona, pero acaba siendo "trabajar de verdad en la terminal desde el móvil".
• Escritorio remoto: pesado y engorroso.
• Esperar: seguro, pero lento.

Lo que funciona bien es una superficie de control dedicada para el móvil.

• Happier: tu CLI de ACP personalizado sigue ejecutándose en el ordenador, pero tienes una interfaz en el móvil para revisar, aprobar y enviar seguimientos. Contrapartida: sigue dependiendo de que el ordenador que ejecuta el agente esté en línea.

Si Happier es nuevo para ti (qué es y dónde conseguirlo)

Si no conocías Happier: es una app complementaria de código abierto (móvil/web/escritorio) para sesiones de programación.

Para empezar:

• GitHub: https://github.com/happier-dev/happier
• Instalación/descarga: https://github.com/happier-dev/happier#how-it-works
• Discord: https://discord.gg/W6Pb8KuHfg

ACP en 90 segundos (para que el resto de la guía tenga sentido)

ACP (Agent Client Protocol) es el protocolo entre:

• un cliente (una app, IDE o panel) y
• un proceso de agente (tu CLI)

El transporte por defecto es stdio: mensajes JSON-RPC delimitados por saltos de línea.

La consecuencia práctica clave:

• el stdout de tu agente es el protocolo
• tus logs tienen que ir a stderr

Si mezclas logs en stdout, el cliente no puede analizar el flujo y todo parece "roto".

ACP frente a MCP (por qué aparecen los dos)

• ACP es cómo el cliente habla con la sesión de tu agente.
• MCP es cómo el agente habla con los servidores de herramientas (GitHub, automatización del navegador, etc.).

Las sesiones de ACP se pueden iniciar con una lista mcpServers, así que puedes tener:

• una CLI de agente personalizada
• más un conjunto coherente de herramientas

Las reglas que deciden si ACP personalizado funciona (el contrato de stdio)

Estas son causas comunes de que una integración falle:

• stdout debe contener solo mensajes del protocolo ACP
• los logs deben ir a stderr
• los mensajes se delimitan con saltos de línea, así que no puede haber saltos de línea dentro de un mensaje JSON
• no formatees el JSON para que sea legible (indent=2 lo rompe)

Si quieres una prueba rápida de "¿mi agente es compatible?":

• ejecútalo en modo ACP y confirma que responde a initialize sin imprimir banners

Paso 1: define tu backend de ACP personalizado

Aquí es donde se atasca mucha gente, porque es un trabajo de configuración detallado.

Tienes que definir:

• nombre/id (cómo lo reconocerás)
• comando (cómo se inicia)
• comando de detección (una comprobación segura de "¿está instalado?")
• comprobación de autenticación (opcional, solo si es segura)
• expectativas sobre el directorio de trabajo (¿da por hecho la raíz del repositorio?)

Una regla que ahorra tiempo: empieza solo con la detección y añade la comprobación de autenticación más adelante.

Negociación de capacidades (no des por hecho que existen los métodos)

ACP empieza con initialize.

El agente responde con sus capacidades.

Los clientes no deberían llamar a métodos que el agente no declara admitir.

Si "reanudar/cargar" no está admitido, verás síntomas como:

• se inician sesiones nuevas cuando esperabas reanudar
• falta el historial

Así que con ACP personalizado es normal publicar primero un agente mínimo (sesión nueva y prompt) y añadir los métodos de ciclo de vida después.

Paso 2: haz que la integración sea predecible primero en un ordenador

Antes de probar flujos con varios ordenadores, haz que funcione en uno.

Aquí es donde "funciona en mi terminal" se separa de "funciona cuando lo lanza un cliente".

Lista de comprobación:

• ¿se puede ejecutar el comando desde el directorio de trabajo esperado?
• ¿depende de un archivo de inicio de la shell (.zshrc, nvm, asdf)?
• ¿necesita variables de entorno o secretos?
• ¿imprime banners o barras de progreso en stdout?

Si la CLI necesita credenciales, no las pegues en la definición del backend. Usa variables de entorno o un sistema de secretos guardados.

Patrones de autenticación que te encontrarás

La mayoría de los agentes ACP encajan en uno de estos patrones:

1. Autenticación por variables de entorno

   • el cliente lanza el agente con variables de entorno
   • sencillo y fácil de automatizar

2. Inicio de sesión en la terminal

   • ejecutas <cli> login una vez en una terminal
   • el agente usa el estado de autenticación local de la máquina

3. OAuth en una interfaz (menos habitual en herramientas centradas en la CLI)

El diseño de autenticación de ACP es prudente a propósito: el agente no debería poder engañar al cliente para que ejecute comandos arbitrarios con la excusa de autenticarse.

Paso 3: el flujo desde el móvil

El ciclo de 2 minutos

1. abre la sesión
2. revisa las aprobaciones
3. envía un seguimiento
4. sal

Tres seguimientos para copiar y pegar

1. Punto de control

Para después del siguiente paso y resume:

• qué has cambiado
• qué no has cambiado
• qué quieres hacer a continuación

2. Restricción

No toques migraciones ni autenticación. Si crees que lo necesitas, para y pregunta.

3. Prueba

Antes de seguir, pega el comando exacto que vas a ejecutar y explica por qué.

Recetas de configuración por cliente (para copiar y pegar)

Cuando tu agente ya cumple ACP, lo siguiente que da guerra son los formatos de configuración de cada cliente.

Algunos habituales:

• agentes personalizados de JetBrains mediante un acp.json
• el JSON de ajustes de Zed
• el cliente ACP de CodeCompanion para Neovim (con limitaciones explícitas)

No hay un formato de archivo universal.

La regla es: elige un cliente, haz que funcione ahí y luego añade más.

Guía de depuración (antes de culpar al agente)

1) Demuestra que el stdout de tu agente está limpio

Si ves errores de análisis, el 80 % de las veces es porque stdout contiene algo que no es JSON-RPC.

Manda todos los logs a stderr.

2) Evita saltos de línea dentro de los mensajes

No formatees los mensajes JSON. Un mensaje tiene que ser una línea.

3) Demuestra que el directorio de trabajo es el que crees

Muchos agentes personalizados "funcionan" pero operan sobre el repositorio equivocado porque el cwd está mal.

Solución de problemas

La detección funciona pero las sesiones no arrancan

Normalmente significa:

• faltan variables de entorno
• directorio de trabajo incorrecto
• tu CLI imprime banners o logs en stdout
• la CLI espera una TTY (no es compatible con ACP por stdio)

El agente arranca, pero no aparecen las herramientas

Suele ser un desajuste en la configuración de MCP:

• campos de stdio frente a http/sse
• faltan cabeceras o variables de entorno

La autenticación muestra "desconocido (Unknown)"

Si tu comprobación de autenticación no es segura (o no está definida), lo esperable es desconocido (Unknown).

Interprétalo como "no se sabe", no como "sin sesión".

Preguntas frecuentes

¿Tengo que implementar toda la especificación de ACP?

No.

Un agente "mínimo viable" admite:

• initialize
• session/new
• session/prompt

Todo lo demás (cargar/reanudar, herramientas avanzadas, adjuntos) puede llegar después.

¿Por qué funciona en mi terminal pero no en mi IDE o app?

Casi siempre es una de estas:

• desajuste de PATH o variables de entorno
• directorio de trabajo incorrecto
• stdout contaminado

¿Es seguro dejar que un agente controle los comandos de autenticación?

ACP se diseña explícitamente para evitarlo: los flujos de autenticación por terminal deben ejecutar el mismo binario y el agente no debería poder especificar comandos arbitrarios.

Si Happier es nuevo para ti

Happier es una app complementaria para ejecutar sesiones en un ordenador de confianza y seguirlas desde el móvil.

Para empezar:

• GitHub: https://github.com/happier-dev/happier
• Instalación/descarga: https://github.com/happier-dev/happier#how-it-works
• Discord: https://discord.gg/W6Pb8KuHfg