Como o Merlin funciona

O Merlin é um app desktop em Electron. Ele não reimplementa os agentes: abre as CLIs oficiais (Claude Code, Codex, Gemini CLI) em terminais reais e coordena o trabalho entre elas.

As peças

Peça	O que faz
Terminais reais	Cada agente é um pseudo-terminal (`node-pty`) rodando a CLI da IA, exibido com `xterm.js` numa janela da mesa.
Mesa	Interface em React; a mesa é um canvas (`@xyflow/react`) com agentes, terminais, navegador e arquivos.
Servidor MCP do Merlin	Um servidor MCP local (HTTP) que dá ao líder e aos agentes as ferramentas para criar agentes, mandar missões e relatar. Veja Servidor MCP do Merlin.
Estado dos agentes	O semáforo vem dos eventos e transcritos das CLIs (pronto, trabalhando, esperando permissão, erro).
Trava de escrita	Um hook `PreToolUse` do Claude Code roda antes de cada edição e recusa, com o motivo, o que estiver fora do cargo. Comandos de terminal não passam por esse hook.
Consumo	Lido dos arquivos locais das CLIs. Nada sai do computador.
Voz	Whisper rodando localmente num worker.

O líder e as missões

O Merlin (líder) é ele mesmo uma sessão de Claude Code com um prompt de sistema e as ferramentas do servidor MCP. Fluxo típico:

o tutor fala com o líder;
o líder propõe a equipe (propose_team) e, aprovada, cria os agentes;
cada missão vai por send_to_agent, com um nível obrigatório (mecanico, simples, normal, complexo) que define modelo e esforço;
o agente trabalha e responde com report_to_merlin, além de atualizar um arquivo de passagem (.merlin/handoff/<agente>.md);
quando a conversa de um agente fica longa, o app pode recomeçá-lo a partir desse arquivo, sem perder o contexto.

Arquivos de um projeto

<Projeto>/
├── CLAUDE.md              ← instruções lidas por todos os agentes
├── app/                   ← código
├── docs/projeto.md        ← resumo vivo (memória compartilhada da matilha)
├── .claude/skills/        ← skills do projeto
└── .merlin/               ← interno: projeto.json, agentes, handoff, relatórios, atividade

O contexto.md da pasta da empresa vira um CLAUDE.md herdado por todos os projetos da empresa.

Link `merlin://`

O app registra o protocolo merlin://, usado para voltar do login no navegador para o app.