Plugin @coder - ChatCLI

O @coder e a suite de engenharia usada pelo Modo Coder (/coder). Ele fornece ações para ler/procurar arquivos, aplicar patches com segurança, rodar comandos e reverter alterações.

O @coder e um plugin builtin — já vem embutido no binario do ChatCLI e funciona imediatamente, sem instalação. Se precisar de uma versão customizada, basta colocar o binario em ~/.chatcli/plugins/ e ele prevalece sobre o builtin. Ao remove-lo, o builtin volta automaticamente no próximo /plugin reload.

Referência Rapida

Tabela com todos os subcomandos e suas flags mais usadas:

Subcomando	Descrição	Flags Principais
`read`	Le conteúdo de arquivo	`--file` (obrig.), `--start`, `--end`, `--head`, `--tail`
`write`	Escreve arquivo com backup	`--file` (obrig.), `--content` (obrig.), `--append`, `--encoding`
`patch`	Aplica search/replace ou diff unificado	`--file`, `--search`, `--replace`, `--diff`, `--encoding`
`multipatch`	Transação atômica de múltiplas edições search/replace em múltiplos arquivos. All-or-nothing rollback.	`--edits` (obrig., JSON array)
`tree`	Estrutura de diretorios	`--dir`, `--glob`, `--max-entries`
`outline`	Esqueleto de símbolos de um arquivo (declarações + linhas)	`--file` (obrig.)
`map`	Mapa estrutural do repositório com budget, arquivos ranqueados por estrutura	`--dir`, `--budget`
`search`	Busca full-text em arquivos	`--term` (obrig.), `--dir`, `--glob`, `--max-results`, `--context`
`exec`	Executa comandos no shell	`--cmd` (obrig.), `--command`
`test`	Roda testes	`--dir`, `--pattern`, `--timeout`
`git-status`	Status do repositório	(sem flags)
`git-diff`	Diferencas pendentes	`--file`, `--staged`
`git-log`	Histórico de commits	`--oneline`, `--limit`
`git-changed`	Arquivos alterados	`--staged`
`git-branch`	Lista branches	`--all`
`rollback`	Reverte arquivo de backup `.bak`	`--file` (obrig.)
`clean`	Remove arquivos `.bak`	(sem flags obrigatórias)
`checkpoint`	Snapshots shadow-git do workspace (automáticos antes de mutações)	`--list`, `--create`, `--restore`, `--label`

Formatos de Argumentos

O @coder aceita dois formatos de argumentos: JSON e CLI-style. Ambos são equivalentes.

Formato JSON (recomendado)
Formato CLI-style

O formato JSON e usado dentro do atributo args de um <tool_call>. A estrutura e:

{
  "cmd": "<subcomando>",
  "args": {
    "<flag>": "<valor>",
    ...
  }
}

Exemplo completo:

<tool_call name="@coder" args='{"cmd":"read","args":{"file":"main.go","start":10,"end":50}}'/>

O formato JSON e o recomendado porque evita problemas de escape e e o que os modelos de linguagem geram com mais consistencia.

Também e possível passar argumentos no estilo linha de comando, separados por espaco:

read --file main.go --start 10 --end 50

Neste caso, o campo cmd e a primeira palavra e as flags seguem no formato --flag valor.Exemplo em tool_call:

<tool_call name="@coder" args='{"cmd":"read --file main.go --start 10 --end 50"}'/>

No formato CLI-style, valores com espacos devem ser colocados entre aspas: --content "hello world".

Subcomandos — Referência Completa

read -- Ler Arquivos

