Remote Harness GitHub ↗

O daemon

Vale para 0.7+

O daemon roda no computador: acompanha os transcripts das sessões, controla o tmux, recebe os hooks do Claude Code em 127.0.0.1 e atende o app por dois caminhos com a mesma criptografia de ponta a ponta: direto, num WebSocket que escuta em todas as interfaces (a rede de casa, ou qualquer endereço de VPN do computador), e pelo seu relay de conexão, onde mantém uma sala aberta. remote-harness --help é a fonte da verdade para os comandos.

Comandos

Comando O que faz
remote-harness setup Instalação guiada: contas e aliases, hooks, serviço, pareamento. --yes mantém a configuração, --lang escolhe o idioma.
remote-harness start Roda o daemon em primeiro plano. --dev prende só a 127.0.0.1 e nunca usa relay, --host define o endereço direto.
remote-harness pair Pede ao daemon em execução um QR code de pareamento: ele pareia um celular e expira em 5 minutos.
remote-harness doctor Confere as ferramentas, a configuração, os perfis e as chaves de provedor, a identidade do daemon, se os relays de conexão respondem, o serviço, o push e os celulares registrados.
remote-harness install / uninstall Instala ou remove os atalhos, a entrada no PATH, os hooks e o wrapper da status line, sem perguntas.
remote-harness service install / uninstall / status O serviço em segundo plano: um LaunchAgent do launchd no macOS, uma unidade de usuário do systemd no Linux e no WSL.
remote-harness update Baixa a nova versão, recompila, atualiza os hooks e reinicia o serviço. `--ref <branch
remote-harness updates status / check / `channel [main development]/auto on
remote-harness push status / test Modo de push em uso e celulares registrados; envia uma notificação de teste.
remote-harness push off / on Para (ou volta a enviar) todos os pushes e o status ao vivo deste computador, sem reiniciar o daemon.
remote-harness provider key <perfil> Guarda a chave do provedor (OpenRouter) de um perfil no cofre do sistema. --stdin lê de um pipe.
remote-harness devices list / revoke <id> Os celulares e tablets pareados com este computador (ID, nome, plataforma, pareado em, visto por último); revoke desconecta um, que precisa parear de novo.
remote-harness rules list / undo <id> As regras "permitir sempre" criadas pelo celular.
remote-harness approvals list O registro de aprovações: o que os aparelhos permitiram, negaram, desfizeram e apagaram (últimos 30 dias).
`remote-harness commands [on off]`

O comando antigo claude-remote e as variáveis CLAUDE_REMOTE_* continuam funcionando em instalações feitas antes da mudança de nome.

Arquivo de configuração

~/.remote-harness/config.json (uma instalação anterior à mudança de nome é movida para lá pelo próximo remote-harness update, e ~/.claude-remote vira um link para ela):

