Guia

Rodar o Claude Code pelo iPhone

Este é o fluxo pelo qual o app existe. Quatro passos: deixar um host acessível, colocar o herdr nele, iniciar o Claude Code e responder ao pedido de permissão no painel em que o alerta da Tela Bloqueada coloca você. Tudo aqui vem de textos reais do app publicado ou de comandos reais que o Moshpit executa.

1 Alcance o host
Adicione os dados SSH, confira a impressão digital do host uma vez e escolha herdr como multiplexador dessa conexão.
2 Inicie o agente
Digite claude em um painel do herdr, ou deixe o Moshpit criar um novo git worktree e iniciar o Claude Code lá dentro.
3 Guarde o celular
Quando o Claude Code pedir permissão, a Tela Bloqueada avisa — e um toque coloca você no painel que perguntou.

O que você precisa antes de começar. Um servidor que você já consiga acessar via SSH, um iPhone com iOS 18 ou posterior e o Claude Code instalado no servidor. O Moshpit não instala o Claude Code e não conversa com a Anthropic — ele conduz um shell, e o Claude Code é só um programa rodando dentro dele.

O herdr é opcional. Ele transforma o status do agente em fato em vez de palpite, por isso este guia o utiliza. O caminho com tmux também funciona e está descrito em Usando o tmux e Respondendo a agentes.

Passo 1

Deixe o host acessível

Quatro campos e uma conferência de impressão digital. Se você já consegue fazer ssh na máquina pelo notebook, esta parte leva um minuto.

Adicione a conexão

No Início, toque em + no cabeçalho. O formulário é dividido em grupos:

  • CONEXÃO — Nome, Host, Porta (padrão 22), Nome de usuário. O botão Salvar acende assim que Nome e Host são preenchidos.
  • AUTENTICAÇÃO — Senha ou Chave SSH. A chave pode ser uma criada em Ajustes → Chaves SSH ou um PEM colado direto no formulário.
  • AVANÇADO — Multiplexador, definido como herdr. Deixe o campo de caminho personalizado em branco, a menos que o binário esteja num lugar incomum; um caminho personalizado é usado literalmente e pula a detecção de recursos.

O multiplexador é escolhido por conexão, não globalmente. Nem todos os seus hosts têm as mesmas ferramentas instaladas, e um padrão global só geraria o clássico «por que este aqui não conecta?».

Confira a impressão digital uma vez

Na primeira conexão, o handshake pausa e o Moshpit mostra a chave do host que o servidor apresentou:

Novo host

Primeira conexão com seu-host:22.

Impressão digital da chave:
SHA256:…

Confira se ela bate com a do servidor (por exemplo, `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`).

          [ Cancelar ]   [ Confiar ]

O Moshpit não tem como validar a impressão digital por você — ele mostra o comando para você comparar. Se uma chave guardada mudar depois, o alerta vira ⚠️ A chave do host mudou com as duas impressões digitais lado a lado, Desconectar como botão padrão e Confiar na nova chave marcado como ação destrutiva.

Limitação que vale saber agora. Não existe uma tela para listar ou esquecer chaves de host confiáveis. Apagar uma conexão não apaga a impressão digital dela, e a confiança fica salva por aparelho e fora dos backups — um celular novo volta a perguntar para cada host. Depois de uma troca legítima de chave, aceitar a alteração no aviso ⚠️ é o único caminho dentro do app.

Além disso: senhas e PEMs digitados direto no formulário de conexão ficam salvos sem barreira de Face ID. Apenas chaves criadas em Adicionar chave com Exigir Face ID pedem biometria a cada uso. Chaves privadas protegidas por frase-senha não são suportadas.

Passo 2

Coloque o herdr no host

O herdr é um único binário em Rust feito para agentes de programação em CLI. Ele informa agent_status como campo de protocolo em cada painel — é por isso que o Moshpit não precisa instalar nada no host para saber que o Claude Code está esperando você.

Instale

