Guía

Ejecutar Claude Code desde tu iPhone

Este es el recorrido por el que existe la app. Cuatro pasos: hacer accesible un host, instalar herdr en él, arrancar Claude Code y responder a su solicitud de permiso desde el panel que abre la alerta en la pantalla bloqueada. Todo lo que aparece aquí es un texto real de la app publicada o un comando real que ejecuta Moshpit.

1 Conectar con el host
Añade los datos de SSH, verifica la huella del host una vez y elige herdr como multiplexor de esa conexión.
2 Arrancar el agente
Escribe claude en un panel de herdr, o deja que Moshpit cree un git worktree nuevo y arranque Claude Code dentro.
3 Deja el teléfono a un lado
Cuando Claude Code pida permiso, la pantalla bloqueada te avisa y un toque te deja en el panel que preguntó.

Qué necesitas antes de empezar. Un servidor al que ya puedas llegar por SSH, un iPhone con iOS 18 o posterior y Claude Code instalado en el servidor. Moshpit no instala Claude Code ni se comunica con Anthropic: controla una shell, y Claude Code es un programa más corriendo en ella.

herdr es opcional. Es lo que convierte el estado del agente en un hecho en vez de una suposición, así que esta guía lo usa. El camino con tmux también funciona y está explicado en Usar tmux y Responder a agentes.

Paso 1

Haz accesible el host

Cuatro campos y una comprobación de huella. Si ya puedes hacer ssh a la máquina desde un portátil, esto toma un minuto.

Añade la conexión

En Inicio, toca + en el encabezado. El formulario está agrupado así:

  • CONEXIÓN — Nombre, Host, Puerto (por omisión 22) y Nombre de usuario. Guardar se activa en cuanto rellenas Nombre y Host.
  • AUTENTICACIÓN — Contraseña o Clave SSH. La clave puede ser una creada en Ajustes → Claves SSH o un PEM pegado directamente en el formulario.
  • AVANZADO — Multiplexor, puesto en herdr. Deja vacío el campo de ruta personalizada salvo que el binario esté en un lugar poco habitual; una ruta personalizada se toma al pie de la letra y omite la comprobación de capacidades.

El multiplexor se elige por conexión, no de forma global. No todos tus hosts tienen las mismas herramientas instaladas, y un ajuste global solo provocaría errores de «¿por qué este no conecta?».

Comprueba la huella una vez

La primera vez que te conectas, el saludo se detiene y Moshpit muestra la clave del host que recibió:

Host nuevo

Primera conexión a tu-host:22.

Huella de la clave:
SHA256:…

Comprueba que coincide con la del servidor (p. ej., `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`).

          [ Cancelar ]   [ Confiar ]

Moshpit no puede verificar la huella por ti: te muestra el comando con el que compararla. Si una clave guardada cambia algún día, el aviso pasa a ser ⚠️ La clave del host ha cambiado mostrando ambas huellas, con Desconectar como botón predeterminado y Confiar en la clave nueva marcado como destructivo.

Una limitación que conviene conocer ahora. No existe una pantalla para listar u olvidar claves de host de confianza. Eliminar una conexión no borra su huella, y la confianza se guarda por dispositivo y queda fuera de las copias de seguridad: un teléfono nuevo vuelve a preguntar por cada host. Tras un cambio legítimo de clave, aceptar el cambio en el diálogo ⚠️ es la única vía dentro de la app.

Además: las contraseñas y los PEM escritos en el formulario de conexión se guardan sin bloqueo de Face ID. Solo las claves creadas en Añadir clave con Pedir Face ID lo solicitan en cada lectura. Las claves privadas cifradas con frase de contraseña no son compatibles.

Paso 2

Instala herdr en el host

herdr es un único binario en Rust hecho para agentes de programación en CLI. Reporta agent_status como un campo de protocolo en cada panel, por eso Moshpit no necesita instalar nada en tu host para saber que Claude Code te está esperando.

Instálalo

# macOS / Linuxbrew
brew install herdr

# todo lo demás
curl -fsSL https://herdr.dev/install.sh | sh