{
  "profiles": [
    { "id": "pessoal", "name": "Pessoal", "configDir": "~/.claude", "color": "#D97757" },
    { "id": "trabalho", "name": "Trabalho", "configDir": "~/.claude-work", "color": "#61AFEF" }
  ],
  "wsPort": 7337,
  "hookPort": 7338,
  "defaultRuleScope": "project",
  "permissionTimeoutSec": 280,
  "questionTimeoutSec": 3300,
  "inputStrategy": "paste",
  "recentDays": 7,
  "tmuxSession": "claude-remote",
  "tmuxSocket": "remote-harness",
  "tmuxConfig": "minimal",
  "push": "auto",
  "update": { "channel": "main", "auto": false },
  "tray": true,
  "relays": ["wss://us.relay.remoteharness.app", "wss://br.relay.remoteharness.app"],
  "relay": "on",
  "direct": "on"
}
  • profiles: um por conta do Claude Code. id é o alias (o nome do atalho), configDir o CLAUDE_CONFIG_DIR da conta, color a cor da etiqueta no app. Opcionais: agent (claude por padrão) e provider (abaixo).
  • wsPort, hookPort: as portas do app e dos hooks.
  • defaultRuleScope: para onde vão as regras "permitir sempre" por padrão, project ou user.
  • permissionTimeoutSec: quanto tempo o daemon segura um pedido de permissão para o celular antes de o diálogo do terminal assumir. O pedido continua no app como "Responda no terminal" até a sessão seguir.
  • questionTimeoutSec: o mesmo para perguntas e aprovação de plano (3300 por padrão). Uma pergunta ainda aberta depois de 10 minutos manda um push de lembrete. O timeout do hook gravado nas configurações do agente cobre os dois, e remote-harness install ou update o reescreve.
  • inputStrategy: paste (padrão) ou type para os prompts enviados pelo celular.
  • recentDays: até quando sessões encerradas são listadas.
  • tmuxSession: a sessão do tmux que os atalhos usam.
  • tmuxSocket: o servidor tmux (tmux -L <nome>) que os atalhos e o daemon usam, remote-harness por padrão, separado do seu tmux e do seu tmux.conf; null usa o seu servidor padrão e a sua configuração.
  • tmuxConfig: minimal (padrão) inicia esse servidor só com os poucos ajustes do Remote Harness (Esc entregue na hora, eventos de foco, histórico maior); user carrega também o seu ~/.tmux.conf (ou ~/.config/tmux/tmux.conf) por cima, para os seus atalhos valerem dentro das janelas do agente.
  • language: pt-BR, en-US ou es-ES para a CLI, a instalação e os textos de push; o idioma do sistema quando ausente.
  • push: auto (a sua conta de serviço do Firebase quando existe, senão o relay) ou off.
  • update: o canal que update e a verificação seguem, e se as atualizações se aplicam sozinhas.
  • tray: o ícone na barra de menus / bandeja.
  • relays: os relays de conexão que o daemon pode usar. Ao iniciar ele mede todos e mantém a sala no mais rápido, trocando só quando ele cai; troque a lista para hospedar o seu.
  • relay: off deixa o daemon fora dos relays (os celulares só o alcançam direto). direct: off para de escutar conexões diretas (só o relay). Não os dois. start --dev nunca usa relay.
  • trayPermissions: se a bandeja oferece Permitir / Sempre permitir / Negar para uma permissão pendente (ligado por padrão; também nas Preferências da bandeja).
  • shellCommands: enabled (desligado por padrão; mude com remote-harness commands on|off), timeoutSec (300) e maxOutputKb (1024) para os comandos rodados pelo app.

Mudanças no arquivo valem quando o daemon reinicia (remote-harness service install de novo, ou reiniciar pela bandeja).

Perfis e OpenRouter

Um perfil pode rotear o Claude Code pelo OpenRouter em vez da conta Anthropic. O jeito mais fácil é remote-harness setup → "Adicionar um perfil OpenRouter": ele pergunta o nome, o alias, a pasta (~/.claude-openrouter), um modelo padrão opcional e a chave (oculta), confere a chave com o OpenRouter e mostra os créditos restantes quando a chave consegue lê-los. Rodar o setup de novo lista esses perfis e deixa manter, trocar a chave ou remover o perfil (o atalho, os hooks e a chave; a pasta fica).

À mão: acrescente um provider com kind: "openrouter" e, opcionalmente, baseUrl (outro gateway compatível com a Anthropic), um model padrão e um smallFastModel.

{
  "id": "openrouter",
  "name": "OpenRouter",
  "configDir": "~/.claude-openrouter",
  "color": "#8A8784",
  "provider": { "kind": "openrouter", "model": "anthropic/claude-sonnet-5.5" }
}

Depois, remote-harness install regenera os atalhos e remote-harness provider key openrouter guarda a chave no mesmo cofre das chaves do próprio daemon (Keychain no macOS, Secret Service ou arquivo 0600 no Linux). O atalho lê a chave só dentro da janela do tmux, nunca numa linha de comando, e o daemon só a usa para mostrar os seus créditos no app. O doctor informa se cada perfil com provedor tem chave.

Perfis do Codex

Um perfil pode rodar o OpenAI Codex CLI em vez do Claude Code: defina "agent": "codex" e aponte configDir para a pasta do Codex (CODEX_HOME, ~/.codex por padrão). O remote-harness setup oferece ~/.codex quando o Codex já o usou.

{ "id": "cdx", "name": "Codex", "configDir": "~/.codex", "color": "#2FBF8F", "agent": "codex" }

