# PrimoCode v11.4.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 v11.4.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`.

## Novidades da 11.2

- **App desktop (Electron)** com a mesma tela do protótipo: conversa, Estúdio, projetos, agentes, kit da marca, avisos e busca. Ele sobe o motor sozinho e fala com ele pelo `app-server` (JSON-RPC). `primocode app` abre o app instalado; no repo, `npm run app:dev`.
- **Celular (Android):** `primocode server --rede` e a tela **Parear celular** geram um QR com token revogável. O app do celular (`mobile/`, Capacitor) usa o mesmo motor do computador. APK de teste: `npm run mobile:build`.
- **Motor reescrito em módulos** (`lib/motor/`, `lib/app-server/`), com turno, aprovação, voz e piloto automático. A CLI ganhou `/estudio`, `/agentes`, `/piloto`, `/avisos` e `/buscar`.
- **Primeira execução:** uma tela só, pulável (nome, esforço, kit da marca). Poppins vai embutida, sem fonte remota.

### App e celular, em duas linhas

```
npm run app:dev      # desktop (precisa de `cd app && npm install` uma vez)
npm run mobile:build # APK debug (JDK 17 e Android SDK)
```

## Primo (voz)

`/voice` abre a tela do Primo: agenda, clima, música, máquina e um robô 3D no centro. Diga **"Primo"** para chamar; ele fala frase a frase e você pode interromper. Na primeira vez cria `~/.primocode/voz-venv` sozinho (`primocode doutor` mostra o estado). Robô offline: `"robo":"expressive"` em `~/.primocode/voz.json`.

## Novidades da 11.0

- **O placar:** o PrimoCode aprende, neste computador, qual modelo grátis acerta mais em cada tipo de tarefa e passa a preferir esse (`/placar`). Nada sai da máquina.
- **Mais ferramentas:** `buscar_web`, `ler_url`, `perguntar`, `agentes_buscar` e `capacidade_buscar` (64 no total), diagnóstico depois de cada edição e `run_shell` em segundo plano.
- **Mais agentes:** 110 especialistas e 204 capacidades, `/review` em duas passadas, `/pesquisar` com fontes, `/testar-app`, `--tentativas N`, `primocode preview` e `primocode review --pr N`.
- **Motion, editor e documentos:** o kit de peças soltas, a câmera viva no editor de vídeo e o deck de ponta a ponta (.pptx e PDF). Detalhes em `RELEASE-11.0.md`.

## Novidades da 10.14

- **Vídeo de motion de ponta a ponta** (EffectCraft, 68 receitas, voz, trilha, prévia e editor por comando). Detalhes no `CHANGELOG.md`.
- **Exportar para redes** em três formatos, com capa, legenda e créditos. **Kit de marca** com `primocode marca`.
- **Sandbox** (`/sandbox on`), **hooks**, `-p`, `--resume`, `--worktree`, modo plano e **planos por recurso** (`primocode planos`).
- **Instalou, está pronto:** o motor After Effects baixa sozinho. `primocode doutor` mostra o que falta e como resolver.

## O que mudou na 10.14

- **Motor After Effects:** a ferramenta `estudio_ae` roda um JSX e renderiza o mp4, com a skill `after-effects`.
- **Projetos completos:** seis receitas que a IA consulta (`estudio_midia acao:projetos`), uma delas em After Effects.
- **MCP remoto:** servidores por HTTP (`{"type":"http","url":"https://…/mcp"}` no `mcp.json`), com login OAuth pelo navegador.
- **Clube do Motion:** `primocode mcp login clube-do-motion` entra com a conta assinante e libera projetos de motion, referências, skills e músicas.
- O token fica em `~/.primocode/mcp-tokens.json` (só você lê). `primocode mcp logout <nome>` apaga.

## O que mudou na 10.13

