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.
claude em um painel do herdr, ou deixe o Moshpit criar
um novo git worktree e iniciar o Claude Code lá dentro.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 —
SenhaouChave 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-toplevele uma varredura em$HOMEordenada 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 campoCaminho do repositório. - Branch — validado no celular antes de qualquer ida ao servidor. Nomes vazios,
espaços,
-ou/no início,/no fim,.., sufixo.locke 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 priorizaclaude, depoiscodex, depois o primeiro da lista. (A ordem alfabética fazia o padrão cair emagynum 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-apiem 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.
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:
| Regra | O 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.
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.
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