# PrimoCode v10.6.0

Agente de engenharia brasileiro para o terminal, no estilo Claude Code.
Cria arquivos de verdade, roda comandos, **controla o navegador e o desktop** —
e lembra do que fez entre uma sessão e outra.

**A API já vem configurada.** Entrou na sua conta Conecta Primo AI, pode usar: não há provedor para escolher, chave para colar nem teto de gasto seu. Os modelos são os grátis do
OpenRouter, e cada apelido (`top`/`main`/`fast`) é uma **corrente**: se um modelo
está no limite de pedidos, o próximo atende. Você não vê o erro, e não paga nada.

```
 ▐▛███▜▌   Primo Code v10.6.0
▝▜█████▛▘  Bem-vindo de volta, Joel
  ▘▘ ▝▝    ~/primocode  · /dir <pasta> muda
```

Personalize o mascote (`primo`, `fox`, `cat`) e o nome com que ele te chama —
veja `/mascot` e `/name`.

## O que mudou na 10.4

- **A tela do OpenCode.** O PrimoCode abre em tela cheia: a conversa rola em
  cima, a caixa de digitar fica presa no pé, e a barra da direita mostra a
  sessão, o contexto (tokens e % usado), o modo, a pasta e a versão. Sem
  conversa, a home põe o logo e a caixa no meio. `Tab` troca o modo, `Ctrl+P`
  abre os comandos (o menu abre em cima da caixa), a roda do mouse e o
  `PgUp`/`PgDn` rolam a conversa. `PRIMOCODE_TELA=linha` volta ao jeito antigo.
- **Motion sem encostar na borda.** Margem de 6% nas laterais e 7% em cima e
  embaixo, e 4% entre elementos — garantido em código antes do render.
- **Vídeo gravado em 3D (`estilo: personagem`).** Personagens modelados — gente
  ou robô — conversando num set (podcast, estúdio, escritório). A boca segue a
  voz letra por letra, eles piscam, gesticulam e viram a cabeça para quem fala.
  A câmera corta como num programa gravado: aberto, ombro, close e detalhe,
  com o balanço de câmera na mão. Por cima: legenda grossa palavra por
  palavra, o nome de quem fala, o cartão de destaque, o REC e o grão de filme.
  Peça "um podcast", "uma entrevista" ou "o Claude falando em 3D".
- **A peça do site, tirada pelo código.** `estudio_midia acao:elementos` lê o
  site e lista logo, menu, título, botões, cartões, preço; `acao:elemento` tira
  uma delas sozinha, em PNG transparente no dobro da resolução, com o código
  (HTML, fonte, cor, raio) para redesenhar se quiser.
- **Recorte de fundo com IA sem instalar nada.** Com o `uv` na máquina, o
  `acao:recortar` usa o rembg num ambiente à parte, em vez do corte por cor.
- **O logo do Claude saiu do cardápio dos vídeos.**
- **Com Claude, Codex ou chave própria, o agente não esquece o arquivo que
  acabou de ler** (antes relia o mesmo arquivo várias vezes).

## O que mudou na 10.0

- **A potência vem do sistema, não do modelo.** O mesmo pedido de landing
  (3 arquivos) caiu de 793 s para 377 s, e de 62 voltas de agente para 5.
  - O construtor faz o produto direto, e o Chrome escondido confere.
  - Ele não relê o arquivo que acabou de escrever.
  - O conteúdo já gravado não volta ao modelo a cada ida.
  - O `edit_file` acha o trecho mesmo com espaço ou indentação errados.
- **Digite enquanto ele trabalha.** O recado entra na tarefa depois do passo
  atual, sem esperar ela acabar.
- **A tela mostra que está andando.** O spinner mostra os segundos e o que
  está chegando, e a espera pela vez no modelo aparece.
  `PRIMOCODE_TRACO=1` diz, a cada ida, o tamanho, o erro e a espera.
- **Navegador por refs.** A página chega como `@e3 [button] "Entrar"`, e o
  clique vai pela ref, sem seletor CSS chutado.
- **`primocode video help`: um editor de vídeo por linha do tempo.** O
  agente opera pelo shell: cortar silêncio, apagar palavras, legendas,
  layouts, cor, zoom, undo e export em ffmpeg.