# macOS / Linuxbrew
brew install herdr

# todo o resto
curl -fsSL https://herdr.dev/install.sh | sh

Não existe comando apt-get para passar: o herdr não está em nenhum repositório de distribuição Linux, e o empacotamento oficial dele só cobre Windows. Por isso o Moshpit se recusa a fabricar sudo apt-get install -y herdr — um comando que termina em «unable to locate package» parece bug do app.

O instalador grava o binário em ~/.local/bin e propositalmente não mexe em nenhum arquivo rc. O Moshpit acrescenta esse diretório ao PATH que usa ao detectar e ao iniciar o herdr, então você não precisa alterar nada no host.

Se ele estiver faltando, o app avisa

Se você conectar com herdr escolhido em um host que não o tem, aparece um aviso dispensável, não uma falha:

  • Aviso: «herdr não encontrado neste host: sessão de shell simples.» com a ação Instalar herdr.
  • A folha de auxílio de instalação abre com o comando certo já preenchido e o texto «O Moshpit nunca instala nada em silêncio. Rode o comando abaixo no seu shell: o sudo e a saída dele ficam totalmente visíveis.»
  • Rodar no terminal cola o comando no shell ativo para que prompts do sudo e a saída fiquem visíveis. Copiar comando e Verificar de novo ficam ao lado.
  • A sessão continua funcionando. Você recebe um shell simples, e o app nunca troca silenciosamente para o tmux — tmux e herdr mantêm sessões separadas e sem relação, então abrir o outro mostraria outro trabalho como se fosse o seu.

Contra qual versão do herdr isso foi desenvolvido. A integração foi projetada para o herdr main / v0.8.0, protocolo 19, e validada em aparelho real com 0.7.3, protocolo 16 — que era o que o brew install herdr instalava na época. O decodificador de snapshots foi escrito para que um campo ausente degrade apenas aquele detalhe em vez de derrubar toda a leitura.

O efeito visível na 0.7.3: ela não informa o comando do painel, então o terceiro segmento da barra de navegação do terminal cai para painel N em vez de mostrar o nome do que está rodando. O segmento continua lá mesmo assim, porque é o único acesso à folha «Selecionar painel».

Use SSH, não Mosh, neste guia. O Mosh transmite diffs de tela renderizada, o que destrói o enquadramento de linhas e impede carregar o protocolo de quadros do herdr (o mesmo motivo pelo qual não carrega tmux -CC). Sobre Mosh, o herdr roda a própria TUI em tela cheia e o Moshpit só renderiza — no celular isso consome cerca de um terço da largura com a barra lateral do herdr. As folhas de controle ainda funcionam por um canal SSH separado em paralelo.

Passo 3

Inicie o Claude Code

Dois caminhos. Rode em um painel que você já tem, ou deixe o Moshpit abrir um git worktree isolado e iniciar lá dentro. O segundo é o que realmente faz diferença no celular.

Em um painel que você já tem

nada novo para aprender

  • Digite claude em um painel do herdr — o passo inteiro é só isso
  • O herdr detecta observando o conteúdo da tela do próprio painel
  • Nada para configurar e nada novo para decorar

Nova tarefa de agente

um worktree, um espaço de trabalho, um agente

  • Uma única folha, acessível pelo cabeçalho AGENTES no Início
  • Cria um novo git worktree no host e inicia o Claude Code dentro dele
  • Sua árvore de trabalho principal não muda
  • Exclusivo do herdr — o tmux não tem equivalente

De qualquer forma, o herdr infere o agente pelo conteúdo da tela. Se quiser que o estado seja informado em vez de inferido, rode herdr integration install claude uma vez no host — aí o próprio Claude Code anuncia o estado dele. É mais preciso, mas não é obrigatório; tudo neste guia funciona sem isso.

A folha, campo por campo