Le o conteúdo de um arquivo do disco. Suporta leitura parcial por linhas e limite de bytes.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--file`	string	Sim	—	Caminho do arquivo a ser lido
`--start`	int	Não	—	Linha inicial (1-based)
`--end`	int	Não	—	Linha final (1-based)
`--head`	int	Não	—	Primeiras N linhas
`--tail`	int	Não	—	Ultimas N linhas
`--max-bytes`	int	Não	200000	Limite máximo de bytes na saída
`--encoding`	string	Não	`text`	Encoding da saida: `text` ou `base64`

Exemplos

JSON
CLI-style

<!-- Ler arquivo inteiro -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"README.md"}}'/>

<!-- Ler linhas 10 a 50 -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"main.go","start":10,"end":50}}'/>

<!-- Primeiras 20 linhas -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"config.yaml","head":20}}'/>

<!-- Ultimas 30 linhas -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"app.log","tail":30}}'/>

<!-- Saída em base64 (util para binarios) -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"image.png","encoding":"base64","max-bytes":500000}}'/>

read --file README.md
read --file main.go --start 10 --end 50
read --file config.yaml --head 20
read --file app.log --tail 30
read --file image.png --encoding base64 --max-bytes 500000

Use --head ou --tail para evitar saidas muito grandes. O --max-bytes (padrão 200KB) atua como limite de segurança mesmo quando não especificado.

write -- Escrever Arquivos

Escreve conteúdo em um arquivo. Cria automaticamente um backup .bak do arquivo existente antes de sobrescrever.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--file`	string	Sim	—	Caminho do arquivo a ser escrito
`--content`	string	Sim	—	Conteúdo a ser escrito
`--encoding`	string	Não	`text`	Encoding do conteúdo: `text` ou `base64`
`--append`	bool	Não	`false`	Se `true`, adiciona ao final do arquivo em vez de sobrescrever

Exemplos

JSON
CLI-style

<!-- Escrever arquivo novo (texto) -->
<tool_call name="@coder" args='{"cmd":"write","args":{"file":"hello.txt","content":"Hello, World!"}}'/>

<!-- Escrever com conteúdo em base64 -->
<tool_call name="@coder" args='{"cmd":"write","args":{"file":"data.bin","content":"SGVsbG8gV29ybGQ=","encoding":"base64"}}'/>

<!-- Adicionar ao final de um arquivo -->
<tool_call name="@coder" args='{"cmd":"write","args":{"file":"notes.txt","content":"\nNova linha adicionada","append":true}}'/>

write --file hello.txt --content "Hello, World!"
write --file data.bin --content "SGVsbG8gV29ybGQ=" --encoding base64
write --file notes.txt --content "Nova linha" --append

Use --encoding base64 para conteúdo que contenha caracteres especiais, quebras de linha complexas ou dados binarios. Isso evita problemas de escape no JSON.

Diagnósticos pós-edição. Após um write bem-sucedido (também patch e multipatch), o ChatCLI roda o language server nos arquivos tocados e anexa os achados ao resultado da tool como um bloco [DIAGNOSTICS] — então uma edição quebrada é pega imediatamente, no mesmo turno, em vez de turnos depois quando um teste falha. É silencioso em arquivos limpos, limitado a 5 arquivos / 3000 caracteres, e desligado com CHATCLI_CODER_AUTODIAG=off. Exige um language server disponível para a linguagem do arquivo (veja LSP Diagnostics).

patch -- Aplicar Patches

