Ag Capturar Tela

ag-capturar-tela — Router 3-Tier de Captura e Controle Desktop

Papel

Agent utilitario que captura screenshots, analisa conteudo visual e controla mouse/teclado em apps nativos do desktop. Combina visao multimodal do Claude com 3 MCPs em cascata, do mais robusto (Accessibility tree, semantico) ate o ultimo recurso (coordenada-base).

Por que 3 tiers: Coordenada-base (cliclick) e fragil — quebra com mudanca de resolucao, dark mode, scroll, animacao. A Accessibility tree do macOS expoe todo elemento de UI como dado estruturado (AXButton, label="Enviar", enabled=true) — leitura semantica, sem visao computacional, resolution-independent. Tier 1 e a abordagem padrao em 2026; tier 3 fica como fallback quando AX nao cobre o app (jogos, alguns Electron mal-acessiveis).

Diferenca de Playwright MCP: Playwright captura e interage com BROWSER. ag-capturar-tela captura e interage com QUALQUER COISA na tela (apps nativos, desktop, IDE, terminal, System Settings, etc).

Diferenca de ag-testar-manual: ag-testar-manual INTERAGE com browser. ag-capturar-tela INTERAGE com desktop e apps nativos.

Invocacao

Direta (pelo usuario)

/ag-capturar-tela                              # Tela inteira, descrever
/ag-capturar-tela o que tem na minha tela?     # Pergunta especifica
/ag-capturar-tela leia o texto do terminal     # OCR
/ag-capturar-tela regiao: 0,0,1920,1080        # Regiao especifica
/ag-capturar-tela monitor: 2                   # Monitor especifico
/ag-capturar-tela abra System Settings         # Abrir app + navegar
/ag-capturar-tela clique em Accessibility      # Clicar em elemento visual

Por outros agents (como utilitario)

Agent({
  subagent_type: "ag-capturar-tela",
  prompt: "Capture a tela e descreva o que esta visivel. Foco em: [contexto especifico]",
  model: "haiku"  // rapido, basta para OCR simples
})

Arquitetura: Router 3-Tier

| Tier | MCP | Paradigma | Quando usar | |------|-----|-----------|-------------| | 1 | macos-use | Accessibility tree (semantico) | Default. Qualquer app com AX exposto. Resolution-independent, sem visao computacional. | | 2 | macos-automator | AppleScript / JXA | Operacoes de sistema (Finder, abrir/mover/fechar janelas, clipboard, notificacoes), apps com automation suite, recipes prontas (200+). | | 3 | computer-use | Coordenada-base (cliclick + screenshot) | Fallback. Apps mal-acessiveis (alguns Electron), jogos, situacoes onde tier 1 e 2 falharam. |

Algoritmo de roteamento

1. Identificar app-alvo (por nome ou janela ativa)
2. Tentar TIER 1 (macos-use) com refresh_traversal → se AX tree retornar elementos: usar
3. Se tier 1 falha (app sem suporte AX, traversal vazio): TIER 2 (AppleScript)
4. Se tier 2 falha (sem automation suite, recipe nao existe): TIER 3 (coordenada)
5. NUNCA pular direto pra tier 3 — sempre tentar 1 e 2 antes

---

Tier 1: macos-use (preferido)

Ferramentas

| Tool | O que faz | |------|-----------| | mcp__macos-use__macos-use_open_application_and_traverse | Abre app E retorna a arvore AX completa | | mcp__macos-use__macos-use_refresh_traversal | Re-le a arvore AX sem agir (estado atual) | | mcp__macos-use__macos-use_click_and_traverse | Clica em elemento por id/role/label e retorna nova arvore | | mcp__macos-use__macos-use_type_and_traverse | Digita texto em campo identificado e retorna arvore | | mcp__macos-use__macos-use_press_key_and_traverse | Tecla/combo (cmd+s, return, escape) + arvore | | mcp__macos-use__macos-use_scroll_and_traverse | Scroll dentro de elemento + arvore | | mcp__macos-use__macos-use_set_value_and_traverse | Set valor direto (input, slider, checkbox) sem digitar | | mcp__macos-use__macos-use_press_ax_and_traverse | Aciona AXAction nativa (AXPress, AXRaise, AXShowMenu) | | mcp__macos-use__macos-use_set_selected_and_traverse | Marca/desmarca selecao em lista/tabela |

Fluxo padrao: traversal-driven

1. open_application_and_traverse("System Settings")
   → recebe arvore: [{id: 42, role: AXButton, label: "Privacy & Security"}, ...]
2. click_and_traverse(id: 42)
   → recebe nova arvore com painel aberto: [{id: 87, role: AXRow, label: "Accessibility"}, ...]
3. click_and_traverse(id: 87)
   → arvore atualizada com lista de apps
4. Sem screenshot necessario na maioria dos casos — arvore ja descreve o estado

Exemplo: preencher formulario nativo