O remote-harness install grava o atalho do perfil (ele abre o codex com o CODEX_HOME certo) e mescla os hooks do daemon em <CODEX_HOME>/hooks.json, ao lado dos seus e com backup; o seu config.toml não é alterado. O Codex pede uma vez para confiar em hooks novos: abra o codex e escolha "Trust all and continue" (ou revise em /hooks). Até lá, as sessões dele aparecem somente leitura e as aprovações ficam no terminal. O doctor verifica se o codex está no PATH e se os hooks estão instalados.

O que funciona como no Claude Code: a lista de sessões (rollouts recentes em sessions/), a conversa, prompts, fotos e teclas, iniciar e retomar pelo celular (num worktree com codex --worktree, e com nome, enviado como /rename), push, status ao vivo, aprovações com Permitir / Negar, Aprimorar ditado e mensagens de commit geradas (via codex exec). Diferenças: o chip de modo mostra o perfil de permissões e alterna entre somente leitura e workspace (/permissions, Codex 0.164 ou mais novo); acesso total só no terminal. Não há "Sempre" (hooks do Codex não criam regras) nem provedor.

Perfis do Gemini CLI

Um perfil pode rodar o Gemini CLI do Google: defina "agent": "gemini" e aponte o configDir para uma pasta de configuração do Gemini, que sempre se chama .gemini (~/.gemini por padrão; para outra, ~/work/.gemini, o atalho define GEMINI_CLI_HOME=~/work). O remote-harness setup oferece a ~/.gemini quando o Gemini CLI já a usou.

{ "id": "gem", "name": "Gemini", "configDir": "~/.gemini", "color": "#E3729E", "agent": "gemini" }

O remote-harness install grava o atalho do perfil (ele abre o gemini) e mescla os hooks do daemon no <configDir>/settings.json, ao lado dos seus hooks e configurações e com backup. O Gemini CLI não roda hooks numa pasta em que ele não confia: quando o gemini perguntar, confie na pasta (ou use /permissions). Até lá, as sessões dele nessa pasta aparecem somente leitura e as aprovações ficam no terminal. O doctor confere se o gemini está no PATH e se os hooks estão instalados.

O que funciona como no Claude Code: a lista de sessões (arquivos de sessão recentes em tmp/), a conversa (comandos de shell, edições e buscas em arquivos aparecem como os do Claude Code), prompts, fotos e teclas, iniciar e retomar pelo celular, push e status ao vivo. Aprovações: os hooks do Gemini CLI não conseguem aprovar uma ferramenta, então quando o diálogo de aprovação dele abre o celular recebe Permitir / Negar e o daemon aperta as teclas do próprio diálogo no terminal ("Allow once" ou Esc); se o diálogo já foi respondido lá, o app avisa. Diferenças: sem "Sempre", sem troca de modo (e nunca YOLO), sem worktree nem nome ao iniciar, sem ditado com Polish nem mensagens geradas, e sem provedor.

Perfis do Kimi CLI

Um perfil pode rodar o Kimi CLI da Moonshot: defina "agent": "kimi" e aponte o configDir para a pasta de dados do Kimi (KIMI_SHARE_DIR, ~/.kimi por padrão). O remote-harness setup oferece a ~/.kimi quando o Kimi CLI já a usou.

{ "id": "km", "name": "Kimi", "configDir": "~/.kimi", "color": "#5B9BF5", "agent": "kimi" }

O remote-harness install grava o atalho do perfil (ele abre o kimi com o KIMI_SHARE_DIR certo) e adiciona os hooks do daemon ao <configDir>/config.toml como tabelas [[hooks]], no fim e com backup; todas as outras linhas do arquivo ficam como estão. Se o seu config.toml define hooks = [...] como uma chave só, o install não mexe nele e o doctor mostra os hooks como ausentes: troque por tabelas [[hooks]] antes. O doctor confere se o kimi está no PATH e se os hooks estão instalados.

O que funciona como no Claude Code: a lista de sessões (sessões recentes em sessions/), a conversa (comandos de shell, edições e buscas em arquivos aparecem como os do Claude Code), prompts, fotos e teclas, iniciar e retomar pelo celular, push e status ao vivo. Aprovações: o Kimi CLI não tem hook para elas, então enquanto uma sessão do Kimi roda o daemon olha o painel do tmux dela a cada segundo; quando o painel de aprovação aparece, o celular recebe Permitir / Negar e o daemon aperta as teclas do próprio painel ("Approve once" ou "Reject"). Se você responder no terminal, o pedido some sozinho. Diferenças: sem "Sempre" (nem "aprovar nesta sessão"), sem modo plano, yolo ou afk pelo app, sem worktree nem nome ao iniciar, sem ditado com Polish nem mensagens geradas, e sem provedor. Um turno cancelado com Esc continua "rodando" no app até o próximo prompt.

