Plonk
O gerenciador de janelas do Mac que seu agente pode controlar. Zonas de encaixe, espaços de trabalho salvos, manter ativo, capturas de tela e OCR no dispositivo — 19 ferramentas MCP conectando-se a uma API de loopback na sua própria máquina. Sem conta, sem nuvem, sem telemetria.
Documentação
Plonk
Uma caixa de ferramentas para o seu Mac, atrás de um único ícone na barra de menus.
Janelas, espaços de trabalho, capturas de tela, OCR, uma régua, manter ativo, ferramentas de ponteiro,
atalhos, voz e agentes — nativo, local e modular.
Plonkar é colocar algo exatamente onde pertence.
Um aplicativo em vez de oito ícones na barra de menus
Plonk é um pequeno conjunto de ferramentas para macOS que compartilham uma interface, uma paleta de comandos e uma superfície de automação. Use tudo, ou desative cada módulo que você não precisar.
Capture e entenda a tela. Tire uma captura de região, janela ou tela cheia, anote-a, fixe um recorte ao vivo, copie texto não selecionável com OCR no dispositivo, ou meça uma interface em pontos e pixels.
Mantenha o Mac e seu fluxo de trabalho em movimento. Segure o sono até um timer, hora do dia ou saída de processo; encontre o ponteiro, adicione miras ou anéis de clique; inspecione os atalhos reais do aplicativo em primeiro plano; e execute qualquer coisa pelo nome em uma paleta.
Organize a mesa. Desenhe zonas de encaixe, salve espaços de trabalho que lembram cada monitor, mova janelas por arrasto, atalho ou voz, e deixe regras de aplicativo colocarem novas janelas onde pertencem.
Deixe um agente usar as mesmas ferramentas. Plonk inclui um servidor MCP e CLI para layouts, espaços de trabalho, capturas de tela, OCR, medição, manter ativo e o resto. O aplicativo continua sendo a fonte da verdade, e toda a superfície permanece no seu Mac.
É cedo. Versão 0.4.x, um autor. Atalhos, arquivos de zona e espaços de trabalho estão estáveis. Os nomes das ferramentas MCP e a API HTTP não estão, e podem mudar entre versões menores. CHANGELOG.md diz o que mudou.
Instalação
macOS 13 ou mais novo, Apple silicon.
brew install --cask ostapondo/plonk/plonk
Conceda Acessibilidade quando solicitado e reinicie. Gravação de Tela é solicitada separadamente, na primeira vez que você capturar. Nada mais: sem Acesso Total ao Disco, sem Automação, sem Keychain.
Plonk é assinado, mas não notarizado, então o macOS segura uma cópia que você baixa manualmente. O cask cuida disso para você.
Executá-lo junto com Rectangle ou Magnet é tranquilo, desde que os atalhos deles não colidam.
Verificando o que você baixou. Notarizar um aplicativo significa pagar à Apple por uma conta de desenvolvedor, e este projeto não tem uma, então Plonk é assinado com um certificado que ele mesmo criou. Isso significa que o macOS não pode dizer quem construiu o aplicativo. Há uma verificação que responde a uma pergunta mais útil, e você pode executá-la você mesmo: este arquivo exato foi construído pelo GitHub a partir do código neste repositório?
gh attestation verify Plonk-<version>.zip --repo ostapondo/Plonk
Coloque o número do nome do arquivo no lugar de <version>. O comando vem
com o GitHub CLI, que é brew install gh. Ele
imprime o commit e a execução do workflow que construiu o arquivo. Se o arquivo foi
alterado após ser construído, ou não foi construído a partir deste repositório, o
comando falha e informa isso.
Cada versão também carrega um pequeno arquivo Plonk-<version>.zip.sha256. Coloque-o
ao lado do zip e execute shasum -a 256 -c Plonk-<version>.zip.sha256 para confirmar
que o download chegou completo e inalterado. Esse arquivo é assinado da mesma forma
que o zip, então gh attestation verify funciona nele também. A atestação em si
também está na versão como Plonk-<version>.zip.sigstore.json, para quem
quiser verificá-la offline com gh attestation verify --bundle ou com
cosign em vez de perguntar ao GitHub.
Instalação manual, Macs Intel, gerenciadores de janelas e remoção
Por que o macOS segura uma cópia baixada. O certificado é autoassinado em vez de um Apple Developer ID, porque notarizar exige uma conta paga da Apple e este projeto não tem uma. O macOS não pode garantir quem o construiu, e diz isso. O cask ignora essa verificação limpando a flag de quarentena para você.
Essa é uma verificação ignorada em seu nome, então aqui está uma mais forte para executar antes de abrir qualquer coisa:
gh attestation verify $(brew --cache)/downloads/*--Plonk-*.zip \
-R ostapondo/plonk
Ele imprime o commit e a execução do GitHub Actions que construiu este arquivo exato. O selo da Apple diria que uma compilação passou por uma varredura de malware. Isso diz que o binário veio do código neste repositório, sem nenhum laptop no meio.
Sem Homebrew. Baixe a versão mais recente, descompacte, arraste Plonk.app para Applications, e limpe a flag você mesmo, que é tudo o que o cask faz:
xattr -dr com.apple.quarantine /Applications/Plonk.app
Ou faça o desvio do Gatekeeper uma vez: abra Plonk, dispense o aviso, depois System Settings, Privacy & Security, role até Security, Open Anyway.
Se você mover ou renomear Plonk.app depois, o macOS vincula a concessão antiga ao caminho antigo e janelas de aplicativos recém-iniciados deixam de ser vistas. Remova Plonk de Privacy & Security, Accessibility, e conceda novamente.
Em um Mac Intel. As versões são construídas apenas para Apple silicon, então o download não vai rodar. Compilar a partir do código deve funcionar, veja Build, mas ninguém tentou e um relato de qualquer forma é bem-vindo em issues.
Ao lado de um gerenciador de janelas. yabai e Amethyst controlam cada janela na tela e puxarão janelas de volta para fora de uma zona. Execute um ou outro.
Removendo. brew uninstall --cask plonk, ou saia do Plonk e arraste-o para a
lixeira. Depois exclua ~/Library/Application Support/Plonk/. O item de login vai
junto com o aplicativo, e nada foi escrito em nenhum outro lugar.
As ferramentas
Os módulos compartilham configurações, atalhos, a barra de menus, a paleta de comandos e a mesma API local. Desligar um remove sua página, itens de menu, atalhos, gerenciador e rotas de agente, mantendo suas configurações para depois.
| Capturas de tela e anotações | Capture uma região, janela ou tela cheia em resolução nativa, depois adicione traços de caneta, setas, formas ou destaques antes de salvar |
| OCR no dispositivo | ⌃⌥T copia palavras de uma captura de tela, vídeo pausado, diálogo ou PDF bloqueado sem enviar um pixel |
| Régua de tela | ⌃⌥R lê folgas e distâncias arrastadas em pontos do macOS e pixels físicos |
| Recortes ao vivo | Fixe uma parte em mudança da tela acima de tudo. Ela transmite ao vivo e nunca é gravada em disco |
| Pulse | Mantenha o Mac acordado por timer, agendamento, aplicativo aberto, estado de carregamento ou tempo de processo. Usa afirmações de energia reais e devolve o sono quando a sessão termina |
| Ferramentas de ponteiro | Encontre o cursor, adicione miras configuráveis ou anéis de clique, e pule o ponteiro para o próximo display |
| Guia de atalhos | Leia cada atalho que o aplicativo em primeiro plano realmente expõe através de seus menus, em vez de depender de uma folha de referência desatualizada |
| Zonas e espaços de trabalho | Desenhe lugares de janela, salve aplicativos e documentos como uma mesa, e retorne tudo aos displays corretos. Detalhes de espaços de trabalho |
| Voz, CLI e agentes | Execute as mesmas ferramentas pelo nome, por fala, o comando plonk ou vinte e duas ferramentas MCP. O reconhecimento de comandos de voz comuns permanece no dispositivo |
Todos, exceto o guia de atalhos, podem ser desligados, em Tools no menu suspenso da barra de menus ou na página Tools. Desligado significa ausente: fora da barra lateral, fora do menu, seus atalhos liberados, e suas ferramentas recusadas a agentes até que volte a ligar. Os mesmos interruptores cobrem zonas, espaços de trabalho e voz, então a organização da mesa pode ficar de lado enquanto o resto do Plonk continua rodando.
Se você vem do Rectangle, Magnet, Loop ou Raycast, os atalhos de janela familiares
podem vir com você. Um botão importa ligações do Rectangle e scripts
rectangle:// existentes precisam de uma substituição. Vindo do Rectangle
tem os detalhes.
Versões mais longas: Zonas · Espaços de trabalho · Atalhos · Todo o resto · Vindo do Rectangle
Para agentes
Um agente recebe a mesma caixa de ferramentas que a barra de menus: capture ou leia a tela, meça uma interface, controle uma sessão ativa, inspecione a mesa, organize-a e salve o resultado.
keep the Mac awake until this build finishes
read the error out of that dialog and tell me what it says
how tall is that toolbar, in points and in pixels
capture this window and highlight the warning
put the browser on the left, then save this desk as "review"
Vinte e duas ferramentas cobrem estado, captura, OCR, medição, manter ativo, layouts, espaços de trabalho e zonas. Vários agentes podem se conectar ao mesmo tempo, cada um se registrando a si mesmo, com um modo opcional que bloqueia mudanças para o ativo.
Configuração, se você quiser o CLI plonk ou um agente dirigindo-o (Node 18+):
claude mcp add plonk -- npx -y plonk-mcp # Claude Code
codex mcp add plonk -- npx -y plonk-mcp # Codex CLI
No Claude Code também pode ser um plugin: o mesmo servidor, fixado na versão com a qual foi enviado, em vez de o que o npm serve como mais recente.
/plugin marketplace add ostapondo/plonk
/plugin install plonk@plonk
Para Claude Desktop não há nada para digitar. Baixe plonk-<version>.mcpb
da versão mais recente e abra-o. O pacote carrega o servidor e
suas dependências, então nenhum arquivo de configuração é editado e nada é buscado na inicialização.
Qualquer cliente MCP funciona, via stdio ou HTTP. Páginas únicas para Cursor, Zed e Cline.
O mesmo pacote carrega um comando plonk, para as coisas que não são nem um
agente nem uma janela de configurações:
plonk state # screens, zone sets, workspaces, windows
plonk launch review # a saved workspace
plonk awake while npm run build # awake for exactly as long as the build
plonk text | pbcopy # OCR a region into the clipboard
plonk measure 0.5 0.5 # size of what is mid-screen, in points and pixels
Para agentes tem cada ferramenta, as regras de multi-agente, o transporte HTTP e o resto do CLI.
Privacidade
Sem conta, sem nuvem, sem telemetria. A API vincula-se a 127.0.0.1, recusa
qualquer coisa com cabeçalhos que um navegador não pode suprimir, e é bloqueada por um token
que só você pode ler. A única conexão de saída é a verificação de atualização, que
não carrega identificador e pode ser desligada.
Nada disso é uma afirmação que você precisa aceitar por confiança. As versões são construídas e assinadas nos runners do GitHub e vêm com uma atestação, então o binário no seu Mac se conecta ao commit de onde veio:
gh attestation verify Plonk-<version>.zip -R ostapondo/plonk
Verifique você mesmo é cada afirmação acima com o comando que a testa. SECURITY.md diz onde cada promessa termina.
Por baixo do capô
- O aplicativo é a única fonte da verdade. O servidor MCP é uma ponte sem estado.
App/é o aplicativo Swift da barra de menus,mcp/o servidor MCP TypeScript.- Config é JSON simples em
~/Library/Application Support/Plonk/config.json.
Build
Sete comandos, e são o que o CI executa em cada pull request. Cada linha é um subshell, então cole o bloco da raiz do repositório.
(cd App && swift build) # the app compiles
./scripts/test.sh # the unit suite
./scripts/lint.sh # style rules, no dependencies
(cd mcp && npm ci && npm test) # the MCP server
node scripts/check-zone-sets.mjs # the layouts in zone-sets/
node scripts/check-strings.mjs # every word the user reads
./scripts/check-security-claims.sh # what SECURITY.md promises
Nada disso precisa de um certificado de assinatura. Geometria de zona, decodificação de config, roteamento HTTP, ferramentas MCP, parsing de voz, o CLI e cada documento aqui são alcançáveis desse loop, e a maioria das mudanças não precisa de mais nada.
Produzir um Plonk.app executável precisa de um. Crie o seu próprio uma vez com
./scripts/make-signing-cert.sh, depois execute ./scripts/build.sh. O macOS vincula
Acessibilidade e Gravação de Tela à assinatura de código, e uma ad-hoc
muda a cada build, então um certificado estável é o que impede reconstruções de
redefinir permissões.
Contribuindo
Relatos de bugs, conjuntos de zonas, páginas únicas de clientes e código são todos bem-vindos. Nenhum deles precisa de um certificado de assinatura.
- A menor mudança útil é um único arquivo JSON.
zone-sets/é uma galeria de layouts que vale a pena copiar: uma divisão ultrawide, um monitor rotacionado, aquele construído em torno de uma reunião recorrente. Desenhe no aplicativo, leia os números deplonk state --json, abra um pull request. Essa pasta tem seu próprio job de CI e responde em cerca de vinte segundos. Sem build, sem assinatura, sem Swift. - good first issue são issues escritas para serem pegas a frio. Cada uma diz onde está o código e como saber se funcionou, e traz um prompt que você pode entregar a um agente, já que AGENTS.md explica o repositório para ele.
- needs-hardware é onde um pedido por uma mesa que ninguém aqui tem é marcado, e responder a um não exige nem Swift nem certificado. Ferramentas de mesa encontram hardware que o autor não pode ver, então um relato de três monitores ou um ultrawide vale mais que um patch. Uma lista vazia não é uma lacuna preenchida: abra uma issue com a disposição que você tem e o que aconteceu.
CONTRIBUTING.md tem o resto, incluindo quanto tempo uma revisão leva. Perguntas e ideias pela metade vão para Discussions. Um problema de segurança passa por SECURITY.md, não por uma issue pública. Todos que participam seguem o Code of Conduct.
Licença
MIT © ostapondo