Aplica alterações a um arquivo existente. Suporta dois modos: search/replace (substitui um trecho específico) e unified diff (aplica um patch no formato diff).

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--file`	string	Condicional	—	Arquivo a ser patcheado. Obrigatório para search/replace; opcional para diff (o diff pode conter os caminhos)
`--search`	string	Condicional	—	Texto a ser encontrado (modo search/replace)
`--replace`	string	Condicional	—	Texto substituto (modo search/replace)
`--diff`	string	Condicional	—	Conteúdo de diff unificado (modo diff)
`--encoding`	string	Não	`text`	Encoding para `--search` e `--replace`: `text` ou `base64`
`--diff-encoding`	string	Não	`text`	Encoding para `--diff`: `text` ou `base64`

Você deve usar ou o modo search/replace (--search + --replace) ou o modo diff (--diff). Não combine os dois.

Modo Search/Replace

JSON
CLI-style

<!-- Substituir texto (plain text) -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"file":"main.go","search":"fmt.Println(\"old\")","replace":"fmt.Println(\"new\")"}}'/>

<!-- Substituir texto (base64 para evitar escape) -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"file":"main.go","search":"Zm10LlByaW50bG4oIm9sZCIp","replace":"Zm10LlByaW50bG4oIm5ldyIp","encoding":"base64"}}'/>

patch --file main.go --search "fmt.Println(\"old\")" --replace "fmt.Println(\"new\")"
patch --file main.go --search "base64str" --replace "base64str" --encoding base64

Modo Unified Diff

JSON
CLI-style

<!-- Aplicar diff em texto -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"diff":"--- a/main.go\n+++ b/main.go\n@@ -5,3 +5,3 @@\n-old line\n+new line"}}'/>

<!-- Aplicar diff em base64 -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"diff":"LS0tIGEvbWFpbi5nbw...","diff-encoding":"base64"}}'/>

patch --diff "--- a/main.go\n+++ b/main.go\n@@ -5,3 +5,3 @@\n-old\n+new"
patch --diff "base64content" --diff-encoding base64

O modo base64 e fortemente recomendado para patches, especialmente quando o conteúdo contem aspas, barras invertidas ou múltiplas linhas. Isso elimina problemas de escape no JSON.

tree -- Estrutura de Diretorios

Lista a estrutura de diretorios no formato arvore. Util para entender a organizacao do projeto.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--dir`	string	Não	`"."`	Diretório raiz para listar
`--glob`	string	Não	—	Padrão glob para filtrar arquivos (ex: `"*.go"`)
`--max-entries`	int	Não	2000	Número máximo de entradas retornadas

Exemplos

JSON
CLI-style

<!-- Listar diretório atual -->
<tool_call name="@coder" args='{"cmd":"tree","args":{"dir":"."}}'/>

<!-- Listar apenas arquivos Go -->
<tool_call name="@coder" args='{"cmd":"tree","args":{"dir":".","glob":"*.go"}}'/>

<!-- Listar subdiretorio com limite -->
<tool_call name="@coder" args='{"cmd":"tree","args":{"dir":"./internal","max-entries":500}}'/>

tree --dir .
tree --dir . --glob "*.go"
tree --dir ./internal --max-entries 500

search -- Busca Full-Text

Busca por um termo em todos os arquivos de um diretório. Retorna trechos com contexto ao redor.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--term`	string	Sim	—	Termo de busca
`--dir`	string	Não	`"."`	Diretório para buscar
`--glob`	string	Não	—	Padrão glob para filtrar arquivos (ex: `".go"`, `".ts"`)
`--max-results`	int	Não	100	Número máximo de resultados
`--context`	int	Não	2	Linhas de contexto antes e depois de cada match

Exemplos

JSON
CLI-style

<!-- Busca simples -->
<tool_call name="@coder" args='{"cmd":"search","args":{"term":"TODO","dir":"."}}'/>

<!-- Busca em arquivos Go com mais contexto -->
<tool_call name="@coder" args='{"cmd":"search","args":{"term":"func main","dir":".","glob":"*.go","context":5}}'/>

<!-- Busca com limite de resultados -->
<tool_call name="@coder" args='{"cmd":"search","args":{"term":"error","dir":"./pkg","max-results":20}}'/>

search --term "TODO" --dir .
search --term "func main" --dir . --glob "*.go" --context 5
search --term "error" --dir ./pkg --max-results 20

outline -- Esqueleto de Símbolos do Arquivo

Renderiza o esqueleto de símbolos de um arquivo — suas declarações com números de linha — para você entender a forma de um arquivo sem ler o arquivo inteiro. Para arquivos Go as assinaturas são exatas (analisadas com o go/ast do Go: funções com seu receiver, structs, interfaces, consts, vars); para Python, JS/TS/JSX, Java, Ruby, Rust, Kotlin, C# e PHP um outline baseado em padrões reconhece as formas de declaração comuns. Somente leitura.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--file`	string	Sim	—	Caminho do arquivo a ser esquematizado

Exemplos

JSON
CLI-style

<tool_call name="@coder" args='{"cmd":"outline","args":{"file":"cli/cli.go"}}'/>