Perfis do Qwen Code

Um perfil pode rodar o Qwen Code: defina "agent": "qwen" e aponte o configDir para a pasta de configuração do Qwen (QWEN_HOME, ~/.qwen por padrão). O remote-harness setup oferece a ~/.qwen quando o Qwen Code já a usou.

{ "id": "qw", "name": "Qwen Code", "configDir": "~/.qwen", "color": "#8C6CF5", "agent": "qwen" }

O remote-harness install grava o atalho do perfil (ele abre o qwen com o QWEN_HOME certo) e mescla os hooks do daemon no <configDir>/settings.json, ao lado dos seus hooks e configurações e com backup. O doctor confere se o qwen está no PATH e se os hooks estão instalados.

O que funciona como no Claude Code: a lista de sessões (transcripts recentes em projects/), a conversa (comandos de shell, edições e buscas em arquivos aparecem como os do Claude Code), prompts, fotos e teclas, iniciar e retomar pelo celular, push, status ao vivo e aprovações com Permitir / Negar pelo próprio hook de permissão do Qwen. Diferenças: sem "Sempre", sem troca de modo de aprovação (e nunca auto nem YOLO), sem worktree nem nome ao iniciar, sem ditado com Polish nem mensagens geradas, e sem provedor. Um QWEN_RUNTIME_DIR personalizado ainda não é suportado.

Atalhos e aliases

Cada perfil ganha um pequeno atalho em zsh em ~/.remote-harness/bin/<alias> (adicionado ao PATH em ~/.zshrc e ~/.bashrc). Rode o alias em vez de claude, com os mesmos argumentos: ele abre o Claude Code numa janela da sessão claude-remote no servidor tmux próprio do Remote Harness (tmux -L remote-harness, iniciado com ~/.remote-harness/tmux.conf em vez do seu tmux.conf, então as suas configurações, plugins e o seu tmux ls ficam em paz) com o CLAUDE_CONFIG_DIR certo e prende o seu terminal nela. Rode o alias dentro do seu próprio tmux e a sessão aparece aninhada naquele pane, sem tomar o seu cliente (aperte o prefixo duas vezes para falar com o tmux de dentro). remote-harness tmux anexa a esse servidor de qualquer terminal e remote-harness tmux ls lista as sessões dele; sessões iniciadas antes desse servidor existir continuam no seu tmux padrão até terminarem. O comando claude puro nunca é alterado.

Serviço em segundo plano

remote-harness service install mantém o daemon rodando depois que você fecha o terminal e o inicia no login: um LaunchAgent no macOS (aparece como item de login), uma unidade de usuário do systemd no Linux (~/.config/systemd/user/remote-harness.service). Em servidores Linux acessados por SSH, a instalação oferece loginctl enable-linger, para o serviço sobreviver ao logout; Servidor na nuvem explica como rodar o daemon numa VM na nuvem. Sem systemd (contêineres, alguns WSL) rode remote-harness start você mesmo, por exemplo numa janela do tmux. No WSL a instalação também pode criar uma tarefa agendada do Windows que inicia a distribuição no logon.

remote-harness service status mostra se está carregado; o menu da bandeja reinicia.

Atualizações e canais

O serviço confere o canal dele no remoto git a cada 6 horas e mostra uma notificação na área de trabalho quando há versão nova (nunca num clone de desenvolvimento). remote-harness update aplica; remote-harness updates auto on deixa o daemon se atualizar sozinho, só quando nenhuma sessão está rodando ou esperando e nenhuma permissão está pendente, e nunca para uma versão mais antiga. remote-harness updates channel development segue a branch de integração; voltar para main avisa que instala uma versão mais antiga.

Ícone na bandeja

