Claude Command Runner

Servidor MCP para o Warp Terminal. Envia comandos do Claude para sua aba ativa do Warp via deeplinks warp:// e eventos OSC 777. Funciona a partir do Claude Desktop ou do painel de agente nativo do Warp. macOS, Swift.

GitHub

Experimente este MCPPatrocinado

Documentação

Warp Command Runner

Dê a qualquer IA de chat um terminal real. Você pergunta no Warp, Claude Desktop, ChatGPT desktop ou qualquer outro host MCP. O modelo digita o comando na sua aba do Warp, captura a saída e te conta o que aconteceu. Quarenta ferramentas: execução de comandos, configuração de projetos, monitoramento de arquivos, SSH, área de transferência, inteligência de ambiente. macOS, Swift, código aberto.

Isto é para quem não vive no Cursor ou no Claude Code. Se você já conversa com Grok, ChatGPT, Claude ou Gemini a partir de um app desktop (especialmente o painel de agente do Warp), adicione este MCP e esse chat poderá ler seus arquivos e executar comandos na sua máquina.

Feito para o Warp Terminal. As cinco ferramentas mais poderosas roteiam comandos visivelmente para a sua aba ativa do Warp. Registre o mesmo binário com quantos hosts MCP quiser — o servidor fala MCP padrão via stdio e não se importa com qual modelo está chamando.

Qualquer IA na nuvem pode usar isto? Qualquer host MCP local pode, via stdio. Apps de celular e sites precisam de MCP remoto: você executa --http e publica HTTPS com um túnel seu. Guia: docs/REMOTE.md. Matriz: docs/COMPATIBILITY.md.

O que há de novo na v8.0.0 — MCP remoto

Streamable HTTP opcional para Grok, ChatGPT e Claude chamarem este Mac a partir de um celular ou site. Você cria a URL HTTPS pública (seu túnel Cloudflare, seu Tailscale Funnel ou seu proxy reverso). Este projeto não hospeda um relay.

warp-command-runner --http escuta apenas em 127.0.0.1 (porta padrão 8741)
OAuth 2.1 com PKCE e Dynamic Client Registration
Ferramentas de roteamento Warp (keystroke) ficam desativadas para chamadas remotas; use execute_pipeline
--remote-doctor e --install-agent para um LaunchAgent de login

O stdio local não mudou. Detalhes: docs/REMOTE.md.

O que há de novo na v7.0.0 — rebranding

Antes chamado Claude Command Runner. Mesmo motor, nome agnóstico de host:

Produto, binário, bundle ID e diretório de configuração renomeados para Warp Command Runner (warp-command-runner, ~/.warp-command-runner)
Dados existentes de ~/.claude-command-runner são copiados no primeiro lançamento (a pasta antiga é mantida no lugar)
O nome do MCP serverInfo é Warp Command Runner para que todo host o liste dessa forma
Snippets de configuração para Warp, Claude Desktop, ChatGPT desktop, Cursor, VS Code e um host stdio genérico
Documentação honesta de compatibilidade: stdio MCP funciona em qualquer lugar onde exista um host local. MCP remoto é opcional na v8 (docs/REMOTE.md).

O histórico da v6.x (deeplinks do Warp, OSC 777, Warp Agent de consumo duplo, 40 ferramentas) não mudou — veja CHANGELOG.md.

Visão geral

Warp Command Runner é um servidor MCP. Um binário, qualquer cliente MCP:

Execute comandos de terminal a partir de uma conversa
Encadeie comandos com pipelines e modos de falha
Transmita saída para builds longos
Salve e reutilize modelos de comando com variáveis
Capture saída automaticamente com temporização inteligente
Acompanhe o histórico de comandos
Leia/grave a área de transferência do macOS
Investigue o contexto do ambiente (git, venv, Docker, Node)
Analise a saída de comandos em JSON estruturado
Gerencie perfis de workspace (opcionalmente como launch configs do Warp)
Abra abas do Warp via deeplinks warp:// e envie comandos para a aba ativa
Monitore arquivos e dispare comandos em mudanças
Execute comandos em hosts remotos via SSH
Exponha status no Warp como eventos OSC 777 warp://cli-agent
Shim de shell opcional: eventos preexec / command-finished via socket Unix

🧭 Em qual app devo registrar isto?

O protocolo é MCP. O valor depende de o host ser local e de o Warp ser o seu terminal. Detalhes em docs/COMPATIBILITY.md.

Host	Config	Recomendado?
Warp Agent (Grok, Claude, GPT, Gemini — o que o Warp estiver configurado)	`~/.warp/.mcp.json`	Sim — melhor ajuste. Veja docs/WARP_AGENT.md
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	Sim
ChatGPT desktop (Connectors / Developer Mode)	configurações MCP do host; snippet em `config/chatgpt-mcp.json`	Sim, se o seu plano expuser MCP local
VS Code / Continue / Cline / Windsurf	configurações MCP deles; veja `config/`	Opcional
Cursor	`~/.cursor/mcp.json`	Opcional — o Cursor já tem terminal
Claude Code	`~/.claude.json`	Nicho — ele já tem Bash
Chats de navegador / celular (chatgpt.com, grok.com, claude.ai)	URL de conector personalizado	Opcional — precisa de `--http` da v8 mais seu túnel HTTPS. `docs/REMOTE.md`

Árvore de decisão rápida