- **Motion pelas referências:** o título enche a tela (rótulo nunca abaixo de 2% da altura), a cena dura de 1 a 2 s, o texto entra com ataque rápido e freio forte, e a frase sai inteira. As saídas que espalhavam letras saíram. O círculo de caneta na palavra-chave ganha o ✓. Sem quadro morto entre as cenas. A conta está em `docs/planos/2026-10-15-motion-pelas-referencias.md`.
- **Revisão do texto:** antes do render, o PrimoCode avisa texto pequeno demais para o celular e contraste abaixo de 3:1.
- **Camadas sem legenda dobrada:** a cena escrita pela IA não repete a fala por cima da legenda.
- **Voz do VoiceStudio:** com o app aberto no Mac, ele narra primeiro. Fechado, a narração segue para o Gemini (`PRIMOCODE_SEM_VOICESTUDIO=1` desliga).
- **Edição de vídeo:** num vídeo sem pedido falado, a edição não para mais na legenda. O agente corta, dá zoom e cor.

## O que mudou na 10.12

- **Vídeo em camadas:** você grava só a fala e o PrimoCode monta o resto. O rosto vira cartão, bolinha no canto, some e volta, com mola, e o motion ocupa o espaço que sobra. A legenda vai palavra por palavra, com a palavra forte em serif itálico. O áudio nunca pula. Use `estudio_video acao:"camadas"`: sem batidas, ele propõe pela transcrição.
- **Fábrica:** camadas 3D empilhadas e terminal com o prompt sendo digitado.

## O que mudou na 10.11

- **Barulhinhos:** cada palavra, item e ponto que entra no motion faz um som pequeno, numa escada de notas, com tique, clique de mouse, blip, swoosh e sub na revelação. A cena pode pedir o som no quadro certo (`sons: [{t, som}]`).
- **Vídeo sem narração:** `semNarracao: true` (ou "sem voz" no pedido) gera só motion, trilha e efeitos, e a trilha não abaixa.
- **Efeitos de fábrica:** peça do site em 3D com impacto, brilho que varre, cor que inunda, risco em várias linhas, entrada com física e raios de luz. Quando nenhuma cena é escrita, o plano devolve o cardápio de efeitos.
- **3D com peso:** o boneco antecipa, respira, pula amassando e anda com o quadril.
- **Risco:** texto riscado que quebra em várias linhas ganha um traço por linha.

## 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.**

## Comparado ao Claude Code e ao Codex

Tabela completa, com `arquivo:linha`, em [docs/paridade.md](docs/paridade.md). O resumo:

| | Claude Code | Codex | PrimoCode |
|---|---|---|---|
| Hooks antes/depois de ferramenta | tem | parcial | tem (`~/.primocode/hooks.json`) |
| Modo só leitura (plan) | tem | read-only | tem (`/perms plano`) |
| Headless (`-p`, JSON, stdin) | tem | `codex exec` | tem |
| Desfazer por pedido | `/rewind` | usa git | tem (`/undo`) |
| MCP stdio, HTTP, OAuth | tem | tem | tem |
| Sandbox de SO | opcional | tem | não |
| Worktrees | tem | não | não |

Hook em 3 linhas: `{"PreToolUse":[{"matcher":"run_shell","command":"./checar.sh"}]}`. O comando
recebe o evento em JSON no stdin; sair com código 2 bloqueia a ferramenta. Em script:
`git diff | primocode -p "revisa" --output-format json --permission-mode plan`.

## 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 |
| `buscar_web` · `ler_url` | Busca na internet (links com trecho) e lê uma página em markdown, sem chave |
| `perguntar` | Pergunta com 2 a 4 opções, só quando está bloqueado |
| `agentes_buscar` · `capacidade_buscar` | Acha o especialista (110) ou a receita pronta (204) certa |

Depois de cada edição, o verificador mais barato da linguagem roda e o erro volta junto. A lista completa: `/help all`.

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.

## Motor After Effects (EffectCraft)