- **Motion novo.** Três estilos:
  - `vox`, o explainer editorial;
  - `marca`, o brand reveal com as alças da fonte, logo cromado e cartões
    de cor;
  - `lancamento`, o filme de produto.
- **`/voice` ficou simples.** Você fala, e o que disse entra como se tivesse
  digitado. A resposta sai em voz alta.
- **Saíram** a janela (`/rc`, `/ide`, `primo --app`), a orb e o "ei, primo".

## Por que trocar o Claude Code pelo PrimoCode

| | PrimoCode | Assistentes gringos de terminal |
|---|---|---|
| **Idioma** | Nasceu em português do Brasil — fala como gente, não como manual traduzido | Inglês primeiro; PT-BR é tradução |
| **Chave de API** | **Não precisa.** Instala e usa — o modelo já vem hospedado | Exige conta e chave de API própria |
| **Controla a máquina** | Navegador (Chrome real) **e** desktop: mouse, teclado, tela | Em geral só arquivos e shell |
| **Memória** | Cada projeto lembra o que foi feito, entre sessões | Esquece ao fechar |
| **Instalação** | Node puro, **zero dependências** — segundos | Pacotes e dependências |
| **Cara própria** | Mascote, nome e temas que você escolhe | Fixo |
| **Modelos** | Escolhidos pelo produto (`/effort` regula o esforço), ou a sua própria chave com `/api` | Preso ao provedor do fabricante |

Em uma frase: **é o poder de um agente de código no terminal, em português, controlando o seu computador de verdade — sem você precisar configurar chave de API nenhuma.**

## Instalação

```bash
npm install -g primocode
```

Requer **Node.js 18.17+**. O CLI não tem dependência nenhuma — só a stdlib do
Node — e por isso instala em segundos. Depois é só `primocode`: ele abre o
login no navegador e, voltando, está pronto.