Você usa Warp e conversa com Grok / ChatGPT / Claude / Gemini dentro do Warp? → Registre em ~/.warp/.mcp.json. Esse é o produto inteiro.
Você usa Claude Desktop (ou ChatGPT desktop) e quer comandos visíveis no Warp? → Registre lá também. Mesmo binário.
Você usa Cursor ou Claude Code e quer tudo em um painel? → Provavelmente você não precisa disto.
Você só usa chatbot de site ou celular? → Stdio não alcança essa aba. Ative MCP remoto (docs/REMOTE.md) ou use um host MCP desktop.

Cinco das 40 ferramentas (execute_command, execute_with_auto_retrieve, execute_with_streaming, run_template, send_to_session) são as de roteamento Warp. As demais são utilitários comuns do lado do servidor (área de transferência, SSH, snapshots, …) que funcionam de qualquer host.

🎯 Principais recursos

Pipelines de comando

Encadeie vários comandos com tratamento inteligente de falhas:

{
  "steps": [
    {"name": "Build", "command": "swift build", "on_fail": "stop"},
    {"name": "Test", "command": "swift test", "on_fail": "continue"},
    {"name": "Package", "command": "swift build -c release", "on_fail": "stop"}
  ]
}

Modos de falha:

stop – Interrompe o pipeline em caso de falha
continue – Registra o erro e prossegue para a próxima etapa
warn – Mostra um aviso e continua

Transmissão de saída

Saída em tempo real para comandos de longa duração:

{
  "command": "swift build -c release",
  "update_interval": 3,
  "max_duration": 180
}

Perfeito para:

Processos de compilação longos
Suites de teste
Qualquer comando que antes "travava" esperando saída

Modelos de comando

Salve padrões reutilizáveis com substituição de variáveis:

// Save a template
{
  "name": "swift-release",
  "template": "cd {{project}} && swift build -c release",
  "category": "Swift Development",
  "description": "Build Swift project in release mode"
}

// Run with variables
{
  "name": "swift-release",
  "variables": {"project": "~/GitHub/MyApp"}
}

Os modelos são armazenados em ~/.warp-command-runner/templates.json e persistem entre sessões.

Recuperação automática inteligente

O comando execute_with_auto_retrieve detecta inteligentemente os tipos de comando e ajusta os tempos de espera:

Comandos rápidos (echo, pwd): 2–6 segundos
Comandos moderados (git, npm): até 20 segundos
Comandos de build (swift build, make): até 77 segundos
Comandos de teste: até 40 segundos

📊 Por que o Warp Terminal?

O Warp Terminal é o alvo principal de integração. Outros terminais funcionam para o básico — o Warp desbloqueia de forma exclusiva deeplinks, OSC 777, o painel de agente nativo e launch configs:

Recurso	Warp	Terminal.app	iTerm2
Deeplinks `warp://` para aba/janela	✅	❌	❌
Painel de agente MCP nativo — converse com Grok, ChatGPT, Claude, Gemini no terminal	✅ (`~/.warp/.mcp.json`)	❌	❌
Canal de eventos OSC 777 cli-agent para exibição de status	✅	❌	❌
Perfil de workspace → launch config reconhecido	✅ (`~/.warp/launch_configurations/`)	❌	❌
Nova aba via AppleScript + envio de keystroke	✅	✅	✅
UI/UX moderna	✅	⚠️	⚠️

A captura de saída (polling /tmp/<id>.json) e as ferramentas que não tocam no terminal (área de transferência, SSH, monitoramento de arquivos, snapshots de ambiente etc.) funcionam de forma idêntica em todos os terminais.

Baixe o Warp em warp.dev. É gratuito, e as superfícies específicas do Warp acima precisam dele.

Instalação

Pré-requisitos

macOS 13.0 ou posterior
Swift 6.0+ (Xcode 16+)
Pelo menos um host MCP local (Warp Agent, Claude Desktop, ChatGPT desktop, VS Code, …) — não uma aba de chat no navegador
Um terminal compatível (Warp fortemente recomendado)

Instalação rápida

Clone e compile:

git clone https://github.com/M-Pineapple/warp-command-runner.git
cd warp-command-runner

# For the 5 keystroke-routing tools (execute_command, etc.) to work, the build
# must be SIGNED with your code-signing identity. build.sh auto-detects a single
# Apple Development / Developer ID identity; to be explicit (or if you have
# several), export it first — find yours with:
#   security find-identity -v -p codesigning
export WCR_CODESIGN_IDENTITY="<your-cert-sha1>"   # optional if auto-detect finds one; persist in ~/.zshrc
./build.sh

Só precisa das 34 ferramentas sem keystroke (incl. execute_pipeline)? Um build sem assinatura é suficiente — pule o export.

Escolha seu(s) host(s) MCP — você pode registrar o mesmo binário em vários. Aponte para o binário dentro do bundle .app (macOS Sequoia+ precisa do Info.plist para prompts TCC nas 5 ferramentas de roteamento por keystroke):

A — Warp Agent (~/.warp/.mcp.json) — Grok, ChatGPT, Claude, Gemini, o que o Warp estiver configurado:
```
{
  "mcpServers": {
    "warp-command-runner": {
      "command": "/Applications/Warp Command Runner.app/Contents/MacOS/warp-command-runner",
      "args": []
    }
  }
}
```
Veja docs/WARP_AGENT.md.

B — Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) — mesma estrutura JSON. ChatGPT desktop, Cursor, VS Code, Continue: copie um snippet de config/ ou docs/COMPATIBILITY.md.