outline --file cli/cli.go

Prefira outline a read quando você só precisa saber o que há em um arquivo (quais funções, tipos, métodos) e onde — custa uma fração dos tokens de ler o arquivo inteiro.

map -- Mapa Estrutural do Repositório

Renderiza um mapa estrutural com budget de caracteres de toda uma árvore: cada arquivo-fonte é esquematizado, os arquivos são ranqueados por quanta estrutura carregam, e seus esqueletos são impressos até o budget acabar — com nota explícita quando arquivos são omitidos. Ignora .git, node_modules, vendor, dist, build, arquivos ocultos e *_test.go. Somente leitura. Use para se orientar em uma codebase grande sem ler arquivos inteiros.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--dir`	string	Não	`"."`	Diretório raiz a mapear
`--budget`	int	Não	8000	Máximo de caracteres de estrutura a emitir

Exemplos

JSON
CLI-style

<!-- Mapear o projeto inteiro -->
<tool_call name="@coder" args='{"cmd":"map","args":{"dir":"."}}'/>

<!-- Mapear uma subárvore com budget maior -->
<tool_call name="@coder" args='{"cmd":"map","args":{"dir":"./cli","budget":16000}}'/>

map --dir . --budget 8000
map --dir ./cli --budget 16000

exec -- Executar Comandos

Executa um comando arbitrario no shell. Possui protecoes de segurança contra comandos destrutivos.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--cmd`	string	Sim	—	Comando a ser executado
`--command`	string	Não	—	Alias para `--cmd`

Exemplos

JSON
CLI-style

<!-- Executar comando simples -->
<tool_call name="@coder" args='{"cmd":"exec","args":{"cmd":"go build ./..."}}'/>

<!-- Listar processos -->
<tool_call name="@coder" args='{"cmd":"exec","args":{"cmd":"ps aux | grep myapp"}}'/>

<!-- Usando alias --command -->
<tool_call name="@coder" args='{"cmd":"exec","args":{"command":"ls -la"}}'/>

exec --cmd "go build ./..."
exec --cmd "ps aux | grep myapp"
exec --command "ls -la"

O exec bloqueia automaticamente comandos considerados perigosos, incluindo:

rm -rf / e variantes destrutivas
dd com alvos de disco
Fork bombs (ex: :(){ :|:& };:)
Outros padroes reconhecidamente destrutivos

Esses bloqueios existem para proteger o sistema. Use com responsabilidade.

test -- Rodar Testes

Executa testes do projeto automaticamente, detectando o framework conforme o diretório.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--dir`	string	Não	`"."`	Diretório onde rodar os testes
`--pattern`	string	Não	—	Padrão de arquivo de teste (ex: `"*_test.go"`)
`--timeout`	int	Não	30	Timeout em segundos

Exemplos

JSON
CLI-style

<!-- Rodar todos os testes -->
<tool_call name="@coder" args='{"cmd":"test","args":{"dir":"."}}'/>

<!-- Rodar testes com padrão específico -->
<tool_call name="@coder" args='{"cmd":"test","args":{"dir":"./pkg","pattern":"*_test.go","timeout":60}}'/>

test --dir .
test --dir ./pkg --pattern "*_test.go" --timeout 60

git-status -- Status do Repositório

Mostra o status do repositório Git (arquivos modificados, staged, untracked, etc.).Não requer flags.

Exemplos

JSON
CLI-style

<tool_call name="@coder" args='{"cmd":"git-status","args":{}}'/>

git-status

git-diff -- Diferencas Pendentes

Mostra o diff dos arquivos modificados no repositório.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--file`	string	Não	—	Filtrar diff por arquivo específico
`--staged`	bool	Não	`false`	Mostrar apenas alterações staged (prontas para commit)

Exemplos

JSON
CLI-style

<!-- Diff completo -->
<tool_call name="@coder" args='{"cmd":"git-diff","args":{}}'/>

<!-- Diff de um arquivo específico -->
<tool_call name="@coder" args='{"cmd":"git-diff","args":{"file":"main.go"}}'/>