A ferramenta `estudio_ae` usa o [EffectCraft](https://github.com/storytold/effectcraft) (storytold, licença MIT/Apache-2.0): ele roda JSX (ExtendScript) no modelo de objetos do After Effects, sem o After Effects instalado. O PrimoCode baixa o binário 0.11.1 na primeira vez para `~/.primocode/bin/effectcraft-0.11.1/` e confere o sha256. `PRIMOCODE_EFFECTCRAFT_BIN` aponta para um binário seu. A IA escreve o JSX, as fontes vêm do Google Fonts e os quadros de conferência saem em `ae/`.

## Projetos completos

Seis receitas originais em `lib/plugin/estudio/dados/projetos/` (narrado, produto, SaaS, só com sons, elementos de site e After Effects). Cada uma traz a ficha técnica, as etapas e um prompt com `{{CAMPOS}}`. A IA lista com `estudio_midia acao:"projetos"` e lê uma com `acao:"projeto" nome:"<id>"`.

## 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               # o CLI: ferramentas, agente, Estúdio, vídeo (sai com 0)
npm run test:server    # o servidor, dentro de server/
```

## 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)
primocode --resume [id]                # retoma uma conversa (sem id: lista e você escolhe)
primocode --worktree <nome>            # worktree ../<repo>-<nome> em branch nova, e abre a sessão lá
```

## Comandos

| Comando | Descrição |
|---|---|
| `/resume [n\|id]` | Lista as conversas salvas ou retoma uma |
| `/worktree <nome>` | Cria `../<repo>-<nome>` numa branch nova e entra nele (só em repo git) |
| `/dir <caminho>` | Trabalha numa pasta que já existe, onde você quiser |
| `/project` | Lista projetos. `/project <nome>` cria em `~/primocode` |
| `/projects [n]` | Os projetos de `~/primocode` do mais recente para o mais antigo, com quando mexeu e o tamanho. `/projects 2` entra no segundo (o `/project` sem nome mostra a mesma lista) |
| `/new <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 |
| `/new` sem nada | Pra quem nunca programou: 3 perguntas (o que criar, pra quem, onde abre) e o primeiro app sai. Sem ideia? Enter mostra 6 ideias pra escolher pelo número |
| `/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 |
| `/commands` | Seus comandos: um `.md` em `~/.primocode/comandos/` (ou `<projeto>/.primocode/comandos/`) vira `/nome`, e `$ARGUMENTOS` recebe o que vem depois. Já vêm `/review`, `/explain` e `/ship`. `/commands novo <nome>` cria um |
| `/skills` · `/skills store` | 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í |
| `/perms 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` · `/attach` sem nada | Remove / lista anexos |
| `/attach <url>` | Anexa o texto de uma página ao próximo pedido (sem menu, rodapé e script). `@https://…` no meio do pedido faz o mesmo, só pra aquele pedido |
| `/help all` | Lista as 64 ferramentas que ele sabe usar, por grupo |
| `/placar` | Qual modelo grátis acerta mais em cada tipo de tarefa, aprendido neste computador (`/placar zerar` apaga) |
| `/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. `/undo lista` mostra os pedidos e quantos arquivos cada um mudou · `/undo N` volta os N últimos |
| `/redo` | Volta o que o último `/undo` desfez — enquanto nenhum pedido novo mexeu nos arquivos |
| `/check` | Acha sozinho como testar o projeto (os testes, senão o build, senão o lint) e responde em português: "Funcionou" ou "Não funcionou", com as linhas que explicam o erro. Se falhou, pergunta se a IA conserta. Se funcionou, marca o ponto como "funcionava" (aparece com ✓ no `/undo lista`) |
| `/restore` | Volta o projeto para o último ponto que o `/check` marcou como funcionando, desfazendo os pedidos feitos depois. Mostra o que vai mudar antes de confirmar, e o `/redo` ainda devolve |
| `/show` · `/show 30` · `/show parar` | Abre o app no celular de quem está no mesmo Wi-Fi, com um link que tem token e prazo (60 min, ou o que você disser). Não publica nada: o link morre no prazo ou quando o PrimoCode fecha, e `.env`, `.git` e `node_modules` nunca saem |
| `/howto` | Escreve (ou atualiza) o bloco "Como rodar" do `PRIMO.md`: instalar, abrir, conferir e mostrar, tirado do `package.json` ou da página, sem modelo. Rodar de novo troca o bloco, nunca duplica |
| `/rule` [texto \| tirar N] | Guarda uma regra ("nunca mexa no logo") no topo do `PRIMO.md`, que entra em todo pedido: ela não some quando a conversa é resumida. Sem texto, lista; `tirar N` tira uma. O `/init` reescreve o `PRIMO.md` e as regras voltam pro topo |
| `/port` | "O app não abre": diz qual porta o projeto declara (`package.json`, `vite.config`, a linha `PORT=` do `.env`, `server.js`), qual responde de verdade em `localhost` (com o título da página) e o endereço certo. Reconhece o AirPlay do Mac na 5000. O `/open` aponta pra ele quando não acha servidor |
| `/undo fora` | Quando o pedido cita arquivos ("arruma o `login.js`") e o agente mexe em outros, o fim do pedido diz quais. `/undo fora` volta só esses, e o que você pediu fica. Pedido que não cita arquivo não gera aviso |
| `/map` | O que tem no projeto, em português: as páginas, o estilo, a lógica e os dados, quem usa quem, e o arquivo que alguém pede e não existe (o `index.html` que puxa um `script.js` que nunca nasceu) |
| `/changes` | O que mudou no projeto, em português: arquivos novos, editados e apagados, e quantas linhas a mais e a menos (contra o último commit; fora do git, o último pedido) |
| `/timeline` | Abre no navegador a história do projeto: um cartão por pedido, com o que mudou, o selo "funcionava" e o comando pronto (`/undo N` ou `/restore`) pra voltar até ali. Também `/historia` |
| `/taste` · `/taste tirar N` | O seu gosto de motion: os estilos que você escolheu, os vídeos de referência (numerados) e pra onde isso inclina o próximo motion. `refazer` abre a tela de novo, `apagar` zera. `salvar <nome>` guarda o gosto de agora (um por cliente), `usar <nome>` troca, `estilos` lista. `força pouco/médio/muito` diz quanto as referências pesam, e `provar [assunto]` mostra o que o gosto muda em 30 motions, sem renderizar |
| `/taste referencias` | Abre a tela do gosto pra soltar os motions que você curtiu: o PrimoCode mede cada um (ritmo, movimento, cores, texto), mostra o que entendeu e você corrige antes de salvar |
| `/map 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 |
| `/open` sem nada | Abre o projeto atual no navegador: o servidor dele, se estiver de pé, ou a `index.html` (o `/open` sem nada faz o mesmo) |
| `/copy` | Copia a última resposta para a área de transferência (pbcopy, clip, wl-copy/xclip/xsel) |
| `/export` | Salva a conversa num `.md` em `~/primocode/conversas/`, pra guardar ou mandar pra alguém. Chave e senha saem trocadas por `[chave escondida]`, e não há link público |
| `/history [termo]` | Procura nos seus pedidos guardados nesta máquina (`~/.primocode/history.jsonl`), do mais recente. As conversas inteiras da conta ficam no `/chats` |
| `/doctor 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 |
| `/usage` | Primeiro em linguagem simples (quantas páginas a IA leu e escreveu, e quem paga: o plano ou a sua chave), depois os tokens por provedor (estimado em caracteres ÷ 4 quando o provedor não manda o número) |
| `/tasks` | O que roda em segundo plano (servidor de dev, watch), com o endereço · `/tasks rodar <cmd>` sobe algo sem travar · `/tasks abrir` abre no navegador · `/tasks parar <id>`. A barra mostra `● de pé :porta`, e ao sair nada fica órfão |
| `/keys` | 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 (`/perms 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/permission/perigo.js`.

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

## Arquitetura

```
┌────────────────┐   HTTPS/SSE    ┌───────────────────┐   HTTPS   ┌─────────────────────┐
│  primocode CLI │ ─────────────► │  primocode-server │ ────────► │ ZeroGPU · Gemini ·  │
│  (seu terminal)│ ◄───────────── │     (Railway)     │ ◄──────── │ Groq · HF · OpenRtr │
└────────────────┘                └───────────────────┘           └─────────────────────┘
     executa as tools                monta o prompt, a conta,     a corrente: se um modelo
     localmente                      os planos e a voz            recusa, o próximo atende
```

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.

### Um repositório, duas partes

| pasta | o que é | como sai |
|---|---|---|
| raiz (`bin/`, `lib/`, `skills/`, `studio/`, `voz/`) | o CLI `primocode` | `npm publish` (o `files` do `package.json` não leva o `server/`) |
| `server/` | o primocode-server: agente, conta Firebase, planos, voz, Estúdio | Railway, serviço `primocode-server`, pasta raiz `server`, em `https://primocode-server-production.up.railway.app` |

O `server/` veio do repositório `primocode-server` em 15/10/2026, com o histórico
inteiro (`git log -- server/`). As chaves ficam nas variáveis do Railway; o
`server/.env.example` diz quais são.

## Licença

MIT © ConectaPrimoAI