Após ./build.sh, você também pode apontar para $(pwd)/.build/release/warp-command-runner.app/Contents/MacOS/warp-command-runner antes de copiar o bundle para /Applications/.

Atualizando da v6.0.0–6.0.2? Edite seu arquivo de configuração existente e acrescente .app/Contents/MacOS/warp-command-runner ao caminho. O caminho legado do binário puro ainda funciona para as 34 ferramentas sem keystroke, mas execute_command / execute_with_auto_retrieve / execute_with_streaming / run_template / send_to_session falharão silenciosamente sem o caminho do bundle.
Conceda permissão de Acessibilidade (necessária apenas para injeção de keystroke send_to_session na v6.0; abertura de aba/janela usa deeplinks e não exige isso):
- Abra Ajustes do Sistema → Privacidade e Segurança → Acessibilidade
- Clique em + e navegue até warp-command-runner/.build/release/
- Pressione Cmd+Shift+. para revelar a pasta oculta .build
- Selecione o binário warp-command-runner e ative-o

Importante: o macOS rastreia permissões pela identidade do binário. Após cada recompilação (./build.sh), você deve remover a entrada antiga e adicionar o novo binário novamente nas configurações de Acessibilidade.

Reinicie seu(s) host(s) MCP (Warp, Claude Desktop, ChatGPT desktop, …).
(Opcional) Instale o shim de shell para captura mais limpa de limites de bloco:
```
helper/install-shim.sh
```
Veja helper/shell-shim.zsh / helper/shell-shim.bash para a implementação. Desinstale com helper/uninstall-shim.sh.

Atualizando de uma versão anterior

Se você já tem uma instalação assinada funcionando (permissões TCC concedidas), a atualização é:

cd warp-command-runner
git pull

# Rebuild with the SAME signing identity you used originally. Without it, build.sh
# falls back to an ad-hoc-signed bundle, macOS sees a new identity, and your
# keystroke (TCC) grants stop applying → error 1002 on execute_command.
# (build.sh auto-detects a single identity; export to be explicit.)
export WCR_CODESIGN_IDENTITY="<your-cert-sha1>"   # persist in ~/.zshrc so you don't forget
./build.sh

# Confirm it signed with your cert (NOT adhoc) BEFORE replacing your good bundle:
codesign -dvv .build/release/warp-command-runner.app 2>&1 | grep -E "Authority=Apple|Signature=adhoc"

# Replace the deployed bundle (rm first — cp -R onto an existing .app nests it):
rm -rf "/Applications/Warp Command Runner.app"
cp -R .build/release/warp-command-runner.app "/Applications/Warp Command Runner.app"

Depois reinicie seu host MCP. Se você atualizou da v6 e manteve o mesmo certificado de assinatura, as concessões TCC existentes em com.m-pineapple.claude-command-runner não são transferidas para com.m-pineapple.warp-command-runner — conceda novamente Acessibilidade / Monitoramento de Entrada / Acesso Total ao Disco / Automação para o novo bundle uma vez. Depois disso, recompilações com o mesmo certificado mantêm as concessões.

🛡️ Receita completa de configuração do macOS Sequoia (os 7 passos ordenados)

Se execute_command / execute_with_auto_retrieve / execute_with_streaming / run_template / send_to_session falharem com osascript is not allowed to send keystrokes (1002) mesmo depois de você alternar todos os painéis nos Ajustes do Sistema, siga isto em ordem — pular qualquer etapa deixa uma negação silenciosa em algum lugar da cadeia. As outras 34 ferramentas funcionam sem nada disso; execute_pipeline é um substituto totalmente funcional se você quiser pular toda a saga TCC.

Esta é a receita verificada empiricamente de uma sessão real de depuração de 6 horas. A v6.0.3+ traz a infraestrutura de bundle que torna isso possível; a v6.0.4 é esta passagem de documentação.

O padrão de negação. O TCC e o sandbox do macOS Sequoia têm requisitos em camadas, não óbvios, para binários CLI que controlam osascript → System Events → keystroke. A mensagem de erro é enganosa — o bloqueio real geralmente não é a permissão de keystroke; é uma verificação preliminar anterior que aborta silenciosamente a cadeia. Os cinco portões, na ordem em que o macOS os avalia:

Portão	Serviço TCC	O que o concede
1. Capacidade de prompt do bundle	(n/a — política)	Bundle em `/Applications/`, não `.build/release/`
2. Identidade estável do bundle	(n/a — codesign)	Assinado com um certificado estável (cdhash não varia entre recompilações)
3. Pré-verificação FDA do sandbox	`kTCCServiceSystemPolicyAllFiles`	Concessão de Acesso Total ao Disco no bundle
4. AppleEvents	`kTCCServiceAppleEvents`	Automação → System Events ☑
5. Síntese de keystroke	`kTCCServiceListenEvent` / `kTCCServicePostEvent`	Monitoramento de Entrada + Acessibilidade

Passo 1 — Tenha um certificado de desenvolvimento Apple (ou certificado de Code Signing autoassinado)

Se você tem uma conta de desenvolvedor Apple paga, já tem um (verifique via security find-identity -v -p codesigning). Se não, crie um autoassinado:

Acesso às Chaves → menu Assistente de Certificado → Criar Certificado…
Nome: warp-command-runner, Tipo de Identidade: Certificado Autoassinado, Tipo de Certificado: Assinatura de Código
Clique em Criar → Continuar pelos avisos → Concluído

Exporte o identificador do certificado para build.sh encontrar:

# Get the SHA-1 hash (more reliable than the cert name)
security find-identity -v -p codesigning
# Then in your shell rc (~/.zshrc, ~/.config/fish/config.fish, etc.):
export WCR_CODESIGN_IDENTITY="<the-sha1-hash-from-above>"

Etapa 2 — Compilar (cria o pacote `.app` assinado)

./build.sh

build.sh invoca scripts/make-app-bundle.sh, que envolve a CLI em .build/release/warp-command-runner.app/ com um Info.plist adequado (CFBundleIdentifier com.m-pineapple.warp-command-runner, as três strings NSXxxUsageDescription obrigatórias, LSUIElement=true). Se WCR_CODESIGN_IDENTITY estiver definido, o pacote é assinado com esse certificado como uma unidade — cdhash estável entre recompilações.

Verificar:

codesign --display --verbose=4 .build/release/warp-command-runner.app | grep -E 'Identifier|TeamIdentifier|CDHash'
codesign --verify --deep --strict .build/release/warp-command-runner.app  # should succeed silently

Etapa 3 — Instalar o pacote em `/Applications/` (CRÍTICO)

O macOS se recusa a solicitar permissões TCC para pacotes em .build/release/ ou outros diretórios de desenvolvimento. O pacote deve estar em /Applications/. Copie-o:

cp -R .build/release/warp-command-runner.app "/Applications/Warp Command Runner.app"

Verifique se a assinatura sobreviveu à cópia:

codesign --verify --deep --strict "/Applications/Warp Command Runner.app"

Etapa 4 — Aponte sua configuração MCP para o caminho `/Applications/`

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "warp-command-runner": {
      "command": "/Applications/Warp Command Runner.app/Contents/MacOS/warp-command-runner",
      "args": []
    }
  }
}

Espelhe em ~/.warp/.mcp.json se você usar o caminho do Warp Agent.

Etapa 5 — Redefina entradas TCC obsoletas para o ID do pacote

Se você está enfrentando negações TCC anteriormente, seu TCC.db provavelmente tem entradas Denied obsoletas de recompilações anteriores com cdhashes diferentes. Limpe-as para o pacote:

for svc in AppleEvents ListenEvent PostEvent Accessibility; do
    tccutil reset "$svc" com.m-pineapple.warp-command-runner
done

Cada linha deve imprimir "Successfully reset". Se você vir "no entries", tudo bem também — significa que o TCC não tinha nada registrado ainda.

Etapa 6 — Conceda as três permissões TCC (Acesso Total ao Disco é a surpresa)

Em Configurações do Sistema → Privacidade e Segurança, adicione /Applications/Warp Command Runner.app a cada um de:

Acesso Total ao Disco — inesperado, mas obrigatório. A sandbox do macOS faz uma verificação prévia de kTCCServiceSystemPolicyAllFiles antes de permitir que o osascript seja iniciado para cadeias de teclas. Sem FDA no pacote, a sandbox nega antes que a verificação de AppleEvents do TCC seja acionada, e você recebe o erro enganoso de "enviar teclas".
Monitoramento de Entrada — para kTCCServiceListenEvent / kTCCServicePostEvent (geração de teclas sintéticas).
Acessibilidade — para a própria ação AppleEvent keystroke.

Cada concessão requer Touch ID / senha de administrador para confirmar. O nome do pacote aparece como "Warp Command Runner" nos painéis.

Etapa 7 — Reinicie o Claude Desktop, acione uma vez, conceda o prompt de Automação

⌘Q Claude Desktop, reabra. No seu primeiro execute_command, o macOS pode mostrar mais um prompt — Automação → "Warp Command Runner quer controlar Eventos do Sistema" — clique em Permitir. Depois disso, é permanente. Recompilações futuras não redefinem nada (o certificado mantém o cdhash estável; o pacote mantém a identidade estável).

Diagnóstico: o que o TCC vê agora?

Se algo não funcionar após a receita, a única maneira confiável de descobrir qual porta está falhando é o log do TCC:

log show --predicate 'process == "tccd"' --last 30s --info --debug \
    | grep -E 'AUTHREQ_CTX|AUTHREQ_RESULT|m-pineapple|promptPolicy|Service Policy'

Acione um execute_command primeiro, depois execute imediatamente o comando acima. Leia para:

service="kTCCServiceXxx" — qual categoria de permissão está sendo verificada
promptPolicy = 0 → o macOS se recusa até a solicitar; geralmente um problema de localização (pacote não está em /Applications/)
promptPolicy = 2 + Denied (Service Policy) → você está sem a permissão para o serviço nomeado
AttributionChain: responsible={identifier=com.m-pineapple.warp-command-runner, ...} → bom, o TCC está nos identificando corretamente

Se você realmente não conseguir fazer funcionar

execute_pipeline é um substituto totalmente funcional para execute_command:

// instead of execute_command: {"command": "git status"}
// use:
{"steps": [{"command": "git status"}]}

Subprocesso puro, sem AppleScript, sem camada TCC, captura saída limpa, funciona em qualquer versão do macOS independentemente de permissões. O efeito colateral visível (comando aparecendo na sua aba Warp) é a única coisa que você perde — para a maioria dos fluxos de trabalho de agentes, isso não é o que você realmente precisa de qualquer forma.

Uso

Ferramentas Disponíveis (40)

Em sessões --http, as cinco ferramentas de roteamento Warp são recusadas a menos que remote.allowKeystrokeTools seja verdadeiro. Use execute_pipeline. Veja docs/REMOTE.md.

