brito-cli 0.3.2 → 0.5.0

package/README.md

@@ -2,9 +2,9 @@
 
 **English** · [Português](README.pt-BR.md)
 
-> A coding-agent CLI that knows your codebase as a **graph** and learns your project's procedures as **skills you review**.
+> A coding agent for your terminal (`brito-cli`) and your desktop (a native app) that knows your codebase as a **graph** and learns your project's procedures as **skills you review**.
 
-Brito is a terminal agent for software development. Instead of grepping and reading files blindly, it keeps a **knowledge graph of your code** (symbols, who calls whom, who imports whom) and answers questions like *"what breaks if I change this?"* straight from the graph, in a fraction of a second. It also keeps **memory notes** and **skills**: reusable procedures learned from your own work, which only become active after **you** approve them.
+Brito is an agent for software development. Use it in the terminal (`brito-cli` on npm) or as a desktop app (an executable for macOS, Windows and Linux): same agent, same graph, same skills. Instead of grepping and reading files blindly, it keeps a **knowledge graph of your code** (symbols, who calls whom, who imports whom) and answers questions like *"what breaks if I change this?"* straight from the graph, in a fraction of a second. It also keeps **memory notes** and **skills**: reusable procedures learned from your own work, which only become active after **you** approve them.
 
 ![Brito answering a question with the code graph](docs/images/answer-with-graph.png)
 