<!-- Diff staged -->
<tool_call name="@coder" args='{"cmd":"git-diff","args":{"staged":true}}'/>

git-diff
git-diff --file main.go
git-diff --staged

git-log -- Histórico de Commits

Exibe o histórico de commits do repositório.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--oneline`	bool	Não	`false`	Formato compacto (uma linha por commit)
`--limit`	int	Não	10	Número máximo de commits exibidos

Exemplos

JSON
CLI-style

<!-- Ultimos 10 commits -->
<tool_call name="@coder" args='{"cmd":"git-log","args":{}}'/>

<!-- Ultimos 5 commits em formato compacto -->
<tool_call name="@coder" args='{"cmd":"git-log","args":{"oneline":true,"limit":5}}'/>

git-log
git-log --oneline --limit 5

git-changed -- Arquivos Alterados

Lista os arquivos alterados no repositório (similar a git diff --name-only).

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--staged`	bool	Não	`false`	Listar apenas arquivos staged

Exemplos

JSON
CLI-style

<!-- Todos os arquivos alterados -->
<tool_call name="@coder" args='{"cmd":"git-changed","args":{}}'/>

<!-- Apenas arquivos staged -->
<tool_call name="@coder" args='{"cmd":"git-changed","args":{"staged":true}}'/>

git-changed
git-changed --staged

git-branch -- Lista de Branches

Lista as branches do repositório.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--all`	bool	Não	`false`	Incluir branches remotas

Exemplos

JSON
CLI-style

<!-- Branches locais -->
<tool_call name="@coder" args='{"cmd":"git-branch","args":{}}'/>

<!-- Todas as branches (locais + remotas) -->
<tool_call name="@coder" args='{"cmd":"git-branch","args":{"all":true}}'/>

git-branch
git-branch --all

rollback -- Reverter Alterações

Restaura um arquivo a partir do seu backup .bak criado automaticamente pelo write ou patch.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--file`	string	Sim	—	Caminho do arquivo a ser restaurado

Exemplos

JSON
CLI-style

<tool_call name="@coder" args='{"cmd":"rollback","args":{"file":"main.go"}}'/>

rollback --file main.go

O rollback só funciona se existir um arquivo .bak correspondente. Os backups são criados automaticamente pelos comandos write e patch.

clean -- Remover Backups

Remove arquivos .bak criados pelo sistema de backup.Não possui flags obrigatórias.

Exemplos

JSON
CLI-style

<tool_call name="@coder" args='{"cmd":"clean","args":{}}'/>

clean

checkpoint -- Snapshots Shadow-git

Snapshots do workspace num repositório git sombra, uma rede de segurança mais forte que o rollback por .bak — cobre edições multi-arquivo e efeitos colaterais do exec, não apenas um arquivo.Um checkpoint é tirado automaticamente antes de todo subcomando mutante (write, patch, multipatch, exec). O snapshot vive num GIT_DIR separado sob ~/.chatcli/checkpoints/<hash> com o seu workspace como work tree, então o seu próprio .git nunca é tocado e o .gitignore do projeto é respeitado.

Flags

Flag	Tipo	Obrigatório	Default	Descrição
`--list`	bool	Não	(padrão)	Lista os snapshots, mais recentes primeiro
`--create`	bool	Não	`false`	Grava um snapshot agora
`--restore`	string	Não	—	Rebobina a árvore de trabalho para o snapshot com este hash
`--label`	string	Não	`manual`	Rótulo para um snapshot `--create`

Exemplos

JSON
CLI-style

<!-- Listar snapshots -->
<tool_call name="@coder" args='{"cmd":"checkpoint","args":{"list":true}}'/>

<!-- Gravar um agora -->
<tool_call name="@coder" args='{"cmd":"checkpoint","args":{"create":true,"label":"antes do refactor"}}'/>

<!-- Rebobinar para um snapshot -->
<tool_call name="@coder" args='{"cmd":"checkpoint","args":{"restore":"a1b2c3d"}}'/>

checkpoint --list
checkpoint --create --label "antes do refactor"
checkpoint --restore a1b2c3d