Execução Principal

Ferramenta	Descrição	Caso de Uso
`execute_command`	Executar com recuperação manual de saída	Comandos simples
`execute_with_auto_retrieve`	Executar com recuperação automática inteligente	Uso mais comum ⭐
`execute_pipeline`	Encadear comandos com lógica condicional	Fluxos de trabalho de build, CI/CD
`execute_with_streaming`	Streaming de saída em tempo real	Builds longos, suítes de teste
`save_template`	Salvar padrão de comando reutilizável	Criar atalhos
`run_template`	Executar modelo salvo com variáveis	Executar padrões salvos
`list_templates`	Ver todos os modelos salvos	Gerenciar modelos
`delete_template`	Remover um modelo salvo por nome	Gerenciar modelos
`get_command_output`	Recuperar manualmente a saída do comando	Depuração
`preview_command`	Visualizar sem executar	Verificação de segurança
`suggest_command`	Sugerir comandos (passe `working_directory` para ideias conscientes de git/Swift/Node)	Descoberta
`list_recent_commands`	Ver histórico de comandos	Análises
`self_check`	Diagnósticos de saúde do sistema	Solução de problemas

Área de Transferência (v5.0)

Ferramenta	Descrição	Caso de Uso
`copy_to_clipboard`	Escrever texto na área de transferência do macOS	Compartilhar saída
`read_from_clipboard`	Ler conteúdo atual da área de transferência	Colar contexto

Notificações (v5.0)

Ferramenta	Descrição	Caso de Uso
`set_notification_preference`	Alternar notificações do macOS	Personalização

Inteligência de Ambiente (v5.0)

Ferramenta	Descrição	Caso de Uso
`get_environment_context`	Investigar estado de git, venv, Node, Docker	Consciência de contexto
`execute_and_parse`	Executar e analisar saída para JSON estruturado	Saída inteligente
`capture_environment`	Capturar instantâneo do seu ambiente de shell real (carrega seu perfil de login)	Comparação antes/depois
`diff_environment`	Comparar dois instantâneos de ambiente	Detecção de mudanças

Perfis de Workspace (v5.0)

Ferramenta	Descrição	Caso de Uso
`save_workspace_profile`	Salvar contexto de projeto como perfil nomeado	Troca de projeto
`load_workspace_profile`	Restaurar um contexto de projeto salvo	Retomar trabalho
`list_workspace_profiles`	Ver todos os perfis salvos	Organização
`delete_workspace_profile`	Remover um perfil de workspace	Limpeza

Sessões Multi-Terminal (v5.0)

Ferramenta	Descrição	Caso de Uso
`open_terminal_tab`	Abrir uma nova aba de terminal nomeada (Warp: via deeplink `warp://action/new_tab` na v6.0)	Processos de longa duração
`send_to_session`	Enviar comando para uma aba específica (tecla AppleScript; direcionamento de aba limitado no Warp)	Execução direcionada
`list_sessions`	Ver sessões de terminal ativas	Visão geral de sessões
`close_session`	Fechar uma sessão nomeada	Limpeza
`cleanup_sessions`	Remover em massa sessões obsoletas; opcionalmente fechar suas abas	Higiene

Detecção de Comandos Interativos (v5.0)

Ferramenta	Descrição	Caso de Uso
`check_interactive`	Classificar um comando para requisitos de TTY/stdin antes de executá-lo	Evitar travamentos de `vim`, `ssh`, `psql`, REPLs

Observação de Arquivos (v5.0)

Ferramenta	Descrição	Caso de Uso
`add_file_watch`	Observar diretório e acionar comando em mudanças	Auto-rebuild, auto-teste
`remove_file_watch`	Parar de observar um diretório	Limpeza
`list_file_watches`	Ver observadores ativos	Visão geral

Execução Remota SSH (v5.0)

Ferramenta	Descrição	Caso de Uso
`ssh_execute`	Executar comando em host remoto via SSH	Operações remotas
`save_ssh_profile`	Salvar perfil de conexão SSH	Conexão rápida
`list_ssh_profiles`	Ver perfis SSH salvos	Visão geral
`delete_ssh_profile`	Remover um perfil SSH	Limpeza

Warp v6.0 — deeplinks, OSC 777, shell shim

Ferramenta	Descrição	Caso de Uso
`focus_warp_session`	Enviar `warp://session/<uuid>` para focar um painel Warp (UUID deve ser um que o Warp reconheça — tipicamente dos eventos do shell shim opcional)	Retomar trabalho em um painel específico
`emit_warp_event`	Construir uma invocação `printf` que emite um evento JSON OSC 777 `warp://cli-agent` na interface do Warp. Esquema: `session_start` / `prompt_submit` / `tool_complete` / `stop` / `permission_request` / `idle_prompt`. O `printf` retornado deve ser executado dentro de um painel Warp (ex.: via `execute_command`) para ter efeito	Notificações de status
`shell_shim_status`	Relatar estado do socket do shell shim opcional e eventos recentes	Verificar se o shim está conectado

Fluxos de Trabalho de Exemplo

Comando Simples:

You: "Check my Swift version"
Assistant: [execute_with_auto_retrieve: swift --version]
Assistant: "You're running Swift 6.0.2"

Pipeline de Build:

You: "Build, test, and package my app"
Assistant: [execute_pipeline with build → test → package steps]
Assistant: "Pipeline complete! Build: ✅ Test: ✅ Package: ✅"

Build Longo com Streaming:

You: "Build this large project"
Assistant: [execute_with_streaming: swift build -c release]
Assistant: "Building... [live updates every 3 seconds]"
Assistant: "Build completed in 45 seconds!"

Usando Modelos:

You: "Save a template for deploying to staging"
Assistant: [save_template: name="deploy-staging", template="cd {{project}} && ./deploy.sh staging"]

You: "Deploy MyApp to staging"
Assistant: [run_template: name="deploy-staging", variables={project: "MyApp"}]

Contexto de Ambiente (v5.0):

You: "What's my current dev environment?"
Assistant: [get_environment_context]
Assistant: "You're on branch feature/auth, Python venv active, Node 20.11, 3 Docker containers running."

Perfis de Workspace (v5.0):

You: "Save this as my API project profile"
Assistant: [save_workspace_profile: name="api-project", directory="~/Projects/api", ...]

You: "Switch to the API project"
Assistant: [load_workspace_profile: name="api-project"]

Observação de Arquivos (v5.0):

You: "Rebuild whenever a Swift file changes"
Assistant: [add_file_watch: path="./Sources", pattern="*.swift", command="swift build"]
Assistant: "Watching ./Sources for *.swift changes. Will run swift build on each change."

Execução Remota SSH (v5.0):

You: "Check disk space on the staging server"
Assistant: [ssh_execute: host="staging.example.com", username="deploy", command="df -h"]
Assistant: "Here's the disk usage on staging..."

Configuração

O arquivo de configuração está localizado em ~/.warp-command-runner/config.json:

{
  "terminal": {
    "preferred": "auto",
    "fallbackOrder": ["Warp", "WarpPreview", "iTerm", "Terminal"]
  },
  "security": {
    "blockedCommands": ["rm -rf /", "format"],
    "maxCommandLength": 1000
  },
  "history": {
    "enabled": true,
    "maxEntries": 10000
  },
  "notifications": {
    "enabled": true,
    "soundEnabled": true,
    "showOnSuccess": false,
    "showOnFailure": true,
    "minimumDuration": 10
  },
  "fileWatching": {
    "maxWatchers": 5,
    "defaultDebounce": 2.0,
    "autoExpireMinutes": 60
  },
  "ssh": {
    "defaultTimeout": 30,
    "allowPasswordAuth": false
  },
  "interactiveDetection": {
    "enabled": true,
    "customPatterns": []
  }
}

Os modelos são armazenados separadamente em ~/.warp-command-runner/templates.json. Os perfis de workspace são armazenados em ~/.warp-command-runner/profiles.json. Os perfis SSH são armazenados em ~/.warp-command-runner/ssh_profiles.json.

🤔 Perguntas Frequentes

P: Grok, ChatGPT ou Gemini podem usar isso — não apenas Claude?

R: Sim, se você conversar dentro de um host MCP local. O painel de agente do Warp é o caminho usual: defina o modelo do Warp para Grok (ou GPT, Claude, Gemini) e registre este servidor em ~/.warp/.mcp.json. O desktop do ChatGPT e o Claude Desktop funcionam da mesma forma. Abas do navegador em grok.com / chatgpt.com / claude.ai não podem iniciar um processo local. Matriz completa: docs/COMPATIBILITY.md.

P: O que há de novo na v8.0.0?

R: MCP remoto opcional. warp-command-runner --http serve Streamable HTTP em loopback com OAuth 2.1. Você publica HTTPS com seu próprio túnel. Conectores de telefone e site podem então chamar este Mac. Ferramentas de teclas permanecem desligadas remotamente. Veja docs/REMOTE.md.

P: O que há de novo na v7.0.0?

R: Rebranding de Claude Command Runner para Warp Command Runner. Mesmas 40 ferramentas e protocolo MCP stdio; nomes, ID do pacote e caminhos ~/.warp-command-runner atualizados. A configuração v6 é copiada no primeiro lançamento.

P: O Cursor diz `spawn /Applications/Warp ENOENT`?

R: O Cursor divide command em espaços. O caminho oficial /Applications/Warp Command Runner.app/... está correto para Warp e Claude Desktop — não renomeie o .app. Para o Cursor, execute helper/install-cursor-wrapper.sh e aponte ~/.cursor/mcp.json para ~/.local/bin/warp-command-runner. Veja config/cursor-mcp.json.

P: O que há de novo na v6.0.0?

R: Re-pivô para Warp depois que o Warp se tornou open source. Arquitetura de consumidor duplo (registre o mesmo binário em ~/.warp/.mcp.json para usá-lo no painel de agente nativo do Warp, além do Claude Desktop). Deeplinks warp:// substituem cliques de menu AppleScript para operações de aba/janela. Novo emissor OSC 777 (emit_warp_event) apresenta eventos estruturados na interface do Warp. Novo shell shim opcional emite eventos limpos de preexec/comando-concluído para o MCP. Perfis de workspace agora também podem emitir configurações de lançamento nativas do Warp. ~460 LOC de código morto removidos. A contagem de ferramentas vai de um subestimado 36 (o README v5 afirmava 30) para 39. Veja CHANGELOG.md e docs/WARP_AGENT.md para a história completa.

P: O que havia de novo na v5.0.0?

R: Dez novas categorias de recursos elevando a contagem de ferramentas de 12 para 36 (o README v5 subestimou como 30; a tabela de despacho realmente registrou 36). Destaques: integração com área de transferência, notificações do macOS, inteligência de ambiente, análise de saída estruturada, perfis de workspace, sessões multi-terminal, observadores de arquivos, execução remota SSH.