Não tem Node? Instale em [nodejs.org](https://nodejs.org) e repita o comando
acima. Quem já clonou este repositório pode usar os instaladores que moram
aqui (`install.sh` no macOS/Linux/WSL, `install.cmd` no Windows): eles detectam
o Node, oferecem instalar, e apontam o npm para `~/.npm-global` em vez da pasta
do sistema — que é o que evita o `EACCES` da tabela abaixo.

### Se der erro

| Erro | O que fazer |
|---|---|
| `command not found: npm` | Você não tem Node. Rode o `install.sh` — ele detecta, pergunta e instala pra você. |
| `EACCES ... mkdir '/usr/local/lib/node_modules'` | O npm está apontando para uma pasta do sistema. **Não use `sudo`** — rode o `install.sh`, que move o npm para `~/.npm-global`. |
| `command not found: primocode` | A instalação não terminou, ou o PATH não foi recarregado. Abra um terminal novo; se persistir, rode o `install.sh` de novo. |

O `install.sh` é seguro de rodar quantas vezes quiser — ele conserta o que estiver errado e não duplica nada.

## Como funciona

Todo trabalho acontece dentro de uma **pasta de projeto**, em `~/primocode/`:

```
~/primocode/
├── memory-geral.md          <- sobre você: nome, preferências, convenções
├── jogo-de-carro/
│   ├── memory.md            <- o que este projeto é e o que já foi decidido
│   ├── index.html
│   └── src/game.js
└── site-de-vendas/
    ├── memory.md
    └── ...
```

Ao receber o primeiro pedido da sessão, o PrimoCode deriva um nome de projeto
do que você pediu. Se já existir um projeto parecido, ele **pergunta** antes de
criar pasta nova:

```
Primo Code ❯ faça um jogo de carro 2D

  Já existe um projeto parecido: jogo-de-carro
? Continuar nele? (S/n)
```

Os dois arquivos de memória são lidos no começo de cada tarefa e atualizados no
fim. É por isso que a IA não esquece o projeto entre sessões.

## Modos

| Modo | O que faz |
|---|---|
| **Auto** (padrão) | Escolhe por pedido: conversa vai pro chat, tarefa vai pro agente |
| **Primo Code** | Agente completo — cria arquivos, roda comandos, abre o navegador |
| **Chat** | Conversa pura, sem tools |

Alterne com `/mode auto`, `/mode primocode` ou `/mode chat`. A escolha fica
guardada entre sessões.

**Por que o auto é o padrão.** O modo Primo Code manda o catálogo das 30
ferramentas em todo pedido — cerca de 4.700 tokens antes de você digitar a
primeira letra. Um "oi" custava o mesmo que uma refatoração, e num plano com
teto diário isso acaba a cota no meio da tarde. O auto decide na sua máquina,
sem chamar o modelo para isso, e mostra o que escolheu:

```
Auto ❯ oi
  ⎿ Chat · cumprimento

Auto·chat ❯ conserta o bug do login em src/auth.js
  ⎿ Primo Code · cita arquivo ou caminho
```

Na dúvida ele vai para o chat: errar para chat custa repetir o pedido, errar
para o agente custa token e pode escrever arquivo que ninguém pediu.

## Onde ele trabalha

**Por padrão, sempre `~/primocode`** — não importa de onde você abriu o
PrimoCode. Antes ele adotava a pasta atual do terminal, e o mesmo "crie um site"
caía num lugar diferente a cada vez; quem digitava não tinha como saber onde ia
parar. Agora o começo é sempre o mesmo, e o cabeçalho avisa em amber qual é.

Para trabalhar em outra pasta, três caminhos:

| Situação | Pasta de trabalho |
|---|---|
| **Falar o nome dela no pedido** — "crie o index.html na pasta loja-do-joao" | ele procura no seu computador (`~/primocode`, Downloads, Documentos, Desktop, projetos…) e muda sozinho |
| `/dir ~/meus-projetos/site` | a pasta que **você** escolher, onde ela estiver |
| `/project loja` | cria `~/primocode/loja`, com memória própria |

A busca por nome é conservadora de propósito: se achar duas pastas com o mesmo
nome, ela **lista e espera** o `/dir` em vez de escolher — heurística não deve
decidir onde um agente escreve arquivo. E nome de arquivo nunca é confundido com
pasta: "edita o `src/app.js`" não muda pasta nenhuma.

**Pasta de projeto nova só nasce quando ele vai mexer em arquivo.** Pedir "abre o
Chrome" não cria projeto — antes criava, e `~/primocode` enchia de pasta vazia.

`/dir` sem argumento mostra a pasta ativa e de onde ela veio. Caminho relativo
resolve contra a pasta ativa, então depois de um `/dir` o `/dir src` entra na
subpasta. Se a pasta não existir, ele pergunta antes de criar; se for a sua home
ou a raiz do disco, pergunta de novo — é onde um arquivo escrito por engano dói
mais.

## Ferramentas do agente

| Tool | Para quê |
|---|---|
| `write_file` | Cria arquivo novo ou reescreve inteiro |
| `edit_file` | **Troca um trecho exato.** É o que evita reescrever 800 linhas pra mudar uma |
| `multi_edit` | Várias trocas no mesmo arquivo, em ordem, tudo-ou-nada |
| `read_file` | Lê o arquivo, com `offset`/`limit` para os grandes |
| `glob` | Acha arquivos por padrão: `**/*.js`, `src/**/*.{ts,tsx}` |
| `grep` | Procura texto/regex **dentro** dos arquivos, com arquivo e linha |
| `list_dir` | Árvore de arquivos |
| `run_shell` | Roda comando na pasta do projeto |
| `run_in_new_terminal` | Sobe servidor de dev / watch em outro terminal |
| `write_todos` | Plano de tarefas da sessão, visível no terminal |
| `open_in_browser` | Abre HTML ou URL no navegador padrão |
| `spawn_agent` | Delega uma sub-tarefa a outro agente |

O `edit_file` é rigoroso de propósito: se o trecho não existe, ou aparece mais
de uma vez sem `replace_all`, ele **recusa** e devolve as linhas reais do
arquivo — em vez de editar o lugar errado.

### Controle de navegador e desktop

O agente não só abre o navegador — ele **age** nele, e no computador também.

| Tool | Para quê |
|---|---|
| `browser_open` | Abre a página num Chrome controlado (CDP) e espera carregar |
| `browser_click` | Clica por texto visível, seletor CSS ou coordenada |
| `browser_type` | Digita num campo (por seletor) ou onde o foco estiver |
| `browser_key` | Enter, Tab, Escape, setas… |
| `browser_read` | Lê o texto visível da página (conferir o resultado) |
| `browser_screenshot` | Print da página, salvo no projeto |
| `browser_scroll` / `browser_wait` / `browser_eval` | Rolar, esperar seletor, rodar JS |
| `desktop_screenshot` | Print da tela inteira do usuário |
| `desktop_click` / `desktop_move` / `desktop_drag` | Mouse na tela real |
| `desktop_type` / `desktop_key` / `desktop_scroll` | Teclado e rolagem do sistema |
| `desktop_size` | Resolução da tela, para calcular coordenadas |

O navegador roda via Chrome DevTools Protocol (sem dependências npm).

**Requisitos por plataforma** (as ferramentas dão um erro claro se faltar algo):

| | Navegador | Desktop (mouse/teclado) | Screenshot da tela |
|---|---|---|---|
| **Windows** | Chrome ou Edge | nativo (PowerShell) | nativo (PowerShell) |
| **macOS** | Chrome/Chromium | `brew install cliclick` | nativo (`screencapture`) |
| **Linux** | Chrome/Chromium | `apt install xdotool` | `scrot`, `gnome-screenshot`, `spectacle`, `maim` ou ImageMagick |

Variáveis de ambiente úteis:
- `CHROME_PATH` / `PRIMOCODE_CHROME` — aponta para um Chrome fora do caminho padrão
- `PRIMOCODE_BROWSER_HEADLESS=1` — roda o navegador sem janela (CI/servidor)

## O Estúdio: vídeo, slides e arte

Sete ferramentas (`estudio_projeto`, `estudio_plano`, `estudio_midia`,
`estudio_narrar`, `estudio_video`, `estudio_render`, `estudio_site`), um
renderizador só — o **Remotion** — e nenhum template. Não há tema pronto,
layout pronto nem fundo pronto: o plano é feito de **primitivas** (texto,
forma, imagem, vídeo, ícone, legenda, componente) com keyframes e câmera
própria por cena, e é a IA que compõe cada vídeo do zero. Lista fechada de
seis temas é template com outro nome, e o resultado dela é todo vídeo sair
igual.

Antes de produzir entra o **diretor** (`planejar_producao`): uma conversa
própria que decide arco, narração falada cena a cena, voz, direção de arte e
a mídia a buscar — e só então o produtor monta as cenas. Ele existe porque
quem está montando o JSON já gastou a atenção no JSON, e é ali que o roteiro
vira legenda de slide ("Vantagens", "Nossos serviços") em vez de virar fala.

De onde vem o material, tudo sem chave de API:

| O quê | Fonte |
|---|---|
| Ícones | **Iconify** — 200 mil ícones, 150 coleções |
| Imagens e som | **Openverse** (licença aberta); Pexels/Freesound entram por cima quando há chave |
| Fontes | **Google Fonts** inteiro |
| Logo de marca | **Simple Icons** → o site da empresa → **Wikimedia Commons** |
| Identidade visual | o próprio site: cor, paleta, tipografia e o que a marca diz de si |

A licença desce junto de tudo, num `.licenca.json` ao lado do arquivo:
descobrir depois de publicar que a foto exigia crédito é tarde.

## Subagentes

Para tarefas com partes independentes, o agente delega:

```
Primo Code site ❯ crie o visual do site

  ◆ Agente criar o CSS
      ⎿ Write style.css
      ⎿ criado · 40 B
  ◆ Criei style.css com fundo #111

Pronto: CSS delegado e criado
```

O subagente tem conversa própria — **não vê o seu diálogo** — e devolve só o
resumo final. Ele não pode criar outro subagente, então a árvore nunca cresce
sem controle.

## Nunca "pronto!" falso

Se uma ferramenta falha e o agente tenta encerrar dizendo que deu certo, o
PrimoCode barra e devolve a tarefa para ele:

```
⎿ Edit app.js
⎿ Trecho não encontrado
    → agente tenta finish("Porta alterada")
    → BARRADO: "NÃO terminou. Estas tools falharam..."
⎿ Edit app.js
⎿ 1 troca · ±0 linhas          ← agora foi de verdade
```

## Testes

```bash
npm test
```

25 verificações sobre glob, grep, edit_file, leitura por partes e bloqueio de
caminho fora do projeto.

## Uso

```bash
primocode                              # interativo
primocode "crie um jogo de carro"      # one-shot
primocode -f app.js "onde está o bug?" # com arquivo anexado
primocode -c                           # continua a última conversa salva (--continue)
```

## Comandos

| Comando | Descrição |
|---|---|
| `/dir <caminho>` | Trabalha numa pasta que já existe, onde você quiser |
| `/project` | Lista projetos. `/project <nome>` cria em `~/primocode` |
| `/projetos [n]` | Os projetos de `~/primocode` do mais recente para o mais antigo, com quando mexeu e o tamanho. `/projetos 2` entra no segundo (o `/project` sem nome mostra a mesma lista) |
| `/novo <descrição>` | Começa um projeto NOVO do zero, em pasta própria com nome escolhido pelo modelo — sem cair num projeto parecido que já existe |
| `/mode primocode\|chat\|auto` | Alterna o modo (fica guardado) |
| `/voice` | Modo voz: você fala, e o que disse entra como se tivesse digitado (na fila, ou como recado no meio da tarefa). A resposta sai em voz alta, resumida; falar por cima corta. `/voice parar` desliga |
| `/comandos` | Seus comandos: um `.md` em `~/.primocode/comandos/` (ou `<projeto>/.primocode/comandos/`) vira `/nome`, e `$ARGUMENTOS` recebe o que vem depois. Já vêm `/revisar`, `/explicar` e `/publicar`. `/comandos novo <nome>` cria um |
| `/skills` · `/marketplace` | O que ele sabe fazer bem. Tela navegável pelas setas, e "New Skill" para escrever a sua |
| `/connectors` | Quem está atendendo os seus pedidos (só mostra — não há o que configurar) |
| `/effort` | O esforço do agente, num slider (←/→, Enter confirma): do `low` ao `ultracode`. O modelo sai daí |
| `/permissoes auto\|perguntar\|livre` | Quando ele pede licença. `auto` (padrão) roda tudo, mas pergunta antes do que não tem volta; `perguntar` pede antes de todo comando e toda escrita; `livre` nunca pergunta (fica guardado) |
| `/api` | Roda com a SUA assinatura (Claude Code, Codex, sem chave) ou a SUA chave (Gemini, ChatGPT, Claude, Groq, OpenRouter, DeepSeek), direto do seu computador, sem o limite do servidor. `/api modelo <nome>` troca o modelo · `/api off` volta ao servidor |
| `/init` | Estuda o projeto e escreve um `PRIMO.md` na raiz: o que é, como rodar, stack, convenções. Ele é lido em todo pedido (vale também `AGENTS.md` ou `CLAUDE.md`, e `~/.primocode/PRIMO.md` para todos os projetos) |
| `@arquivo` | No meio do pedido (`melhora o @index.html`, `@"nome com espaço.txt"`) anexa aquele arquivo do projeto só a esse pedido. Até 40 KB por arquivo, 120 KB no total |
| `/attach <arquivo>` | Anexa arquivo ao próximo pedido |
| `/detach` · `/files` | Remove / lista anexos |
| `/all` | Lista as 46 ferramentas que ele sabe usar, por grupo |
| `/desfazer` · `/undo` | Volta o projeto para como estava antes do último pedido — inclusive o que um comando apagou, moveu ou gerou (com git instalado, cada pedido tira uma foto do projeto num git à parte, que não toca no seu `.git`; `node_modules`, `dist` e o que o `.gitignore` ignora ficam de fora). Sem git, volta o que o agente escreveu com as ferramentas de arquivo. `/desfazer lista` mostra os pedidos e quantos arquivos cada um mudou · `/desfazer N` volta os N últimos |
| `/tree [n]` | Árvore do projeto atual |
| `/read <arquivo>` | Mostra um arquivo do projeto |
| `/run <comando>` | Executa no shell, dentro da pasta do projeto |
| `/open <arquivo\|url>` | Abre no navegador |
| `/abrir` | Abre o projeto atual no navegador: o servidor dele, se estiver de pé, ou a `index.html` (o `/open` sem nada faz o mesmo) |
| `/copiar` | Copia a última resposta para a área de transferência (pbcopy, clip, wl-copy/xclip/xsel) |
| `/historico [termo]` | Procura nos seus pedidos guardados nesta máquina (`~/.primocode/history.jsonl`), do mais recente. As conversas inteiras da conta ficam no `/chats` |
| `/status` | Health check do servidor |
| `/offline` | Temporário: sobe o `primocode-server` no seu computador (a pasta ao lado do CLI, ou `/offline <caminho>`) com as chaves de `~/.primocode/servidor.env` e aponta a sessão pra ele. `/offline off` volta ao servidor de antes |
| `/doctor` | Confere tudo com ✓/✗: Node, servidor, `/api`, Chrome, Python+PyObjC (cursor, macOS), disco e config. Cada ✗ diz como consertar |
| `/custo` | Tokens enviados e recebidos e pedidos feitos nesta sessão, por provedor (estimado em caracteres ÷ 4 quando o provedor não manda o número) |
| `/atalhos` | As teclas: Esc Esc para o agente, `!` roda no shell, Alt+Enter quebra linha… |
| `/name <nome>` | Como o Primo te chama na saudação |
| `/mascot [nome\|n]` | Galeria dos 10 mascotes lado a lado (primo, fox, cat, robo, coruja, dragao, fantasma, capivara, polvo, pinguim), cada um com nome e bordão na abertura. Escolha por nome ou número. Depois de cada tarefa ele reage numa linha (`(^‿^)` pronto, `(°_°)` não terminou); `/mascot reacoes off` desliga |
| `/config` | Mostra suas preferências e onde ficam salvas |
| `/clear` · `/cls` | Limpa conversa / tela |
| `/uninstall` | Remove o PrimoCode (seus projetos ficam) |
| `/exit` | Sair |

## Configuração

`~/.primocode/config.json`:

```json
{
  "server": "https://primocode-server-production.up.railway.app",
  "model": "main",
  "token": null
}
```

Ou por variável de ambiente — elas têm prioridade:

```bash
export PRIMOCODE_SERVER="https://primocode-server-production.up.railway.app"
export PRIMOCODE_MODEL="main"
export PRIMOCODE_TOKEN="..."   # só se o servidor exigir
```

## Segurança

Todo arquivo que o agente escreve (`write_file`, `edit_file`, `multi_edit`) é
resolvido **dentro** da pasta do projeto. Caminho absoluto ou com `../` é
recusado.

Os **comandos** de terminal não têm essa cerca: eles rodam com as suas
permissões. Por isso, no modo padrão (`/permissoes auto`), ele **pergunta antes
do que não tem volta** — `rm -rf` fora do projeto ou em `~` e `/`, `sudo`,
`git push --force`, `git reset --hard`, `git clean -fd`, `curl … | sh`, `dd`,
`mkfs`, `npm publish`, desligar o computador. Apagar `node_modules` ou `dist`
dentro do projeto não pergunta. A régua está em `lib/perigo.js`.

Mexer no mouse e no teclado (controle do computador) sempre pede licença.

## Arquitetura

```
┌────────────────┐   HTTPS/SSE    ┌───────────────────┐   HTTPS   ┌──────────┐
│  primocode CLI │ ─────────────► │  primocode-server │ ────────► │OpenRouter│
│  (seu terminal)│ ◄───────────── │     (Render)      │ ◄──────── │   API    │
└────────────────┘                └───────────────────┘           └──────────┘
     executa as tools                monta o prompt
     localmente                      e fala com o modelo
```

As tools rodam **no seu computador** — o servidor nunca toca nos seus arquivos.
Ele decide o que fazer; o CLI faz e devolve o resultado.

## Licença

MIT © ConectaPrimoAI