O --restore nunca apaga arquivos adicionados depois do snapshot; ele só rebobina o que o snapshot rastreava. Passa pelo gate de segurança; --list e --create são somente leitura.

Auto-snapshots são best-effort (falha de checkpoint nunca bloqueia a edição), throttled a no máximo um por 15 segundos (uma rajada de writes gera um checkpoint), um no-op quando o git não está instalado, e desligados por completo com CHATCLI_CODER_CHECKPOINTS=off.Eles também são limitados: workspaces amplos como o seu diretório home (ou qualquer diretório que o contenha) nunca recebem snapshot automático — hashear tanto disco congelaria todos os comandos — e cada snapshot roda sob um deadline rígido (10s automático, 60s para um checkpoint create explícito, sobrescrevível em segundos via CHATCLI_CODER_CHECKPOINT_TIMEOUT). Falhas repetidas de snapshot fazem backoff exponencial e, após três seguidas, desativam snapshots automáticos pelo resto da sessão com um aviso de uma linha.

Multipatch transacional

Quando uma refatoração precisa tocar vários arquivos como uma unidade (renomear identificador propagado por 5 arquivos, atualizar import em todos os consumidores, etc.), use multipatch em vez de uma cadeia de patch. O contrato:

Phase 1 — validação (sem escrita)

Para cada edição na ordem declarada, o engine carrega o arquivo, simula o search→replace em memória, e verifica que o search continua presente após edições anteriores ao mesmo arquivo. Falha em qualquer edição aborta a transação antes de qualquer escrita ao disco.

Phase 2 — commit

Snapshot de cada arquivo afetado em memória + escrita do conteúdo final. Falha em qualquer escrita restaura todos os arquivos a partir do snapshot.

Concorrência

Mutex por arquivo (chave: path absoluto), aquisição em ordem ordenada — duas transações que tocam o mesmo par de arquivos nunca deadlockam. Permissões do arquivo (chmod) são preservadas.

{
  "cmd": "multipatch",
  "args": {
    "edits": [
      {"file": "internal/auth/login.go", "search": "loginV1", "replace": "loginV2"},
      {"file": "internal/auth/login_test.go", "search": "loginV1", "replace": "loginV2"},
      {"file": "cmd/server/main.go", "search": "auth.loginV1", "replace": "auth.loginV2"}
    ]
  }
}

Cada edição aplica seu search→replace exatamente uma vez (strings.Replace com n=1). Para substituir múltiplas ocorrências no mesmo arquivo, declare múltiplas edições. O encoding base64 é suportado por-edição ("encoding":"base64") para payloads com bytes não-UTF8.

Sistema de Backup

O @coder implementa um sistema de backup automático para proteger contra alterações indesejadas.

Escrita ou Patch

Quando você executa write ou patch, o plugin verifica se o arquivo-alvo já existe.

Criacao do Backup

Se o arquivo existe, uma copia e salva com a extensao .bak (ex: main.go -> main.go.bak).

Aplicação da Alteracao

O conteúdo novo e escrito (ou o patch e aplicado) no arquivo original.

Rollback Disponível

A qualquer momento, você pode usar rollback --file main.go para restaurar a versão anterior a partir do .bak.

Limpeza

Use clean para remover todos os arquivos .bak quando não precisar mais dos backups.

O backup e sobrescrito a cada nova operação de write ou patch no mesmo arquivo. Se você fizer múltiplas alterações, apenas a versão imediatamente anterior estara disponível para rollback.

Validação de Caminhos e Segurança

O @coder aplica diversas validações de segurança em todos os caminhos de arquivo:

Limite de Workspace

Todos os caminhos são resolvidos relativamente ao diretório de trabalho (workspace). Tentativas de acessar arquivos fora do workspace são bloqueadas (ex: ../../etc/passwd).

Resolução de Symlinks

Symlinks são resolvidos antes da validação. Um symlink que aponte para fora do workspace será rejeitado, mesmo que o caminho aparente esteja dentro do diretório permitido.

Caminhos Sensiveis