P: Quando devo usar pipelines em vez de comandos regulares?

R: Use pipelines quando precisar de:

Múltiplos comandos sequenciais
Lógica condicional (parar em falha de build, continuar em falha de teste)
Um resumo de todas as etapas com tempo
Fluxos de trabalho estilo CI/CD

P: Por que meu comando "trava" com execute_with_auto_retrieve?

R: Para comandos muito longos, use execute_with_streaming. Ele fornece atualizações de saída em tempo real e lida com comandos que executam por minutos. Essa foi a principal motivação para adicionar streaming na v4.0.

P: Como uso templates com múltiplas variáveis?

R: Defina variáveis no seu template com a sintaxe {{variable_name}}:

{
  "template": "cd {{project}} && git checkout {{branch}} && swift build -c {{config}}"
}

Depois forneça todas as variáveis ao executar:

{
  "variables": {"project": "~/MyApp", "branch": "main", "config": "release"}
}

P: Onde meus templates são armazenados?

R: Em ~/.warp-command-runner/templates.json. Eles persistem entre sessões e reinicializações do host MCP.

P: Quanto tempo o auto-retrieve espera pelo meu comando?

R: Depende do tipo de comando:

Comandos simples: 6 segundos
Comandos Git/npm: 20 segundos
Comandos de build: 77 segundos
Comandos desconhecidos: 30 segundos

Para comandos mais longos, use execute_with_streaming.

P: Posso usar isso com Terminal.app ou iTerm2?

R: Sim, a execução básica de comandos funciona com qualquer terminal. Captura automática de saída e recursos específicos do Warp (deeplinks, OSC 777, painel de agente) precisam do Warp. Baixe em warp.dev.

P: É seguro deixar uma IA executar comandos?

R: Os comandos são enviados diretamente ao seu terminal e executados automaticamente — não há etapa manual de "pressionar Enter". Configure comandos bloqueados em ~/.warp-command-runner/config.json. Anexe este MCP apenas a um host confiável. Não o exponha como um servidor HTTP público.

P: O que acontece se uma etapa do pipeline falhar?

R: Depende da configuração on_fail:

stop – O pipeline para imediatamente, as etapas restantes são puladas
continue – O erro é registrado, o pipeline continua para a próxima etapa
warn – Um aviso é exibido, o pipeline continua

P: Posso aninhar pipelines ou executar templates dentro de pipelines?

R: Não diretamente. Você pode criar templates que contenham múltiplos comandos separados por && ou ;, ou compor chamando run_template e execute_pipeline na mesma conversa.

P: Onde meu histórico de comandos é armazenado?

R: Em um banco de dados SQLite em ~/.warp-command-runner/warp_commands.db. Ele rastreia todos os comandos, saídas, códigos de saída e tempos de execução.

🛠️ Solução de Problemas

Erro de Permissão no macOS: "osascript is not allowed to send keystrokes" (Erro 1002)

Este erro afeta as 5 ferramentas roteadas por AppleScript-keystroke (execute_command, execute_with_auto_retrieve, execute_with_streaming, run_template, send_to_session). As outras 34 ferramentas — incluindo execute_pipeline — não são afetadas.

Não perca horas alternando painéis das Configurações do Sistema. Este é um problema em camadas com a aplicação de TCC + sandbox do macOS Sequoia, e correções parciais deixam negações silenciosas em camadas mais profundas. A correção canônica é a 🛡️ receita completa de configuração do macOS Sequoia acima (na seção Instalação) — sete etapas ordenadas, incluindo: construir o bundle .app, instalar em /Applications/ (não em .build/), tccutil reset para o bundle ID, e conceder TRÊS permissões TCC, incluindo a surpresa (Acesso Total ao Disco no bundle — o sandbox verifica isso antes de permitir a cadeia de keystrokes). Siga de cima a baixo; pular qualquer etapa deixa uma negação oculta.

Triagem rápida — estou enfrentando isso?

Execute isto imediatamente após um execute_command falho:

log show --predicate 'process == "tccd"' --last 20s --info --debug | grep -E 'm-pineapple|promptPolicy|Service Policy'

Você verá um dos seguintes:

promptPolicy = 0 → o bundle não está em /Applications/ (ou não há bundle algum). Correção: Etapas 2-3 da receita.
promptPolicy = 2 + Denied (Service Policy) para kTCCServiceSystemPolicyAllFiles → falta Acesso Total ao Disco no bundle. Correção: Etapa 6 da receita.
AttributionChain: responsible={identifier=warp-command-runner, ...} (sem m-pineapple) → você não está executando a partir do bundle, está executando o binário puro. Correção: execute novamente ./build.sh e atualize sua configuração MCP para o caminho .app (Etapas 2-4 da receita).

Solução alternativa se você não quiser se preocupar com a receita:

// Use execute_pipeline instead of execute_command:
{"steps": [{"command": "git status"}]}

Subprocesso puro, sem AppleScript, zero TCC. Funciona em qualquer macOS independentemente de permissões. As 34 ferramentas não-keystroke também funcionam.

Referência de Bundle ID: com.m-pineapple.warp-command-runner (este projeto), com.anthropic.claudefordesktop (Claude Desktop).

Problemas de Permissão de Acessibilidade no macOS