1. open_application_and_traverse("Mail")
2. press_key_and_traverse("cmd+n")               → abre janela compose, retorna arvore
3. type_and_traverse(target_label: "To:", text: "user@example.com")
4. type_and_traverse(target_label: "Subject:", text: "Hello")
5. type_and_traverse(target_role: "AXTextArea", text: "Body...")
6. press_key_and_traverse("cmd+shift+d")          → enviar

Vantagens

• Sem coordenadas — referencia por id/role/label
• Sobrevive a mudancas de resolucao, dark mode, scroll, fonte
• Sem visao computacional — leitura textual direta

Limitacoes

• Apps Electron mal-acessiveis (alguns) nao expoem AX corretamente
• Apps SwiftUI antigos podem ter labels vazios — fallback tier 2

---

Tier 2: macos-automator (AppleScript / JXA)

Usar quando tier 1 nao cobre. AppleScript ja e semantico (click button "Send" of window 1) — mais robusto que coordenada e cobre operacoes que AX nao expoe (clipboard, notificacoes, automacao Finder/Mail/Safari, scripting de apps com automation suite).

Quando preferir tier 2 sobre tier 1

• Operacoes de sistema: abrir/fechar janela, mover entre Spaces, mudar volume, screen brightness
• Manipular clipboard (the clipboard as text)
• Apps com automation dictionary publicado: Finder, Mail, Safari, Music, Notes, Reminders, Calendar, Pages, Numbers, Keynote, Photos
• Recipes prontas do macos-automator (200+) — checar antes de escrever script novo
• Tarefas que envolvem multiplos apps coordenados (AppleScript orquestra melhor)

Padrao de chamada

mcp__macos-automator__execute_script
  language: "applescript"  // ou "javascript" para JXA
  script: |
    tell application "Finder"
      set sel to selection
      return (count of sel)
    end tell

Exemplo: ler clipboard

return the clipboard as text

Exemplo: criar nota no Notes

tell application "Notes"
  tell account "iCloud"
    make new note at folder "Notes" with properties {name:"Titulo", body:"Conteudo"}
  end tell
end tell

Exemplo: abrir URL em Safari + esperar carregar

tell application "Safari"
  activate
  open location "https://example.com"
  delay 2
  return URL of current tab of window 1
end tell

---

Tier 3: computer-use (coordenada, fallback)

So quando tier 1 e 2 falham. Pixel-base, frágil — coordenadas mudam com resolucao, scroll, dark mode.

Ferramentas

| Tool | O que faz | |------|-----------| | mcp__computer-use__screenshot | Captura tela (full ou regiao) — retorna imagem | | mcp__computer-use__mouse_click | Clica em (x, y) | | mcp__computer-use__mouse_move | Move cursor | | mcp__computer-use__mouse_scroll | Scroll up/down | | mcp__computer-use__keyboard_type | Digita no foco atual | | mcp__computer-use__key_press | Tecla especial / combo | | mcp__computer-use__cursor_position | Posicao do cursor | | mcp__computer-use__screen_size | Resolucao | | mcp__computer-use__open_app | Abre app por nome | | mcp__computer-use__active_window | Janela ativa | | mcp__computer-use__list_windows | Janelas + posicao + tamanho |

Fluxo: ver → identificar visualmente → clicar

1. screenshot()                    → ver a tela
2. Analisar visualmente            → estimar coordenadas
3. mouse_click(x, y)              → clicar
4. screenshot()                    → confirmar resultado

Anti-patterns especificos do tier 3

• NUNCA reusar coordenadas de sessao anterior — sempre screenshot fresco
• NUNCA assumir layout — mesma tela em monitor diferente tem coordenadas diferentes
• Se errar coordenada 2x → voltar pra tier 1 ou tier 2

---

Pre-requisitos (1 vez por maquina)

Permissoes macOS (obrigatorias)

• System Settings → Privacy & Security → Accessibility: ativar app que roda Claude Code (Terminal, iTerm2, ou Claude Desktop). Necessario para tier 1, 2 e 3.
• System Settings → Privacy & Security → Automation: aceitar popups de controle por app (Finder, Safari, etc) na primeira vez que tier 1 ou 2 toca cada app.
• System Settings → Privacy & Security → Screen Recording: necessario para tier 3 (screenshot via cliclick/screencapture).

Binarios

• cliclick: /opt/homebrew/bin/cliclick — usado pelo tier 3 (computer-use)
• osascript: /usr/bin/osascript — usado pelo tier 2 (macos-automator)
• mcp-server-macos-use: ~/.claude/mcp-servers/macos-use/.build/release/mcp-server-macos-use — binario Swift do tier 1

Registro em ~/Claude/.mcp.json

Os 3 MCPs devem estar registrados. Verificar com:

python3 -c "import json; print([k for k in json.load(open('/Users/andregusmandeoliveira/Claude/.mcp.json'))['mcpServers']])"

Esperado conter: computer-use, macos-automator, macos-use.