No hay un comando de apt-get que ofrecerte: herdr no está en ningún repositorio de distribuciones Linux, y su propio empaquetado solo cubre Windows. Moshpit se niega a inventar un sudo apt-get install -y herdr por esa razón: un comando que acaba en «unable to locate package» parece un fallo de la app.

El instalador deja el binario en ~/.local/bin y a propósito no toca ningún archivo rc. Moshpit añade esa carpeta al PATH que usa al comprobar y al lanzar herdr, así que no tienes que modificar nada en el host.

Si falta, la app te lo dice

Si conectas con herdr seleccionado en un host que no lo tiene, aparece un aviso descartable, no un fallo:

  • Aviso: «No se encontró herdr en este host: sesión de shell normal.» con la acción Instalar herdr.
  • La hoja de ayuda de instalación se abre con el comando correcto ya rellenado y la frase «Moshpit nunca instala nada en silencio. Ejecuta el comando de abajo en tu shell: sudo y su salida quedan completamente a la vista.»
  • Ejecutar en el terminal lo pega en la shell activa para que los avisos de sudo y su salida sigan visibles. Al lado están Copiar comando y Volver a comprobar.
  • La sesión sigue funcionando. Recibes una shell normal y nunca se cambia en silencio a tmux: tmux y herdr llevan sesiones separadas sin relación, así que conectarse al otro te mostraría otro trabajo haciéndolo pasar por el tuyo.

Contra qué versión de herdr se construyó esto. La integración se diseñó contra herdr main / v0.8.0, protocolo 19, y se verificó en hardware real contra 0.7.3, protocolo 16 — que era lo que instalaba brew install herdr en ese momento. El decodificador de instantáneas está escrito para que un campo ausente degrade solo ese detalle en vez de hacer fallar toda la lectura.

El coste visible en 0.7.3: no reporta el comando del panel, así que el tercer segmento de la barra de ruta del terminal muestra panel N en lugar del nombre de lo que se ejecuta. El segmento se mantiene igualmente porque es la única vía para abrir la hoja Seleccionar panel.

Usa SSH, no Mosh, para esta guía. Mosh transmite diferencias de pantalla ya dibujada, lo que rompe el entramado por líneas y le impide transportar el protocolo de tramas de herdr (por la misma razón tampoco puede llevar tmux -CC). Sobre Mosh, herdr ejecuta su propia TUI a pantalla completa y Moshpit solo la dibuja: en un teléfono eso cuesta alrededor de un tercio del ancho de pantalla para la barra lateral de herdr. Las hojas de control siguen funcionando mediante un canal auxiliar SSH aparte.

Paso 3

Arranca Claude Code

Hay dos formas. Ejecútalo en un panel que ya tengas, o deja que Moshpit cree un git worktree aislado y lo arranque allí. La segunda es la que merece la pena usar desde el teléfono.

En un panel que ya tienes

nada nuevo que aprender

  • Escribe claude en un panel de herdr: ese es todo el paso
  • herdr lo detecta observando el contenido en pantalla de su propio panel
  • Nada que configurar y nada nuevo que recordar

Nueva tarea de agente

un worktree, un espacio de trabajo, un agente

  • Una sola hoja, accesible desde el encabezado AGENTES en Inicio
  • Crea un git worktree nuevo en el host y arranca Claude Code dentro
  • Tu árbol de trabajo no se mueve
  • Solo en herdr — tmux no tiene equivalente

De cualquiera de las dos formas, herdr deduce el agente a partir del contenido de la pantalla. Si quieres que se informe de manera explícita en lugar de inferirse, ejecuta herdr integration install claude en el host una vez: así Claude Code anuncia su propio estado. Es más preciso, pero no es obligatorio; todo en esta guía funciona sin ello.

La hoja, campo por campo