O binário MCP requer permissão de Acessibilidade apenas para o caminho de keystrokes AppleScript usado por send_to_session (digitar em uma aba específica do Warp) e os caminhos legados não-Warp em execute_command para iTerm/Terminal/Alacritty. A maioria das ferramentas v6.0 funciona sem Acessibilidade: execução baseada em subprocesso, deeplinks warp:// para abrir abas, área de transferência, SSH, snapshots de ambiente, monitoramento de arquivos, perfis e todas as 24 ferramentas do lado do servidor.

Sintomas (quando isso importa):

Mensagem de erro: osascript is not allowed assistive access. (-1719)
send_to_session falha; área de transferência, SSH, contexto de ambiente, open_terminal_tab baseado em deeplink funcionam normalmente

Solução:

Abra Configurações do Sistema → Privacidade e Segurança → Acessibilidade

Clique no botão + e navegue até o binário warp-command-runner:

/path/to/warp-command-runner/.build/release/warp-command-runner

A pasta .build está oculta por padrão — pressione Cmd+Shift+. no Finder para revelá-la
Ative a permissão ativada para o binário

Importante: o macOS rastreia permissões de Acessibilidade por identidade do binário. Após cada swift build, o binário muda e você deve re-adicioná-lo à lista de Acessibilidade. Isso afeta apenas caminhos de injeção de keystrokes — a maioria das ferramentas não é afetada.

MCP Não Respondendo

Verifique os logs do cliente (Claude Desktop ou Warp). O servidor padrão é um filho do cliente via stdio. MCP remoto (--http) escuta apenas em 127.0.0.1 — veja docs/REMOTE.md.
Reinicie o cliente (Claude Desktop e/ou Warp).
Recompile com ./build.sh. (E re-adicione o binário à Acessibilidade se send_to_session estiver falhando.)

Comandos Não Aparecendo no Terminal

Certifique-se de que Warp/WarpPreview está em execução
Verifique os logs do Claude Desktop para erros
Verifique o caminho da sua configuração MCP

Streaming Não Atualizando

Verifique se o comando está realmente em execução (não aguardando entrada)
Aumente update_interval se as atualizações forem muito frequentes
Verifique /tmp/wcr_stream_*.log para arquivos de saída

Etapas do Pipeline Puladas Inesperadamente

Verifique a configuração on_fail – stop pulará as etapas restantes
Verifique se cada comando funciona individualmente primeiro
Verifique os códigos de saída no resumo do pipeline

Templates Não Salvando

Certifique-se de que o diretório ~/.warp-command-runner/ existe
Verifique as permissões de escrita em templates.json
Verifique a sintaxe JSON na definição do template

Auto-Retrieve Não Funcionando

Certifique-se de estar usando execute_with_auto_retrieve (não execute_command)
Verifique se o arquivo de saída do comando existe: ls /tmp/wcr_output_*.json
Para comandos longos, use execute_with_streaming

Problemas de Banco de Dados

Se os comandos executam mas não são salvos no banco de dados:

Verifique a integridade do banco de dados:

sqlite3 ~/.warp-command-runner/warp_commands.db "PRAGMA integrity_check;"

Se corrompido, faça backup e remova:

mv ~/.warp-command-runner/warp_commands.db ~/.warp-command-runner/warp_commands.db.backup
# Restart the MCP host — a new database is created automatically

Arquitetura

  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │ Warp Agent   │  │ Claude Desk. │  │ ChatGPT /    │
  │ (Grok, GPT,  │  │              │  │ Cursor / VS  │
  │  Claude, …)  │  │              │  │ Code / …     │
  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
         │ stdio MCP       │ stdio MCP       │ stdio MCP
         └─────────────────┴─────────────────┘
                           ▼
         ┌─────────────────────────────────┐
         │  warp-command-runner v7.0       │
         │  Swift MCP server · 40 tools    │
         └─────────┬───────────┬───────────┘
                   │           │
                   ▼           ▼
         ┌──────────────┐  ┌─────────────────────┐
         │ Warp Terminal│  │ Optional shell shim │
         │ warp://      │  │ /tmp/wcr-shell-shim-│
         │ OSC 777      │  │   <uid>.sock        │
         └──────────────┘  └─────────────────────┘

Qualquer host MCP local, um servidor. Operações de aba/janela usam o esquema de URL warp:// do Warp; eventos de status usam OSC 777; digitar em uma aba ainda usa keystrokes AppleScript (o Warp não tem API para isso). Chats de telefone e site precisam de --http além do seu próprio túnel HTTPS — veja docs/REMOTE.md.

Contribuindo

Adoramos contribuições! Veja como:

Faça um fork do repositório
Crie um branch de feature (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Configuração de Desenvolvimento

git clone https://github.com/M-Pineapple/warp-command-runner.git
cd warp-command-runner
swift package resolve
swift build

💖 Apoie Este Projeto

Se o Warp Command Runner ajudou a melhorar seu fluxo de trabalho de desenvolvimento ou economizou seu tempo com execução inteligente de comandos, considere apoiar seu desenvolvimento:

Seu apoio me ajuda a:

Manter e melhorar o Warp Command Runner com novos recursos
Manter o projeto open-source e gratuito para todos
Dedicar mais tempo para atender solicitações de usuários e correções de bugs
Explorar novas integrações de terminal e inteligência de comandos

Obrigado por considerar apoiar meu trabalho! 🙏

Licença

Licença MIT – veja o arquivo LICENSE para detalhes

Feito com ❤️, originalmente por 🍍 como Claude Command Runner. A v7 renomeia o mesmo MCP para qualquer host.

Se isso ajudar, dê uma estrela no repositório e experimente o Warp.