# PrimoCode v8.42.2

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.

**Sem chave de API sua.** O modelo vem hospedado: você entra com a conta do
Conecta Primo AI (plano **Premium** ou **Super**) e usa — nada de console de
provedor, nada de teto de gasto para acompanhar. Quem preferir a própria chave
do Claude ou do GPT escolhe isso na abertura, com as setinhas, e passa a usar a
assinatura dele.

```
 ▐▛███▜▌   Primo Code v8.42.2
▝▜█████▛▘  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`.

## 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** | Claude Opus 5, Sonnet 5 e Haiku 4.5 via OpenRouter — trocáveis com `/model` | 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.**

## Vídeo e apresentação: o diretor entra antes da produção

Quando o pedido é de vídeo, reels, teaser ou apresentação narrada, o PrimoCode
não sai montando cena: ele chama primeiro o **diretor** — uma IA que só
estrutura. Ela devolve o roteiro cena a cena com a **narração escrita para ser
falada**, a duração, a transição, o movimento de cada cena, a voz (perfil e
instrução de leitura) e a lista de imagens, logos e música a buscar. Só depois
disso a produção começa, e ela segue a pauta em vez de inventar.

A mídia é de verdade: foto com licença aberta (Openverse), logo em SVG da marca
(Wikimedia Commons) e, com chave própria, a busca de imagens do Google pela API
oficial. Música e efeito sonoro vêm do `buscar_audio`, que baixa e já traz o
crédito; a identidade de uma empresa — logo, cor, paleta, fontes e frase — o
`marca_da_empresa` lê do site dela. Tudo o que desce guarda a licença ao lado do
arquivo, e os créditos saem prontos para a cena final. Recorte de fundo com
`rembg`, quando instalado.

O quadro também se move: cada cena aceita uma **câmera** (`aproximar`,
`empurrar`, `pan-direita`, `balanco`…) e cada elemento uma **profundidade**, e
aí as camadas andam em velocidades diferentes — é o que separa motion de slide
animado. Junto com as chaves em 3D, as curvas com nome e o som por elemento,
dá para montar no navegador o que antes pedia After Effects.

O motor não é gosto: vídeo curto sai pelo estúdio, em segundos, sem instalar
nada; vídeo longo, canal alfa, ProRes ou fps alto viram projeto **Remotion** na
sua pasta — e a resposta sempre diz por que escolheu.

## Instalação

**macOS / Linux / WSL** — um comando, e ele resolve tudo (inclusive instalar o Node, se faltar):

```bash
curl -fsSL https://raw.githubusercontent.com/ConectaPrimoAI/primocode/main/install.sh | bash
```

**Windows** — baixe o repositório e rode:

```cmd
install.cmd
```

Já tem Node 18.17+? Então basta:

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

Requer **Node.js 18.17+**. O CLI não tem dependências — só a stdlib do Node, por isso instala em segundos.

### 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)

## 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
```

## Comandos

| Comando | Descrição |
|---|---|
| `/dir <caminho>` | Trabalha numa pasta que já existe, onde você quiser |
| `/project` | Lista projetos. `/project <nome>` cria em `~/primocode` |
| `/mode primocode\|chat\|auto` | Alterna o modo (fica guardado) |
| `/model top\|main\|fast` | **Todos grátis.** top = o mais capaz (550B, 1M de contexto), main = agente de código (padrão), fast = o mais rápido. Aceita qualquer ID do OpenRouter |
| `/attach <arquivo>` | Anexa arquivo ao próximo pedido |
| `/detach` · `/files` | Remove / lista anexos |
| `/tudo` | Lista as 44 ferramentas que ele sabe usar, por grupo |
| `/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 |
| `/status` | Health check do servidor |
| `/name <nome>` | Como o Primo te chama na saudação |
| `/mascot primo\|fox\|cat` | Escolhe o mascote (mostra os três) |
| `/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.onrender.com",
  "model": "main",
  "token": null
}
```

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

```bash
export PRIMOCODE_SERVER="https://primocode-server.onrender.com"
export PRIMOCODE_MODEL="main"
export PRIMOCODE_TOKEN="..."   # só se o servidor exigir
```

## Segurança

Todo caminho que o modelo pede é resolvido **dentro** da pasta do projeto.
Caminho absoluto ou com `../` é recusado — o agente não escreve fora da sua
área de trabalho.

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