---
name: ag-capturar-tela
description: "Captura tela e controla mouse/teclado em apps nativos macOS via router 3-tier: macos-use (Accessibility tree, semantico — preferido) -> macos-automator (AppleScript/JXA) -> computer-use (coordenada, fallback). Use quando o usuario quer ver a tela, analisar app nativo, ler texto, clicar em elementos, ou navegar fora do browser. Para apps BROWSER, preferir Playwright MCP."
model: sonnet
context: fork
argument-hint: "[o que analisar/fazer na tela | regiao: x,y,w,h | monitor: N | clicar em X]"
allowed-tools: Read, Bash, Glob, Grep
metadata:
  bashPattern: "screencapture|screenshot|screen.capture|tela|printscreen|capturar.tela|desktop.control|mouse|clicar.na.tela|applescript|osascript|accessibility|axbutton"
  filePattern: "**/screen*.png,**/claude-screen*.png"
  priority: 50
---

# 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
```applescript
return the clipboard as text
```

### Exemplo: criar nota no Notes
```applescript
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
```applescript
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:
```bash
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
```bash
uname -s 2>/dev/null || echo "Windows"
```

### Passo 1: Capturar (por OS)

#### macOS
```bash
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)
```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
```bash
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
```bash
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