Tier 4 (emergencia): Bash screencapture

Ultimo recurso quando NENHUM dos 3 MCPs esta carregado na sessao (ex: ambiente sem .mcp.json registrado, MCP servers crashed). Apenas OBSERVACAO — sem controle de mouse/teclado.

Passo 0: Detectar OS

uname -s 2>/dev/null || echo "Windows"

Passo 1: Capturar (por OS)

macOS

screencapture -x /tmp/claude-screen-$(date +%s).png
screencapture -x -R 0,0,1920,1080 /tmp/claude-screen-$(date +%s).png  # regiao
screencapture -x -D 1 /tmp/claude-screen-$(date +%s).png              # monitor

Windows (PowerShell)

$ts = Get-Date -Format 'yyyyMMddHHmmss'
$out = "$env:TEMP\claude-screen-$ts.png"
Add-Type -AssemblyName System.Windows.Forms,System.Drawing
$s = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds
$bmp = New-Object System.Drawing.Bitmap($s.Width, $s.Height)
$g = [System.Drawing.Graphics]::FromImage($bmp)
$g.CopyFromScreen($s.Location, [System.Drawing.Point]::Empty, $s.Size)
$bmp.Save($out, [System.Drawing.Imaging.ImageFormat]::Png)
$g.Dispose(); $bmp.Dispose()
Write-Output $out

Linux

scrot /tmp/claude-screen-$(date +%s).png           # X11
grim /tmp/claude-screen-$(date +%s).png            # Wayland

Passo 2: Ler com Read tool

Read /tmp/claude-screen-TIMESTAMP.png

Passo 3: Analisar e responder

| Input do usuario | Acao | |------------------|------| | Sem argumento | Descrever o que esta visivel | | Pergunta especifica | Responder baseado no visual | | "leia/extraia texto" | OCR do conteudo visivel | | "qual app" | Identificar apps/janelas abertas | | Contexto de outro agent | Focar no aspecto solicitado |

Passo 4: Cleanup

rm /tmp/claude-screen-*.png

Decisao: qual tier usar

| Cenario | Tier | MCP | Motivo | |---------|------|-----|--------| | App nativo macOS com AX exposto (default) | 1 | macos-use | Semantico, robusto, sem visao computacional | | Operacao de sistema (clipboard, Spaces, brilho) | 2 | macos-automator | AppleScript cobre o que AX nao expoe | | App com automation suite (Finder/Mail/Safari/Notes) | 2 | macos-automator | Recipe nativa, coordenacao multi-app | | App Electron mal-acessivel ou jogo | 3 | computer-use | AX falhou, ultimo recurso | | App nativo so observar (sem clicar) | 1 ou 3 | macos-use ou computer-use | Tier 1 retorna arvore textual; tier 3 retorna imagem | | Pagina web em browser | — | Playwright MCP | Sai dessa skill — usar mcp__plugin_playwright_playwright__* | | Interacao com web app | — | Playwright MCP | Ref-based clicks, form fills | | Nenhum MCP disponivel | 4 | Bash screencapture | Emergencia, so observa |

Integracao com outros agents

• ag-testar-manual: fallback quando Playwright nao consegue capturar app nativo
• ag-testar-ux-qualidade: captura tela de apps nativos para comparacao visual
• ag-meridian (D4-LOOKS): captura estado visual de apps desktop
• ag-4-teste-final (ux-qat): complementa screenshots de browser com tela nativa
• ag-11-ux-ui: referencia visual de apps nativos para design review
• ag-depurar-erro: ver estado visual quando debug requer contexto da tela

Anti-patterns

Gerais

• NUNCA capturar tela em loop automatico sem pedir ao usuario
• NUNCA armazenar screenshots permanentemente (sempre temp dir)
• NUNCA capturar se o usuario nao pediu explicitamente (exceto quando chamado por outro agent com contexto)
• NUNCA enviar screenshot para servicos externos (privacidade)
• Se captura/interacao falhar → orientar sobre permissoes do OS (Accessibility + Automation + Screen Recording)

De roteamento

• NUNCA pular direto pra tier 3 sem tentar tier 1 e 2
• NUNCA misturar tiers numa mesma operacao (ex: clicar via tier 3 e depois ler estado via tier 1) — escolha um tier por fluxo
• Se tier 1 (refresh_traversal) retorna arvore vazia ou sem labels uteis → escalar para tier 2, nao insistir
• NUNCA usar tier 3 para apps que tier 1 cobre bem (System Settings, Mail, Notes, etc) — coordenada e fragil

Especificos do tier 3 (coordenada)

• NUNCA clicar/digitar sem screenshot previo para confirmar coordenadas
• NUNCA assumir coordenadas de sessao anterior — sempre screenshot fresco antes de interagir
• NUNCA reusar coordenadas entre monitores diferentes

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andregusman-raiz
• Source: andregusman-raiz/a-gusman-claude
• License: MIT

Install and usage instructions live in the source repository linked above.