Grupo TAREFA, rodapé: «Cria um git worktree no host e inicia o agente dentro dele. Sua árvore de trabalho não é alterada.»

  • Repositório — um menu. O Moshpit busca candidatos de dois jeitos ao mesmo tempo: o diretório atual de cada painel aberto resolvido com git rev-parse --show-toplevel e uma varredura em $HOME ordenada por data de modificação. Enquanto procura, o menu exibe «Procurando repositórios…»; se não achar nada, «Nenhum encontrado: não há painéis dentro de repositórios nem nada em ~». O último item é sempre Outro…, que abre o campo Caminho do repositório.
  • Branch — validado no celular antes de qualquer ida ao servidor. Nomes vazios, espaços, - ou / no início, / no fim, .., sufixo .lock e os caracteres ~ ^ : ? * [ \ são bloqueados com uma mensagem clara, como «O nome da branch não pode ter espaços». Entrada inválida nunca chega ao host.
  • Agente — lido de herdr server agent-manifests --json. O padrão prioriza claude, depois codex, depois o primeiro da lista. (A ordem alfabética fazia o padrão cair em agy num host real, por isso deixou de ser alfabética.)

Grupo PRIMEIRA MENSAGEM, rodapé: «Opcional. Enviado ao agente assim que ele estiver rodando; deixe em branco para digitar você mesmo.» O botão Iniciar muda para Iniciando… durante a operação, porque um checkout grande leva dezenas de segundos e um botão que não reage parece travado.

O que Iniciar realmente executa

Três comandos via SSH, em ordem. Nada fica escondido, e todo texto digitado por você vai entre aspas simples antes de encostar num 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'          <- digita o comando e pressiona Return

herdr agent send 'w4:p1' '<primeira mensagem>'   <- 2 s depois, só se você escreveu uma

Um novo git worktree, um novo espaço de trabalho e um painel já posicionado no checkout, em foco. O segundo passo usa propositalmente pane run em vez de agent start: agent start --workspace não herda o diretório do worktree, então o painel abre no lugar errado. pane run digita exatamente o que você digitaria, e você vê acontecer.

O que você vai ver primeiro

Na verificação em aparelho real, o espaço de trabalho surgiu com o diretório ~/.herdr/worktrees/…/fix-scroll-jump, git worktree list confirmou que a branch foi criada de verdade e o Claude Code abriu e parou no prompt de confiança de diretório. O herdr marcou o painel como agent: claude / status: blocked, e a seção Agentes no Início passou imediatamente a mostrar AGENTES 1 · PRECISA DE VOCÊ. Esse primeiro prompt é o que você responde no passo 4.

Limpando tudo depois

Segure a linha do espaço de trabalho no Início → Remover worktree. A opção só aparece em espaços de trabalho que realmente são worktrees vinculados. O primeiro comando nunca passa --force:

  • Remover o worktree de «…»? — «Apaga o checkout da branch em ~/.herdr/worktrees. payments-api em si não é alterado.»
  • Se o herdr recusar porque há arquivos modificados — e só nesse caso — aparece um segundo aviso: «…» tem alterações sem commit — «Essas alterações não existem em nenhum outro lugar. Remover o worktree joga tudo fora.» Botões Apagar mesmo assim / Manter. Só esse toque explícito acrescenta --force.

Limites deste passo, sem rodeios.

Os worktrees ficam em ~/.herdr/worktrees/<repo>/<branch>, não ao lado do repositório, e não há opção de caminho personalizado nesta versão — não é algo que compense digitar no celular. Repositórios grandes levam dezenas de segundos para concluir o checkout. O comportamento do git worktree add em um repositório com alterações pendentes deve funcionar bem, mas não foi validado.

Flags do agente não são escolhidas por você. O que roda é o comando padrão claude do manifesto. Opções como --dangerously-skip-permissions precisam ser digitadas por você, no painel.

O herdr só enxerga agentes dentro dos próprios painéis. Um claude iniciado no Terminal.app na mesma máquina não aparece — o herdr é um runtime, não um scanner de processos. Isso já aconteceu na prática: cinco painéis ociosos no herdr, um claude ativo em outro terminal, e a seção Agentes corretamente dizia «Nada rodando. Inicie uma tarefa para isolá-la no próprio worktree» enquanto o usuário tinha certeza de que havia algo rodando.

Não verificado no aparelho: o menu contextual de toque longo em si. A automação não consegue acionar um toque longo do SwiftUI, então a sequência menu → diálogo → diálogo é garantida por compilação e testes unitários, sem gravação no aparelho.

Passo 4

Responda ao pedido de permissão de onde você estiver

O Claude Code para e pergunta se pode rodar um comando. Âmbar é a única cor neste site que significa «um agente precisa de um humano», e é aqui que ela aparece — numa notificação que alcança o celular bloqueado.

Tela Bloqueada do iPhone: notificação sensível ao tempo do Moshpit — claude precisa de permissão para usar Bash em m1-pro

A pergunta, no celular bloqueado O título é o agente; o corpo diz o que ele está pedindo e onde — Claude needs your permission to use Bash — m1-pro · pit. Quando vários agentes esperam no mesmo host, eles dividem um único cartão: claude +2.

O toque Cai direto no painel que perguntou. Você lê o prompt em um terminal de verdade e responde com as mesmas teclas que apertaria na sua mesa.

Sem botão Permitir, de propósito Os botões na Tela Bloqueada que este app tinha antes mandavam uma tecla às cegas para o painel. Aprovar algo que você não leu, num app cujo valor inteiro é deixar você ler, era a troca errada — então eles saíram.

Como isso chega a um celular em que o app não está aberto

Seu host faz a parte que um iPhone suspenso não consegue. Os mesmos hooks que marcam o painel passam attention e done — nunca working — para um pequeno script remetente, ~/.moshpit/moshpit-push.sh, que sela o alerta com uma chave que só o seu celular tem e entrega o texto cifrado ao relay de push do Moshpit e depois à Apple. Nenhum dos dois consegue ler um byte sequer: nome do agente, comando e a própria pergunta são descriptografados dentro de uma extensão de notificação no seu celular, inclusive na Tela Bloqueada. O pareamento acontece sozinho na primeira vez que você ativa notificações em um host; a única confirmação que resta é a primeira instalação dos hooks.

Escopo, sem rodeios. O remetente pega carona nos hooks de agente, e os hooks marcam painéis do tmux — logo, o caminho de push com o app fechado exige o agente rodando sob tmux com os hooks instalados. Em um painel puro do herdr, o próprio agent_status do herdr alimenta a Dynamic Island e as notificações enquanto o Moshpit estiver vivo, e os avisos param quando o app para. Se acordar você com o app fechado é o ponto principal, rode o Claude Code em um painel do tmux por enquanto.

As quatro regras que mantêm o silêncio

Notificar por qualquer coisa é o mesmo que não notificar por nada, então um alerta precisa merecer a interrupção:

RegraO que significa
30 segundos parado Uma pergunta respondida na sua mesa dentro da janela de tolerância nunca é anunciada em nenhum celular.
Um cartão por host Todos os agentes esperando compartilham um resumo — «claude +2». Só a transição de ninguém esperando → alguém esperando toca e pode atravessar o Foco; tudo depois atualiza o cartão em silêncio.
Concluído só toca após 3 minutos Um turno concluído só faz som se levou três minutos ou mais. Turnos curtos entram na lista sem acender a tela.
Agentes parados ficam quietos Um lembrete ocioso de um agente que você deixou parado no prompt não acende nada — e um «precisa de você» abandonado há um dia se resolve sozinho como concluído.

Honestidade nas letras miúdas também: olhar um prompt dentro do app marca o aviso como visto, e reconectar ou reabrir o app nunca faz tocar de novo uma pergunta da qual você já foi avisado.

Os quatro controles que governam tudo

Ajustes → NOTIFICAÇÕES. Todos os quatro vêm ativados por padrão.

  • Notificações — «Avisar quando um agente precisar de você»
  • Atividade ao Vivo — «Mostrar o status do agente na Dynamic Island»
  • Som do alerta — «Tocar um som quando o agente precisar de você»
  • Mostrar detalhes na Tela Bloqueada — «Mostra o que o agente está executando ou perguntando — desativado, fica privado». Desativado, você ainda vê trabalhando / precisa de você / concluído, só não vê a linha Bash: npm install.

Desative Notificações e Atividade ao Vivo e nada é monitorado. A linha Configurar este host abaixo dos botões mostra o que o host conectado tem: quais agentes têm hooks, se o script de push está instalado e o pareamento salvo neste celular — a configuração em si é automática ao conectar.

Dynamic Island mostrando ponto âmbar e exclamação: um agente precisa de você

Desbloqueado · precisa de você A pílula exibe uma exclamação âmbar quando um agente está bloqueado, ou o número quando há vários. Só cabe um agente na pílula — segure-a para ver os demais na visualização expandida.

Dynamic Island mostrando ponto turquesa e cronômetro ao vivo enquanto um agente trabalha

Desbloqueado · trabalhando Turquesa com cronômetro ao vivo enquanto o Claude Code está rodando. Um agente pensando e um agente travado não têm a mesma cara.

A parte honesta

O que acontece quando você coloca o app em segundo plano

Esta é a seção para ler antes de depender do que foi descrito acima. O push criptografado cobre o intervalo agora — e o que ele não cobre também está escrito aqui.

O iOS suspende a conexão, e as superfícies ao vivo pausam

Quando o iOS suspende o app, a varredura de 2 segundos e as consultas SSH param junto. O que atravessa esse intervalo é o caminho de push do passo 4: os hooks no seu host percebem attention e done e enviam o alerta selado por conta própria — sem sessão ativa, com o celular bloqueado e o app fechado.

O que não atravessa o intervalo: a Atividade ao Vivo. Ela mostra o último estado que o app viu, e com o app suspenso nada a alimenta. Medido no aparelho: com o Moshpit em segundo plano, mudar um painel de bloqueado para trabalhando deixou a Dynamic Island parada até a primeira consulta depois de voltar ao primeiro plano.

Por isso a ilha diz «pausado» em vez de mentir

Moshpit                      2 trabalhando · 1 precisa de você
●  claude                   PRECISA DE VOCÊ · 2m
   mac-studio · ~ · Aba 1
   Bash: npm install

… app suspenso por dois minutos …

Moshpit            pausado — abra o Moshpit para atualizar

A Atividade ao Vivo tem um limite de validade de 120 segundos — duas varreduras perdidas — e exibe um aviso honesto de «pausado» em vez de um «trabalhando» congelado. O widget da Tela de Início usa 180 segundos e apaga todos os pontos de estado para cinza quando fica desatualizado. Onde o remetente do passo 4 está instalado, as notificações push continuam chegando normalmente.

Mesmo em primeiro plano, mudanças externas têm atraso

  • A consulta de controle do herdr roda a cada 2 segundos enquanto há atividade, e desacelera para 8 segundos depois de três leituras idênticas. Qualquer mudança — ou puxar para atualizar — faz voltar na hora para 2 segundos.
  • Tudo o que você faz dentro do app atualiza imediatamente — cada ação dispara uma nova leitura. O que acontece fora dele (no notebook, em outro cliente ou um agente mudando de estado) pode levar até 8 segundos para aparecer.
  • É por isso que o tempo decorrido aparece em minutos — agora, 2m, 1h 12m — e nunca em segundos. O dado por trás tem granularidade de até 8 segundos, e mostrar segundos fingiria uma precisão que o número não tem.
  • A API de socket do herdr tem inscrição em eventos, mas a CLI não expõe comando de subscribe e um celular não consegue abrir um Unix socket no seu host. Polling é o único mecanismo disponível hoje.

Dois clientes Moshpit no mesmo painel vão brigar

O attach direto do herdr é exclusivo por painel. O Moshpit precisa conectar com --takeover, porque uma reconexão sempre colide com o próprio canal antigo. Dois celulares no mesmo painel acabam retomando um do outro a cada cerca de dois segundos. Isso é inerente ao attach exclusivo e não pode ser resolvido pelo cliente.

O que o Moshpit faz a respeito: três encerramentos não solicitados em 30 segundos acionam uma pausa de 30 segundos e um aviso visível — «Outro cliente está usando este painel. Tentando de novo em instantes» — que some assim que os quadros voltam a desenhar. Um notebook rodando a TUI própria do herdr não ocupa vaga de attach, então notebook + celular deve ser seguro, mas essa combinação não foi testada.

Pontas soltas

Perguntas que este guia costuma gerar

Eu sou obrigado a usar herdr?

Não. No tmux, instale os hooks de agente em Ajustes → NOTIFICAÇÕES → Instalar hooks de agente — um comando que registra os hooks UserPromptSubmit, PreToolUse, Notification e Stop do Claude Code para marcarem o estado no painel do tmux. Ele faz backup de ~/.claude/settings.json antes, sempre termina com código 0 para nunca travar o agente e evita duplicação se você rodar duas vezes. Sem hooks, o Moshpit recorre à leitura da saída do painel e ao sino do terminal, o que é um palpite e é tratado como tal. A seção Agentes no Início é exclusiva do herdr.

Ele consegue me avisar com o Moshpit fechado?

Sim — é para isso que o caminho de push existe. Os hooks no seu host selam o alerta com uma chave que só o seu celular possui e o enviam pelo relay do Moshpit; uma extensão de notificação descriptografa tudo na Tela Bloqueada, com o app fechado e o celular bloqueado. Vale a nota de escopo do passo 4: o remetente usa os hooks de agente que marcam painéis do tmux, então rode o agente no tmux se essa for a parte que importa para você. As regras de silêncio — 30 segundos de tolerância, um cartão por host, concluído só toca após três minutos, agentes parados em silêncio — estão em Respondendo a agentes.

E quanto ao Mosh?

O Mosh é a escolha certa para um shell que precisa sobreviver à troca de Wi-Fi para 5G, mas ele não consegue transportar o protocolo de quadros do herdr nem o tmux -CC. Sobre Mosh, o herdr roda a própria TUI dentro do terminal e ocupa cerca de um terço da largura do celular com a barra lateral; as folhas de controle continuam funcionando por um canal SSH separado. Para este guia, use SSH. Detalhes em Mosh e roaming.

O Claude Code está rodando, mas a seção Agentes está vazia.

Quase certamente ele não está rodando dentro de um painel do herdr. O herdr identifica agentes observando os próprios painéis, então um claude iniciado no Terminal.app ou numa sessão SSH separada é invisível para ele. Inicie-o por Nova tarefa de agente ou rode dentro de um painel do herdr. No herdr 0.7.3 há um segundo efeito: o nome do agente não é informado, então um agente ocioso nunca gera uma linha.

O Moshpit lê meu código, meus prompts ou qualquer outra coisa?

Não existe conta do Moshpit nem telemetria, e o tráfego do terminal só vai para os servidores que você adicionou. A única peça operada pelo Moshpit é o relay de push, que só carrega texto cifrado que não consegue abrir — o alerta é selado no seu host com uma chave que só o seu celular tem. A única coisa que sai do painel é o título curto do hook — o que o agente está executando ou perguntando, limitado a 80 caracteres —, que viaja selado e aparece só na sua Tela Bloqueada.

Para onde vou agora?

Conexões e chaves para ver o formulário completo e o comportamento das chaves de host, Usando o herdr para o vocabulário e atalhos e Respondendo a agentes para os detalhes de notificações e Atividade ao Vivo. Se algo não conectar ou se comportar de forma estranha, comece por Solução de problemas.

Continue com Acessar sua máquina de qualquer lugar · Voltar aos guias