@@ -14,10 +14,12 @@ Brito is a terminal agent for software development. Instead of grepping and read
 
 - **Graph-first exploration.** `graph_search`, `graph_context`, `graph_callers`, `graph_callees` and `graph_impact` answer "where is it, who uses it, what breaks" without reading whole files. The graph is embedded ([Kùzu](https://kuzudb.com)), local and incremental.
 - **Wide coverage.** TypeScript/JavaScript, Python and the script blocks of `.svelte`, `.vue` and `.astro` components. Import aliases (`tsconfig` paths, `package.json` imports, SvelteKit's `$lib`) become real edges. Files ignored by `.gitignore` stay out.
-- **Skills that learn, with a human in the loop.** After a complex task Brito reflects on what happened and *proposes* skills. Nothing becomes active until you run `/skills approve`.
+- **Skills that learn on their own, on probation.** After a task that tripped or was corrected, Brito reflects and creates a skill *in trial* without interrupting you. A skill proves itself by use: 3 clean uses promote it, 2 stumbles archive it (recoverable). Anything risky, or any change to a skill you approved, still waits for your `/skills approve`. `BRITO_SKILLS=ask` restores approval-for-everything; `off` disables learning.
 - **Safety rails for what gets learned.** A lint rejects secrets, credentials embedded in URLs, `curl | sh` and prompt-injection phrasing, and **warns about destructive commands** (see below).
-- **Permission modes.** manual, auto-edits, plan and "everything allowed" (`Shift+Tab` cycles them). Even in the last one, skills are queued for review instead of being activated.
+- **Permission modes.** manual, auto-edits, plan and "everything allowed" (`Shift+Tab` cycles them). Autonomous skills do not depend on the mode: they are created in trial and judged by results.
 - **Two backends, one interface.** Use an Anthropic API key, or your Claude Code subscription through the `claude` CLI. Brito never reads or sends your subscription token.
+- **Terminal or desktop app.** `npm i -g brito-cli` gives you the `brito` command; the desktop app is a native executable with a window (projects and sessions in a sidebar, chat, permission prompts), no Node or terminal needed. See [Install](#install).
+- **Images.** Drag an image file into the prompt (or paste its path) and it is attached to the turn: PNG, JPEG, GIF or WebP, up to 5 MB.
 - **Subagents.** `explore`, `plan` and `general` run in isolated contexts (read-only ones in parallel); add your own in `.brito/agents/*.md`.
 - **MCP server.** `brito mcp-serve` exposes the graph, memory and skills to other MCP clients such as Claude Code. The query tools are marked `alwaysLoad`, so they are not hidden behind tool search.
 
@@ -29,9 +31,13 @@ flowchart LR
     cg <-->|"graph_search · graph_callers<br/>graph_impact · graph_context"| agent{{"Brito agent"}}
     mem[("Memory<br/>decisions · conventions")] <-->|"recall / remember"| agent
     agent -->|"after a complex task"| learn["Reflection"]
-    learn -->|"proposes"| pending["Pending skills"]
-    pending -->|"/skills approve<br/>you decide"| skills[("Skills<br/>.brito/skills")]
+    learn -->|"creates"| trial["Skill in trial"]
+    trial -->|"3 clean uses"| skills[("Skills<br/>.brito/skills")]
+    trial -->|"2 stumbles or 21 idle days"| trash["Archived (.trash)"]
+    learn -->|"risky or changes yours"| pending["Pending<br/>/skills approve"]
+    pending --> skills
     skills -->|"skill_load"| agent
+    trial -->|"skill_load"| agent
 ```
 
 - **Code graph**: functions, classes, methods and components as nodes; `CALLS` and `IMPORTS` as edges. It re-parses only files whose hash changed and updates itself after edits.
@@ -39,11 +45,12 @@ flowchart LR
 - **Skills**: step-by-step procedures for *your* project (commands, order, traps, how to verify). The agent loads one with `skill_load` before a task it covers.
 - **Journal**: Brito remembers across sessions which tasks repeated, which is the best hint that a procedure is general and worth saving.
 
-## Skills you review, not magic
+## Skills that earn their place
 
 ![Reviewing a pending skill, with a destructive-command warning](docs/images/skills-review.png)
 
-1. A proposal appears in `/skills pending`, flagged when it contains destructive commands.
+0. **Autonomous path (default).** The reflection saves a new skill as *trial*, marked "(em teste)" in the index. Each turn that loads it counts as a win (no error-then-fix, no user correction) or a loss. 3 wins (and at most 1 loss per 3 wins) promote it; 2 losses without more wins, or 21 days unused, archive it to `.brito/skills/.trash`. Brito prints one line per promotion or archive. Limits: at most 3 new automatic skills a day, project scope only, and a weekly automatic consolidation that only touches automatic skills.
+1. **Review path.** Skills with destructive commands, and changes to skills you approved, appear in `/skills pending`, flagged when they contain destructive commands.
 2. `/skills approve <name>` shows the **whole body** and the lint warnings, then asks for confirmation. That confirmation is required even in "everything allowed" mode.
 3. Approved skills are versioned (`history/`), ranked by use, and flagged when the files they cite no longer exist. `/skills consolidate` merges duplicates and prunes unused ones.
 4. A skill can be project-scoped or **global** (valid in every project); `/skills promote` moves one to global.
@@ -52,7 +59,9 @@ The lint **rejects** secrets/tokens, absolute user paths, credentials in URLs (`
 
 ## Install
 
-Requires Node >= 20. Developed on macOS; Linux should work, Windows is untested.
+### Terminal (`brito-cli`)
+
+Requires Node >= 20. Developed on macOS; Linux should work. On Windows use `npm i -g brito-cli` (the `install.sh` script needs bash); install Git for Windows so the `bash` tool runs bash commands, otherwise it falls back to `cmd.exe` (override with `BRITO_SHELL`).
 
 ```bash
 # from npm (the command is `brito`)
@@ -76,6 +85,28 @@ export ANTHROPIC_API_KEY=sk-ant-...      # Anthropic API
 # or: install Claude Code, run `claude` and /login — Brito will use your subscription
 ```
 
+### Desktop app (executable)
+
+The same agent in a window: projects and sessions in a sidebar, chat with markdown, collapsible tool calls, permission prompts, and pickers for model, effort and permission mode. It needs neither Node nor a terminal.
+
+![Brito desktop app answering a question with the code graph](docs/images/desktop-app.png)
+
+*The desktop app on a small project: one question, one graph call (the collapsed "ran 1 command" line), and the answer as a table. The sidebar groups sessions by project; the footer shows the backend, the folder, the context size and the cost.*
+
+Download it from the [Releases page](https://github.com/wilsonbrito/brito/releases):
+
+| System | File |
+|---|---|
+| macOS | `Brito-<version>-macos-arm64.dmg` (Apple Silicon) or `-x64.dmg` (Intel): open it and drag Brito to Applications |
+| Windows | `Brito-<version>-windows-x64-setup.exe` |
+| Linux | `Brito-<version>-linux-x64.tar.gz`: extract it and run `./install.sh` (adds Brito to the applications menu) |
+
+The builds are not signed with an Apple Developer ID or a Windows certificate, so macOS ("unidentified developer": right-click, then Open) and Windows SmartScreen warn on the first launch. macOS is the platform exercised the most; the Windows and Linux builds come from CI and have had less testing.
+
+Like the terminal version, it uses `ANTHROPIC_API_KEY` when your shell exports it, otherwise your Claude Code subscription (`claude`, then `/login`). Opened from the Finder, the app reads your login shell to find them.
+
+To build it yourself: `npm run desktop` (development), `npm run desktop:app` (macOS: installs `/Applications/Brito.app`) or `npm run desktop:dmg`.
+
 ## Quick start
 
 ```bash
@@ -133,13 +164,14 @@ Brito has **no database drivers and connects to nothing on its own**. When it ne
 
 ## Configuration
 
-`BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (where global skills and history live), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` or `full`; default: full screen on windows of 95+ columns and 28+ rows), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (how long a turn must be to trigger reflection when nothing else does).
+`BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (where global skills and history live), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` or `full`; default: full screen on windows of 95+ columns and 28+ rows), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (how long a turn must be to trigger reflection when nothing else does), `BRITO_SKILLS` (`auto` default, `ask`, `off`), `BRITO_SHELL` (shell used by the `bash` tool; on Windows defaults to Git Bash when installed).
 
 Project data lives in `.brito/` (graph, project skills, agents) and global data in `~/.brito`. The graph, memory and skills stay on your machine; as with any coding agent, the code the model reads is sent to the model provider you configured.
 
 ## Limitations
 
-- Early software (v0.3.1), one maintainer.
+- Early software (v0.5.0), one maintainer.
+- The desktop app is new: a single window (no tabs yet), and with an API key (no `claude` CLI) the model does not resume a conversation after you reopen the app, although the screen shows it.
 - **The interface and the agent's default language are Brazilian Portuguese.** Translating them is a welcome contribution.
 - Skill learning is a heuristic: it proposes, you decide. Expect some proposals to be rejected.
 
@@ -161,6 +193,8 @@ npm test             # 190+ tests, including a real MCP server and a real REPL
 | `src/tools/` | graph, memory, skills, filesystem and shell tools |
 | `src/mcp/` | MCP server |
 | `src/repl.ts`, `src/ui/` | terminal interface |
+| `src/desktop/` | `brito gui-serve`: the backend the desktop window talks to (JSON over stdio) |
+| `desktop/` | Electron window and packaging (`package.mjs`); `npm run bundle` builds the single-file backend it uses |
 
 ## License
 

package/README.pt-BR.md

@@ -2,9 +2,9 @@
 
 [English](README.md) · **Português**
 
-> Uma CLI de agente de código que conhece o seu projeto como um **grafo** e aprende os procedimentos dele como **skills que você revisa**.
+> Um agente de código para o seu terminal (`brito-cli`) e para o seu desktop (um app nativo) que conhece o seu projeto como um **grafo** e aprende os procedimentos dele como **skills que você revisa**.
 
-O Brito é um agente de terminal para desenvolvimento de software. Em vez de dar `grep` e ler arquivos às cegas, ele mantém um **grafo de conhecimento do código** (símbolos, quem chama quem, quem importa quem) e responde perguntas como *"o que quebra se eu mudar isto?"* direto do grafo, em uma fração de segundo. Ele também guarda **notas de memória** e **skills**: procedimentos reutilizáveis aprendidos no seu próprio trabalho, que só passam a valer depois que **você** aprova.
+O Brito é um agente para desenvolvimento de software. Use no terminal (`brito-cli` no npm) ou como app de desktop (um executável para macOS, Windows e Linux): o mesmo agente, o mesmo grafo, as mesmas skills. Em vez de dar `grep` e ler arquivos às cegas, ele mantém um **grafo de conhecimento do código** (símbolos, quem chama quem, quem importa quem) e responde perguntas como *"o que quebra se eu mudar isto?"* direto do grafo, em uma fração de segundo. Ele também guarda **notas de memória** e **skills**: procedimentos reutilizáveis aprendidos no seu próprio trabalho, que só passam a valer depois que **você** aprova.
 
 ![Brito respondendo uma pergunta com o grafo de código](docs/images/answer-with-graph.png)
 
@@ -14,10 +14,12 @@ O Brito é um agente de terminal para desenvolvimento de software. Em vez de dar
 
 - **Exploração guiada pelo grafo.** `graph_search`, `graph_context`, `graph_callers`, `graph_callees` e `graph_impact` respondem "onde está, quem usa, o que quebra" sem ler arquivos inteiros. O grafo é embutido ([Kùzu](https://kuzudb.com)), local e incremental.
 - **Cobertura ampla.** TypeScript/JavaScript, Python e os blocos de script de componentes `.svelte`, `.vue` e `.astro`. Aliases de import (`paths` do tsconfig, `imports` do package.json, `$lib` do SvelteKit) viram arestas de verdade. O que o `.gitignore` ignora fica de fora.
-- **Skills que aprendem, com um humano no circuito.** Depois de uma tarefa complexa o Brito reflete sobre o que aconteceu e *propõe* skills. Nada fica ativo até você rodar `/skills approve`.
+- **Skills que aprendem sozinhas, em período de teste.** Depois de uma tarefa em que algo tropeçou ou foi corrigido, o Brito reflete e cria uma skill *em teste* sem te interromper. A skill se prova pelo uso: 3 usos limpos a promovem, 2 tropeços a arquivam (recuperável). O que é arriscado, ou qualquer mudança numa skill que você aprovou, continua esperando o seu `/skills approve`. `BRITO_SKILLS=ask` volta a pedir aprovação para tudo; `off` desliga o aprendizado.
 - **Proteções sobre o que é aprendido.** Um lint rejeita segredos, credenciais embutidas em URL, `curl | sh` e frases de injeção de prompt, e **avisa sobre comandos destrutivos** (veja abaixo).
-- **Modos de permissão.** manual, auto-edições, plano e "tudo liberado" (`Shift+Tab` alterna). Mesmo no último, as skills vão para a fila de revisão em vez de ficarem ativas.
+- **Modos de permissão.** manual, auto-edições, plano e "tudo liberado" (`Shift+Tab` alterna). As skills autônomas não dependem do modo: nascem em teste e são julgadas pelo resultado.
 - **Dois backends, uma interface.** Use uma chave da API da Anthropic ou a sua assinatura do Claude Code pela CLI `claude`. O Brito nunca lê nem envia o token da sua assinatura.
+- **Terminal ou app de desktop.** `npm i -g brito-cli` instala o comando `brito`; o app de desktop é um executável nativo com janela (projetos e sessões numa barra lateral, chat, pedidos de permissão), sem precisar de Node nem de terminal. Veja [Instalação](#instalação).
+- **Imagens.** Arraste um arquivo de imagem para o prompt (ou cole o caminho) e ele é anexado ao turno: PNG, JPEG, GIF ou WebP, até 5 MB.
 - **Subagentes.** `explore`, `plan` e `general` rodam em contextos isolados (os somente-leitura, em paralelo); crie os seus em `.brito/agents/*.md`.
 - **Servidor MCP.** `brito mcp-serve` expõe grafo, memória e skills a outros clientes MCP, como o Claude Code. As tools de consulta são marcadas `alwaysLoad`, para não ficarem escondidas atrás da busca de tools.
 
@@ -39,11 +41,12 @@ flowchart LR
 - **Skills**: procedimentos passo a passo para o *seu* projeto (comandos, ordem, armadilhas, como verificar). O agente carrega uma com `skill_load` antes de uma tarefa que ela cobre.
 - **Journal**: o Brito lembra entre sessões quais tarefas se repetiram, o melhor indício de que um procedimento é geral e vale guardar.
 
-## Skills que você revisa, sem mágica
+## Skills que merecem o lugar
 
 ![Revisando uma skill pendente, com aviso de comando destrutivo](docs/images/skills-review.png)
 
-1. Uma proposta aparece em `/skills pending`, sinalizada quando contém comandos destrutivos.
+0. **Caminho autônomo (padrão).** A reflexão grava a skill nova como *em teste*, marcada "(em teste)" no índice. Cada turno que a carrega conta como vitória (sem erro→conserto nem correção do usuário) ou falha. 3 vitórias (e no máximo 1 falha a cada 3 vitórias) a promovem; 2 falhas sem mais vitórias, ou 21 dias sem uso, a arquivam em `.brito/skills/.trash`. O Brito imprime uma linha a cada promoção ou arquivamento. Limites: no máximo 3 skills automáticas novas por dia, só no escopo do projeto, e uma consolidação semanal automática que só mexe em skills automáticas.
+1. **Caminho de revisão.** Skills com comandos destrutivos, e mudanças em skills que você aprovou, aparecem em `/skills pending`, sinalizadas quando contêm comandos destrutivos.
 2. `/skills approve <nome>` mostra o **corpo inteiro** e os avisos do lint, e pede confirmação. Essa confirmação é exigida mesmo no modo "tudo liberado".
 3. Skills aprovadas são versionadas (`history/`), ranqueadas por uso e sinalizadas quando os arquivos que citam deixam de existir. `/skills consolidate` junta duplicadas e poda as sem uso.
 4. Uma skill pode ser do projeto ou **global** (vale em todos os projetos); `/skills promote` move uma para global.
@@ -52,6 +55,8 @@ O lint **rejeita** segredos/tokens, caminhos absolutos do usuário, credenciais
 
 ## Instalação
 
+### Terminal (`brito-cli`)
+
 Requer Node >= 20. Desenvolvido no macOS; no Linux deve funcionar, no Windows não foi testado.
 
 ```bash
@@ -76,6 +81,28 @@ export ANTHROPIC_API_KEY=sk-ant-...      # API da Anthropic
 # ou: instale o Claude Code, rode `claude` e /login — o Brito usa a sua assinatura
 ```
 
+### App de desktop (executável)
+
+O mesmo agente numa janela: projetos e sessões numa barra lateral, chat com markdown, chamadas de ferramenta recolhíveis, pedidos de permissão e seletores de modelo, esforço e modo de permissão. Não precisa de Node nem de terminal.
+
+![App de desktop do Brito respondendo uma pergunta com o grafo de código](docs/images/desktop-app.png)
+
+*O app de desktop num projeto pequeno: uma pergunta, uma chamada ao grafo (a linha recolhida "executou 1 comando") e a resposta em tabela. A barra lateral agrupa as sessões por projeto; o rodapé mostra o backend, a pasta, o tamanho do contexto e o custo.*
+
+Baixe na [página de Releases](https://github.com/wilsonbrito/brito/releases):
+
+| Sistema | Arquivo |
+|---|---|
+| macOS | `Brito-<versão>-macos-arm64.dmg` (Apple Silicon) ou `-x64.dmg` (Intel): abra e arraste o Brito para Aplicativos |
+| Windows | `Brito-<versão>-windows-x64-setup.exe` |
+| Linux | `Brito-<versão>-linux-x64.tar.gz`: extraia e rode `./install.sh` (coloca o Brito no menu de aplicativos) |
+
+Os pacotes não são assinados com Apple Developer ID nem com certificado do Windows, então o macOS ("desenvolvedor não identificado": botão direito, depois Abrir) e o SmartScreen do Windows avisam na primeira abertura. O macOS é a plataforma mais testada; os pacotes de Windows e Linux saem do CI e foram menos exercitados.
+
+Como na versão de terminal, ele usa a `ANTHROPIC_API_KEY` se o seu shell a exporta; senão, a sua assinatura do Claude Code (`claude`, depois `/login`). Aberto pelo Finder, o app lê o seu shell de login para encontrá-las.
+
+Para compilar você mesmo: `npm run desktop` (desenvolvimento), `npm run desktop:app` (macOS: instala `/Applications/Brito.app`) ou `npm run desktop:dmg`.
+
 ## Começando
 
 ```bash
@@ -133,13 +160,14 @@ O Brito **não tem drivers de banco e não se conecta a nada sozinho**. Quando p
 
 ## Configuração
 
-`BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (onde ficam skills globais e histórico), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` ou `full`; padrão: tela cheia em janelas de 95+ colunas e 28+ linhas), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (tamanho mínimo do turno para disparar a reflexão quando nada mais dispara).
+`BRITO_MODEL`, `BRITO_EFFORT`, `BRITO_EXPLORE_MODEL`, `BRITO_LEARN_MODEL`, `BRITO_HOME` (onde ficam skills globais e histórico), `BRITO_CONFIG`, `BRITO_COLOR`, `BRITO_BANNER` (`compact` ou `full`; padrão: tela cheia em janelas de 95+ colunas e 28+ linhas), `BRITO_INDEX_IGNORED`, `BRITO_SKILL_MIN_TOOLS` (tamanho mínimo do turno para disparar a reflexão quando nada mais dispara), `BRITO_SKILLS` (`auto` padrão, `ask`, `off`), `BRITO_SHELL` (shell da tool `bash`; no Windows usa o Git Bash se instalado).
 
 Os dados do projeto ficam em `.brito/` (grafo, skills do projeto, agentes) e os globais em `~/.brito`. O grafo, a memória e as skills ficam na sua máquina; como em qualquer agente de código, o código que o modelo lê é enviado ao provedor de modelo que você configurou.
 
 ## Limitações
 
-- Software em fase inicial (v0.3.1), um mantenedor.
+- Software em fase inicial (v0.5.0), um mantenedor.
+- O app de desktop é novo: uma janela só (sem abas ainda) e, com chave de API (sem o `claude` CLI), o modelo não retoma a conversa ao reabrir o app, embora a tela a mostre.
 - **A interface e o idioma padrão do agente são português do Brasil.** Traduzi-los é uma contribuição bem-vinda.
 - O aprendizado de skills é heurístico: ele propõe, você decide. Espere rejeitar algumas propostas.
 
@@ -161,6 +189,8 @@ npm test             # 190+ testes, incluindo um servidor MCP real e um REPL rea
 | `src/tools/` | tools de grafo, memória, skills, arquivos e shell |
 | `src/mcp/` | servidor MCP |
 | `src/repl.ts`, `src/ui/` | interface de terminal |
+| `src/desktop/` | `brito gui-serve`: o backend com que a janela do desktop conversa (JSON por stdio) |
+| `desktop/` | janela Electron e empacotamento (`package.mjs`); `npm run bundle` gera o backend em arquivo único que ela usa |
 
 ## Licença
 

package/dist/agent/approval.js

@@ -0,0 +1,48 @@
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { describeClaudeTool, perms } from "../permissions.js";
+/**
+ * Aprovações do claude CLI: o claude chama a tool MCP `approve` (--permission-prompt-tool), que roda no
+ * processo do servidor MCP e consulta ESTE processo por um socket unix, onde está o terminal (ou a janela do app).
+ */
+export function startApprovalServer(io) {
+    // No Windows um socket unix em %TEMP% não é aceito por net.listen: o endereço tem que ser um named pipe.
+    const sock = process.platform === "win32" ? `\\\\.\\pipe\\brito-approve-${process.pid}` : path.join(os.tmpdir(), `brito-approve-${process.pid}.sock`);
+    try {
+        fs.unlinkSync(sock);
+    }
+    catch { /* não existia */ }
+    const server = net.createServer((conn) => {
+        let buf = "";
+        conn.on("data", async (d) => {
+            buf += d.toString();
+            const nl = buf.indexOf("\n");
+            if (nl < 0)
+                return;
+            let reply;
+            try {
+                const req = JSON.parse(buf.slice(0, nl));
+                const plan = req.tool_name === "ExitPlanMode";
+                const ok = await io.ask(describeClaudeTool(req.tool_name, req.input), { force: plan });
+                if (ok && plan)
+                    perms.mode = "manual";
+                reply = ok ? { allow: true } : { allow: false, message: plan ? "Plano não aprovado pelo usuário. Pergunte o que ajustar." : "O usuário negou a execução." };
+            }
+            catch (e) {
+                reply = { allow: false, message: `erro no pedido de aprovação: ${e?.message ?? e}` };
+            }
+            conn.end(JSON.stringify(reply) + "\n");
+        });
+        conn.on("error", () => { });
+    });
+    server.listen(sock);
+    server.unref();
+    const close = () => { server.close(); try {
+        fs.unlinkSync(sock);
+    }
+    catch { /* já removido */ } };
+    process.on("exit", close);
+    return { path: sock, close };
+}

package/dist/agent/claude-cli.js

@@ -1,17 +1,23 @@
+import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { listAgents } from "./agents.js";
 import { buildSystemPrompt } from "./prompt.js";
 import { skillsIndex } from "../skills/store.js";
 import { MCP_NAME, MCP_PREFIX, APPROVE_TOOL } from "../mcp/server.js";
-import { ui } from "../ui/ui.js";
+import { ui as terminalUi } from "../ui/ui.js";
 import { MODE_ENV, perms } from "../permissions.js";
 import { wireEffort } from "../model.js";
+import { claudeCommand } from "../util/platform.js";
+import { fmtBytes, findImages, splitOversize } from "../util/images.js";
 // Backend alternativo: delega ao `claude` oficial, que autentica com o /login do usuário.
 // O brito nunca lê nem envia o token da assinatura. Grafo, memória e skills chegam ao claude via MCP.
 export function hasClaudeCli() {
-    return spawnSync("claude", ["--version"], { stdio: "ignore" }).status === 0;
+    const c = claudeCommand(["--version"]);
+    return spawnSync(c.command, c.args, { stdio: "ignore" }).status === 0;
 }
+/** Texto de um tool_result (string ou lista de blocos). */
+const resultText = (c) => (typeof c === "string" ? c : Array.isArray(c) ? c.map((b) => (typeof b?.text === "string" ? b.text : "")).join("") : "");
 /** Nome das tools do Brito → nome que o claude enxerga. */
 const CLAUDE_TOOL = { read_file: "Read", glob: "Glob", grep: "Grep", write_file: "Write", edit_file: "Edit", bash: "Bash" };
 const claudeToolName = (n) => CLAUDE_TOOL[n] ?? MCP_PREFIX + n;
@@ -64,9 +70,9 @@ export function recordStreamEvent(turn, ev, loadedSkills) {
  * Config do servidor MCP entregue ao claude. O servidor roda em outro processo: o env leva o socket de aprovação
  * e o modo de permissão do REPL (vale por turno, pois cada turno sobe um claude novo com esta config).
  */
-export function mcpConfig(cmd, approvalSock, mode) {
+export function mcpConfig(cmd, approvalSock, mode, extraEnv = {}) {
     // alwaysLoad: sem isso o claude adia as tools do Brito atrás do ToolSearch e o modelo raramente chega ao grafo.
-    return { mcpServers: { [MCP_NAME]: { type: "stdio", command: cmd.command, args: cmd.args, alwaysLoad: true, env: { BRITO_APPROVE_SOCK: approvalSock, [MODE_ENV]: mode } } } };
+    return { mcpServers: { [MCP_NAME]: { type: "stdio", command: cmd.command, args: cmd.args, alwaysLoad: true, env: { ...extraEnv, BRITO_APPROVE_SOCK: approvalSock, [MODE_ENV]: mode } } } };
 }
 export class ClaudeSession {
     o;
@@ -93,11 +99,17 @@ export class ClaudeSession {
     constructor(o) {
         this.o = o;
     }
+    get sessionId() { return this.id; }
+    /** Retoma uma conversa do claude (--resume) em vez de começar outra. */
+    resume(id) { this.id = id; this.started = true; }
     reset() { this.id = randomUUID(); this.started = false; this.contextTokens = 0; this.recentTurns = []; }
-    abort() { this.child?.kill("SIGINT"); }
-    args(text) {
+    abort() { if (!this.child)
+        return; this.aborted = true; this.child.kill("SIGINT"); }
+    /** No Windows `kill("SIGINT")` termina o processo sem sinal nem código 130: lembramos que fomos nós que interrompemos. */
+    aborted = false;
+    args(text, imageDirs = []) {
         const { root, approvalSock, stats, mcpCommand } = this.o;
-        const mcp = mcpConfig(mcpCommand, approvalSock, perms.mode);
+        const mcp = mcpConfig(mcpCommand, approvalSock, perms.mode, this.o.env);
         const readOnlyMcp = ["graph_search", "graph_callers", "graph_callees", "graph_impact", "graph_context", "graph_query", "graph_index", "remember", "recall", "skill_load"];
         const system = buildSystemPrompt(root, stats, skillsIndex(root)) +
             `\n\n# Nesta sessão\nAs tools do Brito chegam com o prefixo \`${MCP_PREFIX}\` (ex.: ${MCP_PREFIX}graph_context). Use-as como descrito acima. ` +
@@ -106,6 +118,8 @@ export class ClaudeSession {
             "-p", text,
             this.started ? "--resume" : "--session-id", this.id,
             "--output-format", "stream-json", "--verbose",
+            // Pastas das imagens anexadas: o Read do claude as lê sem pedir permissão (cada --add-dir é uma pasta).
+            ...imageDirs.flatMap((d) => ["--add-dir", d]),
             "--append-system-prompt", system,
             "--mcp-config", JSON.stringify(mcp),
             "--agents", JSON.stringify(claudeAgents()),
@@ -125,12 +139,21 @@ export class ClaudeSession {
     }
     /** Roda um turno renderizando o stream-json com a UI do Brito. */
     send(text) {
+        const ui = this.o.sink ?? terminalUi;
         return new Promise((resolve) => {
             ui.turnStart();
-            const child = (this.child = spawn("claude", this.args(text), {
+            const { ok: imgs, tooBig } = splitOversize(findImages(text, this.o.root));
+            for (const i of tooBig)
+                ui.warn(`${i.name} passa de 5 MB e não foi anexada`);
+            if (imgs.length)
+                ui.info(`🖼 ${imgs.map((i) => `${i.name} (${fmtBytes(i.bytes)})`).join(", ")} anexada${imgs.length > 1 ? "s" : ""}`);
+            // O claude vê a imagem pela tool Read: o prompt diz quais arquivos são imagens anexadas pelo usuário.
+            const prompt = imgs.length ? `${text}\n\n[O usuário anexou ${imgs.length > 1 ? "estas imagens" : "esta imagem"}; abra com a tool Read para vê-${imgs.length > 1 ? "las" : "la"}:\n${imgs.map((i) => `- ${i.path}`).join("\n")}]` : text;
+            const cmd = claudeCommand(this.args(prompt, [...new Set(imgs.map((i) => path.dirname(i.path)))]));
+            const child = (this.child = spawn(cmd.command, cmd.args, {
                 cwd: this.o.root, stdio: ["ignore", "pipe", "pipe"],
                 // `/reasoning none`: o claude desliga o raciocínio com MAX_THINKING_TOKENS=0 (não há `--effort none`)
-                env: wireEffort(this.effort).thinking ? process.env : { ...process.env, MAX_THINKING_TOKENS: "0" },
+                env: { ...process.env, ...this.o.env, BRITO_DEPTH: String(Number(process.env.BRITO_DEPTH ?? 0) + 1), ...(wireEffort(this.effort).thinking ? {} : { MAX_THINKING_TOKENS: "0" }) },
             }));
             let buf = "", stderr = "", ok = true, interrupted = false;
             const names = new Map();
@@ -163,7 +186,7 @@ export class ClaudeSession {
                 else if (ev.type === "user") {
                     for (const b of ev.message?.content ?? [])
                         if (b.type === "tool_result")
-                            ui.toolEnd(b.tool_use_id, !!b.is_error);
+                            ui.toolEnd(b.tool_use_id, !!b.is_error, resultText(b.content));
                 }
                 else if (ev.type === "result") {
                     this.usage.input += (ev.usage?.input_tokens ?? 0) + (ev.usage?.cache_read_input_tokens ?? 0) + (ev.usage?.cache_creation_input_tokens ?? 0);
@@ -197,7 +220,8 @@ export class ClaudeSession {
             child.on("error", (e) => { ok = false; ui.error(`não consegui executar o claude: ${e.message}`); });
             child.on("close", (code, signal) => {
                 this.child = null;
-                interrupted = signal === "SIGINT" || code === 130;
+                interrupted = signal === "SIGINT" || code === 130 || this.aborted;
+                this.aborted = false;
                 if (code !== 0 && !interrupted) {
                     ok = false;
                     if (stderr.trim())

package/dist/agent/context.js

@@ -1,4 +1,6 @@
-export const estimateTokens = (msgs) => Math.ceil(JSON.stringify(msgs).length / 4);
+/** Imagem em base64 tem megabytes, mas custa ~1,6 mil tokens: troca o conteúdo por um marcador antes de medir ou resumir. */
+const stubImages = (_k, v) => (v && typeof v === "object" && v.type === "image" ? { type: "image", note: "x".repeat(6400) } : v);
+export const estimateTokens = (msgs) => Math.ceil(JSON.stringify(msgs, stubImages).length / 4);
 const MAX_OLD_RESULT = 1500;
 /** Fase 1 (barata): encurta tool_results antigos, preservando as últimas `keep` mensagens. */
 export function trimOldToolResults(msgs, keep = 8) {
@@ -33,7 +35,7 @@ export async function summarizeMiddle(client, model, msgs, keepTail = 6) {
         model,
         max_tokens: 2000,
         system: "Resuma a conversa de um agente de programação. Preserve: objetivo, decisões, arquivos/símbolos tocados, erros encontrados, estado atual e próximos passos. Seja denso.",
-        messages: [{ role: "user", content: JSON.stringify(middle).slice(0, 150_000) }],
+        messages: [{ role: "user", content: JSON.stringify(middle, (_k, v) => (v && typeof v === "object" && v.type === "image" ? { type: "image", note: "[imagem omitida]" } : v)).slice(0, 150_000) }],
     });
     const summary = res.content.map((b) => (b.type === "text" ? b.text : "")).join("");
     return [...head, { role: "user", content: `[Resumo da conversa anterior]\n${summary}` }, { role: "assistant", content: "Entendido, continuando a partir do resumo." }, ...tail];

package/dist/agent/loop.js

@@ -1,8 +1,9 @@
 import Anthropic from "@anthropic-ai/sdk";
 import { toApiTools, execTool, isConcurrent } from "../tools/registry.js";
 import { estimateTokens, summarizeMiddle, trimOldToolResults } from "./context.js";
-import { ui } from "../ui/ui.js";
+import { ui as terminalUi } from "../ui/ui.js";
 import { initialModel } from "../model.js";
+import { fmtBytes, findImages, imageBlock, splitOversize } from "../util/images.js";
 export const MODEL = initialModel();
 const COMPACT_AT = Number(process.env.BRITO_COMPACT_TOKENS ?? 120_000);
 export class Agent {
@@ -21,13 +22,15 @@ export class Agent {
     recentTurns = [];
     maxSteps;
     log;
+    ui;
     constructor(system, ctx, opts = {}) {
         this.system = system;
         this.ctx = ctx;
         this.opts = opts;
         this.model = opts.model ?? MODEL;
         this.maxSteps = opts.maxSteps ?? 40;
-        this.log = opts.log ?? ((s) => ui.info(s));
+        this.ui = opts.sink ?? terminalUi;
+        this.log = opts.log ?? ((s) => this.ui.info(s));
     }
     /** Roda um turno completo (até não haver mais tool_use) e devolve o texto final. */
     async send(userText, signal) {
@@ -56,7 +59,18 @@ export class Agent {
         this.lastTurn = turn;
         this.recentTurns = [...this.recentTurns, turn].slice(-3);
         const push = (m) => { this.messages.push(m); turn.messages.push(m); };
-        push({ role: "user", content: userText });
+        // Imagens arrastadas para o terminal chegam como caminhos no texto: anexa como blocos `image`. O registro do turno
+        // (usado na reflexão) guarda só o texto, para não carregar base64.
+        const { ok, tooBig } = splitOversize(findImages(userText, this.ctx.root));
+        for (const i of tooBig)
+            this.log(`⚠ ${i.name} passa de 5 MB e não foi anexada`);
+        if (ok.length) {
+            this.log(`🖼 ${ok.map((i) => `${i.name} (${fmtBytes(i.bytes)})`).join(", ")} anexada${ok.length > 1 ? "s" : ""}`);
+            this.messages.push({ role: "user", content: [...ok.map(imageBlock), { type: "text", text: userText }] });
+            turn.messages.push({ role: "user", content: userText });
+        }
+        else
+            push({ role: "user", content: userText });
         await this.compactIfNeeded();
         let finalText = "";
         for (let step = 0; step < this.maxSteps; step++) {
@@ -70,7 +84,7 @@ export class Agent {
                 messages: this.messages,
             }, { signal });
             if (!this.opts.quiet)
-                stream.on("text", (t) => ui.text(t));
+                stream.on("text", (t) => this.ui.text(t));
             const msg = await stream.finalMessage();
             this.contextTokens = msg.usage.input_tokens + (msg.usage.cache_read_input_tokens ?? 0) + (msg.usage.cache_creation_input_tokens ?? 0);
             this.usage.input += msg.usage.input_tokens + (msg.usage.cache_read_input_tokens ?? 0) + (msg.usage.cache_creation_input_tokens ?? 0);
@@ -82,7 +96,7 @@ export class Agent {
             if (text)
                 finalText = text;
             if (!this.opts.quiet)
-                ui.textEnd();
+                this.ui.textEnd();
             const uses = msg.content.filter((b) => b.type === "tool_use");
             if (msg.stop_reason !== "tool_use" || uses.length === 0) {
                 turn.finished = true;
@@ -91,13 +105,13 @@ export class Agent {
             const runOne = async (u) => {
                 const t0 = Date.now();
                 if (!this.opts.quiet)
-                    ui.toolStart(u.id, u.name, u.input);
+                    this.ui.toolStart(u.id, u.name, u.input);
                 const denied = this.opts.tools && !this.opts.tools.has(u.name);
                 const r = denied ? { text: `Tool não permitida para este agente: ${u.name}`, isError: true } : await execTool(u.name, u.input, this.ctx);
                 if (this.opts.quiet)
-                    this.log(ui.toolLine(u.name, u.input, Date.now() - t0, r.isError));
+                    this.log(terminalUi.toolLine(u.name, u.input, Date.now() - t0, r.isError));
                 else
-                    ui.toolEnd(u.id, r.isError);
+                    this.ui.toolEnd(u.id, r.isError, r.text);
                 return { type: "tool_result", tool_use_id: u.id, content: r.text.slice(0, 40_000), is_error: r.isError };
             };
             // Leituras puras rodam em paralelo; qualquer escrita/aprovação força execução em série.
@@ -109,7 +123,7 @@ export class Agent {
             push({ role: "user", content: results });
             await this.compactIfNeeded();
         }
-        ui.warn("Limite de passos atingido.");
+        this.ui.warn("Limite de passos atingido.");
         return finalText || "(limite de passos atingido sem resposta final)";
     }
     async compactIfNeeded() {

package/dist/agent/prompt.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { shellNote } from "../util/platform.js";
 /**
  * Frase sobre o grafo para o system prompt. "0 símbolos" sem contexto faz o modelo concluir que o grafo é inútil, mas o
  * projeto pode só estar vazio no início (e o grafo se atualiza sozinho a cada edição). Por isso: rótulo do momento da
@@ -37,7 +38,7 @@ export function buildSystemPrompt(root, graphStats, skills = "") {
 
 # Ambiente
 Diretório do projeto: ${root}
-Data: ${new Date().toISOString().slice(0, 10)}${skills ? `\n\n# Skills disponíveis (use skill_load)\n${skills}` : ""}${projectDoc}`;
+Data: ${new Date().toISOString().slice(0, 10)}${shellNote()}${skills ? `\n\n# Skills disponíveis (use skill_load)\n${skills}` : ""}${projectDoc}`;
 }
 import { skillsIndex } from "../skills/store.js";
 export function buildSubagentPrompt(root, def) {

package/dist/agent/sink.js

@@ -0,0 +1 @@
+export {};