pc-bot

Agentes de IA controlando o Windows — clicando, digitando e navegando da forma mais confiável possível, com um cursor overlay visível para o usuário acompanhar cada ação.

Por quê

O computer use tradicional (ex: cua-driver) depende de uma única árvore de acessibilidade para "ler" a tela. Quando essa árvore está incompleta (browsers modernos, apps Electron, canvas como Google Docs), o clique falha. O pc-bot resolve isso com camadas: cada uma tenta ser a mais confiável possível, e o orquestrador cai para a próxima apenas quando necessário.

┌──────────────────────────────────────────────┐
│  A · NATIVA (UIA/pywinauto)                  │  ← mais confiável para apps nativos
│    clica por propriedade real do elemento     │
├──────────────────────────────────────────────┤
│  B · BROWSER (CDP/Playwright)                │  ← mais confiável para a web
│    clica por seletor DOM real (ref)           │
├──────────────────────────────────────────────┤
│  C · PIXEL (pyautogui/OpenCV)                │  ← último recurso
│    clica por coordenada / template matching   │
└──────────────────────────────────────────────┘

Cada ação reporta o nível de confiança usado:

• A = clique por elemento (árvore UIA do Windows)

• B = clique por DOM (navegador via CDP)

• C = clique por pixel (fallback — use com cuidado)

Related MCP server: pywinauto-mcp

O cursor overlay

Uma janela transparente em toda a tela (via UpdateLayeredWindow + alpha por pixel) desenha um anel colorido que desliza até onde o agente vai clicar. Ele não rouba o foco, não intercepta cliques e fica invisível quando não há ação — o usuário vê exatamente onde o agente está agindo, mas pode continuar trabalhando em outra janela.

Instalação

# requer Python 3.11+
pip install -e .
python -m playwright install chromium   # baixa o Chromium pro CDP (opcional, só p/ web)

Uso

CLI

pcbot state                    # lista janelas abertas
pcbot find --name "Editor"     # busca elementos nativos
pcbot click --name "Salvar"    # clica num elemento pelo nome
pcbot click --x 640 --y 400    # clica por coordenada (fallback)
pcbot type "Olá mundo"         # digita na janela ativa
pcbot screenshot               # captura a tela
pcbot demo                     # demo do cursor overlay

Como biblioteca (Python)

from pcbot.agent import AgentDesktop
from pcbot.overlay import CursorOverlay

overlay = CursorOverlay()          # cursorzinho visível
overlay.start()
agent = AgentDesktop(overlay=overlay)

state = agent.get_state()          # janelas abertas
print(state)

result = agent.click(name="Salvar")      # camada A (UIA)
result = agent.click(x=640, y=400)       # camada C (pixel)
print(result["confidence"], result)

Como MCP server (para qualquer agente de IA)

pcbot-mcp                 # só camadas nativas + pixel
pcbot-mcp --browser       # adiciona a camada browser CDP

Depois, configure seu agente (Claude, Hermes, Cursor, etc.) para apontar o MCP:

{
  "mcpServers": {
    "pc-bot": {
      "command": "pcbot-mcp",
      "args": ["--browser"]
    }
  }
}

O agente ganha as tools: screenshot, get_state, click, type_text, find, browser_goto, browser_dom, browser_click, browser_type, browser_text.

Plugins

Plugins são módulos Python em pcbot/plugins/ descobertos automaticamente pelo orquestrador. Exemplo: um plugin pode expor ações de apps específicos (Spotify, Excel, etc.).

Arquitetura

Testes

python tests/mcp_client_test.py    # conecta um client MCP stdio e chama get_state

Avisos

• Segurança: valide o confidence em cada resposta antes de agir. Cliques de nível C (pixel) devem pedir confirmação ao usuário.

• Irreversibilidade: clique errado = ação errada. Para ações sensíveis (apagar, enviar, pagar), o agente deve confirmar antes.

• Detecção: cliques sintéticos podem ser detectados por sites que verificam isTrusted. Nenhum sistema de automação de desktop escapa disso.

Roadmap

• Camada nativa UIA (clique/digitação por propriedade)

• Camada browser CDP (DOM com refs, clique real)

• Camada pixel (coordenada + template matching OpenCV)

• Cursor overlay visual (alpha por pixel, sem roubo de foco)

• MCP server (tools para agentes)

• CLI

• Plugin de OCR (ler texto da tela como fallback de estado)

• Recording/Playback (gravar trajetórias e repetir)

• Suporte a múltiplos monitores

• Modo dry-run (mostrar plano antes de executar)

Projeto criado para agentes de IA que precisam de um "par de mãos" confiável no Windows. Feito com ❤️ e commits orgânicos.