Caminhos para arquivos sensiveis do sistema (ex: /etc/shadow, /etc/passwd) são bloqueados por padrão, impedindo leitura ou escrita.

Comandos Perigosos

O subcomando exec filtra padroes destrutivos conhecidos como rm -rf /, dd, fork bombs e outros. Esses comandos são rejeitados antes da execução.

Exemplo Completo de Uso (no /coder)

No modo /coder, o assistente responde com um bloco reasoning e em seguida um tool_call. O bloco é dimensionado pela tarefa: um pedido de um passo só (uma consulta, um comando, uma resposta) recebe uma linha e nenhuma lista de tarefas, enquanto qualquer coisa com dois ou mais passos recebe um plano numerado curto com marcas [✓] conforme avança. A regra mora no system prompt estável de propósito: decidir por query mudaria o prompt e reescreveria o prefixo cacheado. O mesmo prompt amarra afirmações a evidência: quando resultados de tools fundamentam a resposta, números, datas, prazos, regras e nomes de lugares específicos vêm só dessa evidência, e o que vem do conhecimento próprio do modelo é rotulado como não verificado ou estimativa na frase que o usa, nunca apresentado com a autoridade de uma fonte consultada. Aqui está um fluxo completo de engenharia:

<!-- 1. Entender a estrutura do projeto -->
<tool_call name="@coder" args='{"cmd":"tree","args":{"dir":".","glob":"*.go"}}'/>

<!-- 2. Buscar onde uma função e definida -->
<tool_call name="@coder" args='{"cmd":"search","args":{"term":"func HandleRequest","dir":".","glob":"*.go"}}'/>

<!-- 3. Ler o arquivo relevante -->
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"handler.go","start":15,"end":45}}'/>

<!-- 4. Aplicar uma correcao -->
<tool_call name="@coder" args='{"cmd":"patch","args":{"file":"handler.go","search":"return nil","replace":"return fmt.Errorf(\"missing parameter: %s\", name)"}}'/>

<!-- 5. Rodar os testes -->
<tool_call name="@coder" args='{"cmd":"test","args":{"dir":".","timeout":60}}'/>

<!-- 6. Verificar o que mudou -->
<tool_call name="@coder" args='{"cmd":"git-diff","args":{}}'/>

<!-- 7. Se algo deu errado, reverter -->
<tool_call name="@coder" args='{"cmd":"rollback","args":{"file":"handler.go"}}'/>

Recuperação de JSON e Parsing Robusto

O @coder inclui um sistema de recuperação de JSON que corrige automaticamente argumentos malformados gerados por LLMs:

7 Estrategias de Recovery

Aspas simples, chaves sem aspas, virgulas finais, plain string wrapping e mais. Veja Recuperação de JSON para detalhes.

Escaped Quotes em Shell

Tratamento melhorado de aspas escapadas em comandos shell, evitando falhas de parsing quando o modelo gera exec --cmd "echo \"hello\"".

Normalizacao de Aspas Unicode

Aspas curvas (tipograficas) sao convertidas automaticamente para aspas retas em arquivos de código, prevenindo erros de compilacao.

Execução Concorrente

Tool calls que operam em arquivos diferentes sao executadas em paralelo (file-scoped parallelization), acelerando operações de leitura e busca.

Notas Importantes

O @coder outorga poder de leitura/escrita em arquivos e execução de comandos, tudo passivel de rollback quando solicitado. Use em repositorios confiaveis.

Por ser builtin, o @coder aparece em /plugin list com a tag [builtin]. Não e possivel desinstala-lo via /plugin uninstall.

FAQ do Plugin @coder

O @coder aceita JSON em args?

Sim. O formato recomendado e JSON. Exemplo:

<tool_call name="@coder" args='{"cmd":"read","args":{"file":"README.md"}}'/>

Quando usar patch --diff vs --search/--replace?

Use --search/--replace para substituicoes simples e pontuais em um único local do arquivo. Use --diff quando precisar aplicar múltiplas alterações ao mesmo tempo ou quando a alteracao envolve adicao/remocao de linhas em diferentes trechos do arquivo. O diff pode ser codificado em text ou base64.

