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.
claude en un panel de herdr, o deja que Moshpit cree un
git worktree nuevo y arranque Claude Code dentro.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) yNombre de usuario. Guardar se activa en cuanto rellenas Nombre y Host. - AUTENTICACIÓN —
ContraseñaoClave 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$HOMEpor 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 campoRuta 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.lockfinal 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 prefiereclaude, luegocodexy después el primero de la lista. (El orden alfabético hacía que el predeterminado fueraagyen 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-apien 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.
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:
| Regla | Qué 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.
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.
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