O daemon do serviço mostra um ícone na barra de menus do macOS (um pequeno auxiliar em Swift compilado no primeiro início com as Command Line Tools) e um ícone na bandeja do Linux (python3 com GTK 3 e AyatanaAppIndicator3 ou AppIndicator3). O menu mostra as sessões em andamento e as permissões pendentes (responda por ali), abre uma sessão nova, mostra o código de pareamento, confere ou aplica atualizações, escolhe o canal, abre os logs, a configuração e a documentação, e reinicia o daemon. Parear um celular mostra o QR de pareamento no próprio menu no macOS, o endereço e o pareamento no terminal; cada código é de uso único e expira em 5 minutos. Preferências liga e desliga as respostas de permissão no menu, o modo de manter acordado e as notificações push, aplicados na hora, e abre o arquivo de configuração para o resto. Com o serviço, Sair esconde o ícone ou para o serviço até o próximo login. "tray": false desliga; sem o auxiliar, o daemon roda sem interface. No WSL o ícone aparece na área de notificação do Windows: o daemon inicia um pequeno auxiliar no lado do Windows via interop (o Windows PowerShell o compila na hora; nada é instalado no Windows), então ele aparece no login com a tarefa de logon e some quando o daemon para. Tem o mesmo menu da bandeja do Linux, as notificações de atualização viram notificações do Windows e as ações que abrem um terminal usam o Windows Terminal.

No macOS o ícone abre um popover em vez de um menu: o computador com seus caminhos (direto e/ou pelo relay, nunca um endereço), a permissão pendente como um cartão com Negar / Sempre / Permitir, até cinco sessões (clique para abrir uma no terminal, clique direito para renomear ou fechar), os dispositivos pareados e se estão online, e as ações rápidas. A janela de Preferências tem as abas Geral, Perfis (renomeie um perfil), Notificações, Rede (os endereços do caminho direto, o relay de conexão e o relay principal, os dispositivos conectados agora), Dispositivos (cada dispositivo pareado, com Revogar…), Pareamento, Atualizações e Avançado. No Linux o menu segue a mesma ordem, e cada dispositivo tem um submenu Revogar….

Hospedar o próprio relay de conexão

Quando o celular não alcança o computador diretamente, o daemon e o app se encontram num relay de conexão: us.relay.remoteharness.app e br.relay.remoteharness.app por padrão. O relay só repassa o tráfego que o daemon e o app criptografam de ponta a ponta; ele não consegue ler sessões, prompts nem arquivos, e não guarda log do que passa nem de endereços IP. Rodar o seu é um contêiner:

docker build -t remote-harness-relay apps/relay
docker run -d --restart unless-stopped -p 8080:8080 remote-harness-relay

Coloque-o atrás de um proxy que termine o TLS (Traefik, Caddy, nginx), para ser acessado por wss://, e defina RELAY_CLIENT_IP_HEADER com o cabeçalho em que o proxy põe o endereço do cliente (X-Real-Ip, por exemplo), para que os limites por endereço vejam o cliente real. GET /healthz responde {"status":"ok"}. Os limites vêm do ambiente: RELAY_MAX_DEVICES (10 celulares por computador), RELAY_MAX_FRAME_BYTES (8 MB), RELAY_ROOM_RATE_BYTES e RELAY_ROOM_BURST_BYTES (banda por computador), RELAY_IDLE_TIMEOUT, RELAY_IP_CONNECTS_PER_MINUTE, RELAY_IP_BURST e RELAY_IP_MAX_CONNS.

Depois liste-o no arquivo de configuração do daemon, no lugar dos relays padrão ou antes deles:

{ "relays": ["wss://relay.example.com"] }

Pareie o celular de novo em seguida: o código de pareamento diz ao app qual relay usar.

Dados e logs

Tudo o que o daemon guarda fica em ~/.remote-harness/: config.json, state.json (as sessões conhecidas), secrets/ (chaves de provedor quando o cofre é o arquivo), models-cache.json, bin/ (atalhos), logs/ e src/ (o código que o instalador compilou). Anexe os logs a um relato de bug depois de remover tokens e conteúdo de sessões.

Variáveis de ambiente: REMOTE_HARNESS_HOME muda a pasta de dados, REMOTE_HARNESS_TOKEN_STORE=keychain|secret-tool|file força o cofre de segredos (as chaves do daemon e as de provedor), REMOTE_HARNESS_LANG define o idioma.