O exec e perigoso?

O @coder exec bloqueia padroes perigosos por padrão, como rm -rf /, dd em alvos de disco e fork bombs. A proteção e automática e não precisa ser configurada.

Existe limite de leitura?

Sim. O padrão e --max-bytes 200000 (200KB). Use também --head ou --tail para ler apenas partes do arquivo. Isso evita que saidas muito grandes sobrecarreguem o contexto do modelo.

O que acontece se eu fizer write duas vezes no mesmo arquivo?

O backup .bak e sobrescrito a cada operação. Apenas a versão imediatamente anterior a ultima escrita estara disponível para rollback. Se precisar de histórico completo, use git para gerenciar versões.

Posso usar @coder fora do modo /coder?

Sim. O plugin @coder pode ser invocado em qualquer modo que suporte tool_calls. O modo /coder simplesmente configura o system prompt para guiar o modelo a usar @coder como ferramenta principal.

Como substituir o @coder builtin por uma versão customizada?

Coloque um binario com o mesmo nome no diretório ~/.chatcli/plugins/. Ele prevalecera sobre o builtin. Para voltar ao builtin, remova o binario customizado e execute /plugin reload.

O --encoding base64 e necessário?

Não e obrigatório, mas e fortemente recomendado para write e patch quando o conteúdo contem caracteres especiais, aspas, barras invertidas ou múltiplas linhas. O base64 elimina completamente problemas de escape no JSON.

Próximos passos

Modo Coder

Como /coder orquestra @coder num loop ReAct completo.

Coder Security

Policies, allowlist e governança de execução.

Enhanced Permissions

40+ patterns de imunidade e 90+ allowlist read-only.

JSON Recovery

7 estratégias para recuperar JSON malformado em tool calls.

File Staleness

Rastreio mtime + SHA-256 entre read/write para evitar conflitos.

Cookbook: Corrigir testes

Receita prática usando @coder para consertar testes autônomamente.

​Referência Rapida

​Formatos de Argumentos

​Subcomandos — Referência Completa

​Flags

​Exemplos

​Flags

​Exemplos

​Flags

​Modo Search/Replace

​Modo Unified Diff

​Flags

​Exemplos

​Flags

​Exemplos

​Flags

​Exemplos

​Flags

​Exemplos

​Flags

​Exemplos

​Flags

​Exemplos

​Exemplos

​Flags

​Exemplos

​Flags

​Exemplos

​Flags

​Exemplos

​Flags

​Exemplos

​Flags

​Exemplos

​Exemplos

​Flags

​Exemplos

​Multipatch transacional

​Sistema de Backup

​Validação de Caminhos e Segurança

Limite de Workspace

Resolução de Symlinks

Caminhos Sensiveis

Comandos Perigosos

​Exemplo Completo de Uso (no /coder)

​Recuperação de JSON e Parsing Robusto

7 Estrategias de Recovery

Escaped Quotes em Shell

Normalizacao de Aspas Unicode

Execução Concorrente

​Notas Importantes

​FAQ do Plugin @coder

​Próximos passos

Modo Coder

Coder Security

Enhanced Permissions

JSON Recovery

File Staleness

Cookbook: Corrigir testes

Referência Rapida

Formatos de Argumentos

Subcomandos — Referência Completa

Flags

Exemplos

Flags

Exemplos

Flags

Modo Search/Replace

Modo Unified Diff

Flags

Exemplos

Flags

Exemplos

Flags

Exemplos

Flags

Exemplos

Flags

Exemplos

Flags

Exemplos

Exemplos

Flags

Exemplos

Flags

Exemplos

Flags

Exemplos

Flags

Exemplos

Flags

Exemplos

Exemplos

Flags

Exemplos

Multipatch transacional

Sistema de Backup

Validação de Caminhos e Segurança

Exemplo Completo de Uso (no /coder)

Recuperação de JSON e Parsing Robusto

Notas Importantes

FAQ do Plugin @coder

Próximos passos