Grupo TAREA, pie: «Crea un git worktree en el host y arranca el agente dentro. Tu árbol de trabajo no se toca.»

  • Repositorio — un menú. Moshpit busca candidatos de dos formas a la vez: el directorio actual de cada panel abierto resuelto con git rev-parse --show-toplevel, y un recorrido de $HOME por fecha de modificación. Mientras busca, el menú muestra «Buscando repositorios…»; si no encuentra nada, «No se encontró ninguno: no hay paneles dentro de repositorios ni nada en ~». El último elemento siempre es Otro…, que abre un campo Ruta del repositorio.
  • Rama — se valida en el teléfono antes de enviar nada al servidor. Nombres vacíos, espacios, un - o / inicial, un / final, .., un .lock final y los caracteres ~ ^ : ? * [ \ se rechazan con un mensaje claro, por ejemplo «El nombre de la rama no puede tener espacios». Ninguna entrada inválida llega al host.
  • Agente — se lee de herdr server agent-manifests --json. Por omisión prefiere claude, luego codex y después el primero de la lista. (El orden alfabético hacía que el predeterminado fuera agy en un host real, así que dejó de ser alfabético.)

Grupo PRIMER MENSAJE, pie: «Opcional. Se envía al agente cuando arranca; déjalo en blanco para escribirlo tú.» El botón Iniciar cambia a Iniciando… mientras corre, porque un checkout grande tarda decenas de segundos y un botón que no cambia parece colgado.

Qué ejecuta realmente Iniciar

Tres comandos por SSH, en orden. No se oculta nada y cada texto que escribiste va entre comillas simples antes de acercarse a una shell.

herdr worktree create --cwd '~/code/payments-api' --branch 'fix-webhook-retry' \
     --label 'fix-webhook-retry' --focus --json
→ {"type":"worktree_created",
    "workspace":{"workspace_id":"w4"},
    "root_pane":{"pane_id":"w4:p1",
                 "cwd":"~/.herdr/worktrees/payments-api/fix-webhook-retry"}}

herdr pane run 'w4:p1' 'claude'          <- escribe el comando y pulsa retorno

herdr agent send 'w4:p1' '<primer mensaje>'   <- 2 s después, solo si escribiste uno

Un git worktree nuevo, un espacio de trabajo nuevo y un panel ya ubicado en ese checkout y enfocado. El segundo paso usa a propósito pane run y no agent start: agent start --workspace no hereda el directorio del worktree, así que su panel cae en el sitio equivocado. pane run escribe exactamente lo que tú habrías escrito, y puedes verlo ocurrir.

Lo primero que verás

En la verificación sobre hardware real, el espacio de trabajo apareció con cwd ~/.herdr/worktrees/…/fix-scroll-jump, git worktree list confirmó que la rama se había creado de verdad y Claude Code arrancó y se detuvo en su aviso de confianza de directorio. herdr marcó el panel como agent: claude / status: blocked y la sección Agentes de Inicio pasó de inmediato a mostrar AGENTES 1 · TE NECESITA. Esa primera pregunta es la que respondes en el paso 4.

Limpiar al terminar

Mantén pulsada la fila del espacio de trabajo en Inicio → Quitar worktree. La opción solo aparece en espacios de trabajo que realmente son un worktree enlazado. El primer comando nunca lleva --force:

  • ¿Quitar el worktree de «…»? — «Elimina el checkout de la rama en ~/.herdr/worktrees. payments-api en sí no se toca.»
  • Si herdr se niega porque el worktree tiene cambios, y solo entonces, aparece un segundo aviso: «…» tiene cambios sin confirmar — «Esos cambios no existen en ningún otro sitio. Si quitas el worktree, se pierden.» Botones Eliminar de todos modos / Conservar. Solo ese toque explícito añade --force.

Límites de este paso, dichos sin rodeos.

Los worktrees se crean en ~/.herdr/worktrees/<repo>/<rama>, no junto al repositorio, y en esta versión no hay opción de ruta: no merece la pena escribir rutas largas en un teléfono. Los repositorios grandes tardan decenas de segundos en crearse. Se espera que git worktree add funcione bien sobre un repositorio con cambios pendientes, pero no se ha verificado.

Las banderas del agente no se eligen por ti. Se ejecuta el comando claude predeterminado del manifiesto. Opciones como --dangerously-skip-permissions tienes que escribirlas tú en el panel.

herdr solo ve agentes en sus propios paneles. Un claude que arrancaste en Terminal.app en la misma máquina no aparece: herdr es un entorno de ejecución, no un escáner de procesos. Nos pasó en la práctica: cinco paneles inactivos de herdr, un claude ocupado en otro terminal, y la sección Agentes decía con razón «No hay nada en marcha. Inicia una tarea para aislarla en su propio worktree» mientras el usuario juraba que algo estaba corriendo.

No verificado en dispositivo físico: el menú contextual de pulsación larga en sí. La automatización no puede pulsar de forma prolongada en SwiftUI, así que la secuencia menú → diálogo → diálogo está verificada por compilación y pruebas unitarias, sin grabación en dispositivo.

Paso 4

Responde a la solicitud de permiso estés donde estés

Claude Code se detiene y pregunta si puede ejecutar un comando. El ámbar es el único color en este sitio que significa «un agente necesita a una persona», y aquí es donde aparece: como una notificación que llega al teléfono bloqueado.

Pantalla bloqueada de iPhone: notificación urgente de Moshpit — claude necesita permiso para usar Bash en m1-pro

La pregunta, en el teléfono bloqueado El título es el agente; el cuerpo dice qué pregunta y dónde — Claude needs your permission to use Bash — m1-pro · pit. Cuando varios agentes esperan en un mismo host, comparten una sola tarjeta: claude +2.

El toque Aterriza exactamente en el panel que preguntó. Lees el prompt en un terminal de verdad y respondes con las mismas teclas que pulsarías en tu escritorio.

Sin botón Permitir, a propósito Los botones en pantalla bloqueada que la app tuvo antes enviaban una pulsación a ciegas al panel. Aprobar algo que no has leído, en una app cuyo valor es justo poder leerlo, era el compromiso equivocado: por eso se quitaron.

Cómo llega a un teléfono donde la app no está abierta

Tu host hace la parte que un iPhone suspendido no puede hacer. Los mismos hooks que marcan el panel pasan attention y done — nunca working — a un pequeño emisor, ~/.moshpit/moshpit-push.sh, que sella la alerta con una clave que solo tiene tu teléfono y envía el texto cifrado al servidor relay de Moshpit y luego a Apple. Ninguno de los dos puede leer un solo byte: el nombre del agente, el comando y la pregunta se descifran dentro de una extensión de notificaciones en tu teléfono, incluida la pantalla bloqueada. El emparejamiento ocurre solo la primera vez que activas notificaciones en un host; el único consentimiento que se pide es la primera instalación de hooks.

Alcance, dicho sin rodeos. El emisor se apoya en los hooks del agente, y esos hooks marcan paneles de tmux: por tanto, el camino push con la app cerrada requiere que el agente corra bajo tmux con los hooks instalados. En un panel puro de herdr, el propio agent_status de herdr alimenta la isla y las notificaciones mientras Moshpit está activo, y los avisos se detienen cuando la app se cierra. Si lo que buscas es que te avise con la app cerrada, ejecuta Claude Code en un panel de tmux por ahora.

Las cuatro reglas que mantienen el silencio

Notificar por todo equivale a no notificar por nada, así que cada alerta tiene que ganarse la interrupción:

ReglaQué significa
30 segundos esperando Una pregunta respondida en tu escritorio dentro de ese margen nunca se anuncia a ningún teléfono.
Una tarjeta por host Todos los agentes en espera comparten un único resumen («claude +2»). Solo la transición de nadie esperaba → alguien espera suena y puede atravesar los modos de concentración; todo lo posterior actualiza la tarjeta en silencio.
«Listo» suena a partir de 3 minutos Un turno terminado hace sonido solo si duró tres minutos o más. Los turnos cortos quedan en la lista sin encender la pantalla.
Los agentes aparcados guardan silencio Un recordatorio de inactividad en un agente que dejaste adrede en su prompt no enciende nada, y un «te necesita» obsoleto de hace un día pasa solo a listo.

Honestidad también en la letra pequeña: ver un prompt dentro de la app lo marca como atendido, y reconectar o relanzar nunca vuelve a sonar por una pregunta de la que ya te avisó.

Los cuatro interruptores que lo controlan

Ajustes → NOTIFICACIONES. Los cuatro vienen activados por omisión.

  • Notificaciones — «Avisar cuando un agente te necesite»
  • Actividad en Vivo — «Mostrar el estado del agente en la Dynamic Island»
  • Sonido de aviso — «Reproducir un sonido cuando el agente te necesite»
  • Mostrar detalles en la pantalla bloqueada — «Muestra qué ejecuta el agente, qué pregunta o qué prompt acaba de responder. Desactivado, se mantiene en privado». Si lo desactivas, sigues viendo trabajando / te necesita / listo, pero no la línea Bash: npm install.

Desactiva tanto Notificaciones como Actividad en Vivo y no se vigila nada. La fila Configurar este host debajo de los interruptores muestra qué tiene instalado el host conectado: qué agentes tienen hooks, si el emisor push está instalado y el emparejamiento de este teléfono; la configuración en sí es automática al conectar.

Dynamic Island mostrando un punto ámbar y un signo de exclamación: un agente te necesita

Desbloqueado · te necesita La píldora muestra un signo de exclamación ámbar para un agente bloqueado, o el número cuando son varios. Solo cabe un agente en la píldora: mantenla pulsada y la vista expandida lista los demás debajo.

Dynamic Island mostrando un punto turquesa y un cronómetro en vivo mientras un agente trabaja

Desbloqueado · trabajando Turquesa con cronómetro en vivo mientras Claude Code corre. Un agente pensando y uno atascado no se parecen en nada.

La parte honesta

Qué pasa cuando mandas la app a segundo plano

Esta es la sección que conviene leer antes de depender de todo lo anterior. El push cifrado es lo que cubre el hueco ahora, y aquí también está escrito lo que no cubre.

iOS suspende la conexión y las vistas en vivo se pausan

Cuando iOS suspende la app, el barrido cada 2 segundos y los sondeos SSH se detienen con ella. Lo que sí cruza ese hueco es la ruta push del paso 4: los hooks de tu host detectan attention y done y envían la alerta cifrada por su cuenta, sin necesidad de sesión viva, con el teléfono bloqueado y la app cerrada.

Lo que no cruza ese hueco: la Actividad en Vivo. Muestra el último estado que vio la app, y con la app suspendida nada la alimenta. Medido en dispositivo: con Moshpit en segundo plano, pasar un panel de bloqueado a trabajando dejó la Dynamic Island sin cambios hasta el primer sondeo tras volver a primer plano.

Por eso la isla dice «en pausa» en vez de mentir

Moshpit                      2 trabajando · 1 te necesita
●  claude                   TE NECESITA · 2m
   mac-studio · ~ · Pestaña 1
   Bash: npm install

… app suspendida durante dos minutos …

Moshpit            en pausa: abre Moshpit para actualizar

La Actividad en Vivo tiene un horizonte de frescura de 120 segundos — dos barridos perdidos — y muestra un aviso honesto de «en pausa» en vez de un «trabajando» congelado. El widget de la pantalla de inicio usa 180 segundos y atenúa a gris todos los puntos de estado cuando caduca. Donde el emisor del paso 4 está instalado, las notificaciones push siguen llegando igualmente.

Incluso en primer plano, los cambios externos tardan un poco

  • El sondeo de control de herdr corre cada 2 segundos mientras hay movimiento y se relaja a 8 segundos tras tres lecturas idénticas. Cualquier cambio, o tirar para actualizar, lo devuelve a 2 segundos.
  • Todo lo que haces dentro de la app se refresca de inmediato: cada cambio va seguido de una relectura. Todo lo que ocurra fuera (tu portátil, otro cliente, un agente que cambia de estado) puede tardar hasta 8 segundos en aparecer.
  • Por eso los tiempos transcurridos se muestran en minutos — ahora, 2m, 1h 12m — y nunca en segundos. Los datos subyacentes tienen hasta 8 segundos de margen, y mostrar segundos fingiría una precisión que el número no tiene.
  • La API de socket de herdr sí tiene suscripción a eventos, pero su CLI no expone un comando de suscripción y un teléfono no puede abrir un socket Unix en tu host. El sondeo es el único mecanismo disponible hoy.

Dos clientes de Moshpit en el mismo panel pelearán

La conexión directa de herdr es exclusiva por panel. Moshpit debe conectarse con --takeover porque una reconexión siempre choca con su propio canal obsoleto. Dos teléfonos en el mismo panel se lo arrebatarán uno al otro cada dos segundos aproximadamente. Es algo inherente a la conexión directa exclusiva y no puede arreglarse desde el cliente.

Qué hace Moshpit al respecto: tres cierres no solicitados en 30 segundos activan una pausa de 30 segundos y un aviso visible — «Otro cliente está usando este panel. Se reintentará en breve» — que desaparece en cuanto vuelven a pintarse tramas. Un portátil ejecutando la propia TUI de herdr no ocupa un hueco de conexión, así que portátil + teléfono debería ser seguro, pero esa combinación no se ha probado.

Cabos sueltos

Preguntas que suele despertar esta guía

¿Tengo que usar herdr obligatoriamente?

No. En tmux, instala los hooks de agente desde Ajustes → NOTIFICACIONES → Instalar hooks de agente: un comando que registra los hooks UserPromptSubmit, PreToolUse, Notification y Stop de Claude Code para que marquen el estado en el panel de tmux. Primero hace copia de seguridad de ~/.claude/settings.json, siempre sale con 0 para no bloquear al agente y evita duplicados si lo ejecutas dos veces. Sin hooks, Moshpit recurre a leer la salida del panel y la campana del terminal, lo cual es una estimación y así se describe. La sección Agentes en Inicio es exclusiva de herdr.

¿Puede avisarme cuando Moshpit está cerrado?

Sí: para eso existe la ruta push. Los hooks en tu host sellan la alerta con una clave que solo tiene tu teléfono y la envían por el servidor relay de Moshpit; una extensión de notificaciones la descifra en la pantalla bloqueada, con la app cerrada y el teléfono bloqueado. Aplica la nota de alcance del paso 4: el emisor se apoya en los hooks del agente, que marcan paneles de tmux, así que ejecuta el agente bajo tmux si esa es la parte que te importa. Las reglas de silencio — margen de 30 segundos, una tarjeta por host, «listo» solo suena pasados tres minutos, agentes aparcados en silencio — están explicadas en Responder a agentes.

¿Qué pasa con Mosh?

Mosh es la opción adecuada para una shell que quieres que sobreviva al cambio de Wi-Fi a 5G, pero no puede transportar el protocolo de tramas de herdr ni tmux -CC. Sobre Mosh, herdr ejecuta su propia TUI dentro del terminal y usa alrededor de un tercio del ancho del teléfono para su barra lateral; las hojas de control siguen funcionando mediante un canal auxiliar SSH aparte. Para esta guía, usa SSH. Detalles en Mosh e itinerancia.

Claude Code está corriendo pero la sección Agentes aparece vacía.

Casi seguro no está corriendo dentro de un panel de herdr. herdr identifica agentes observando sus propios paneles, así que un claude iniciado en Terminal.app o en otra sesión SSH es invisible para él. Arráncalo con Nueva tarea de agente o ejecútalo dentro de un panel de herdr. En herdr 0.7.3 hay un segundo efecto: no reporta nombre de agente, así que un agente inactivo nunca genera fila.

¿Moshpit lee mi código, mis prompts o algo más?

No hay cuenta de Moshpit ni analítica, y el tráfico del terminal va solo a los servidores que tú añades. La única pieza operada por Moshpit es el servidor relay de notificaciones push, y transporta texto cifrado que no puede abrir: la alerta se sella en tu host con una clave que solo tiene tu teléfono. Lo único que sale del panel es el título corto del hook — qué está ejecutando o preguntando el agente, limitado a 80 caracteres —, que viaja cifrado y se muestra en tu propia pantalla bloqueada.

¿Por dónde sigo ahora?

Conexiones y claves para el formulario completo y el manejo de claves de host, Usar herdr para el vocabulario y los atajos, y Responder a agentes para ver en detalle las notificaciones y la Actividad en Vivo. Si algo no conecta o se comporta raro, empieza por Solución de problemas.

Continúa con Llegar a tu máquina desde cualquier lugar · Volver a las guías