Pular para o conteúdo principal
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:
SubcomandoDescriçãoFlags Principais
readLe conteúdo de arquivo--file (obrig.), --start, --end, --head, --tail
writeEscreve arquivo com backup--file (obrig.), --content (obrig.), --append, --encoding
patchAplica search/replace ou diff unificado--file, --search, --replace, --diff, --encoding
multipatchTransação atômica de múltiplas edições search/replace em múltiplos arquivos. All-or-nothing rollback.--edits (obrig., JSON array)
treeEstrutura de diretorios--dir, --glob, --max-entries
searchBusca full-text em arquivos--term (obrig.), --dir, --glob, --max-results, --context
execExecuta comandos no shell--cmd (obrig.), --command
testRoda testes--dir, --pattern, --timeout
git-statusStatus do repositório(sem flags)
git-diffDiferencas pendentes--file, --staged
git-logHistórico de commits--oneline, --limit
git-changedArquivos alterados--staged
git-branchLista branches--all
rollbackReverte arquivo de backup .bak--file (obrig.)
cleanRemove arquivos .bak(sem flags obrigatórias)

​
Formatos de Argumentos

O @coder aceita dois formatos de argumentos: JSON e CLI-style. Ambos são equivalentes.
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.

​
Subcomandos — Referência Completa

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

​
Flags

FlagTipoObrigatórioDefaultDescrição
--filestringSim—Caminho do arquivo a ser lido
--startintNão—Linha inicial (1-based)
--endintNão—Linha final (1-based)
--headintNão—Primeiras N linhas
--tailintNão—Ultimas N linhas
--max-bytesintNão200000Limite máximo de bytes na saída
--encodingstringNãotextEncoding da saida: text ou base64

​
Exemplos

<!-- 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}}'/>
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.
Escreve conteúdo em um arquivo. Cria automaticamente um backup .bak do arquivo existente antes de sobrescrever.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--filestringSim—Caminho do arquivo a ser escrito
--contentstringSim—Conteúdo a ser escrito
--encodingstringNãotextEncoding do conteúdo: text ou base64
--appendboolNãofalseSe true, adiciona ao final do arquivo em vez de sobrescrever

​
Exemplos

<!-- 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}}'/>
Use --encoding base64 para conteúdo que contenha caracteres especiais, quebras de linha complexas ou dados binarios. Isso evita problemas de escape no JSON.
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

FlagTipoObrigatórioDefaultDescrição
--filestringCondicional—Arquivo a ser patcheado. Obrigatório para search/replace; opcional para diff (o diff pode conter os caminhos)
--searchstringCondicional—Texto a ser encontrado (modo search/replace)
--replacestringCondicional—Texto substituto (modo search/replace)
--diffstringCondicional—Conteúdo de diff unificado (modo diff)
--encodingstringNãotextEncoding para --search e --replace: text ou base64
--diff-encodingstringNãotextEncoding 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

<!-- 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"}}'/>

​
Modo Unified Diff

<!-- 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"}}'/>
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.
Lista a estrutura de diretorios no formato arvore. Util para entender a organizacao do projeto.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--dirstringNão"."Diretório raiz para listar
--globstringNão—Padrão glob para filtrar arquivos (ex: "*.go")
--max-entriesintNão2000Número máximo de entradas retornadas

​
Exemplos

<!-- 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}}'/>
Busca por um termo em todos os arquivos de um diretório. Retorna trechos com contexto ao redor.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--termstringSim—Termo de busca
--dirstringNão"."Diretório para buscar
--globstringNão—Padrão glob para filtrar arquivos (ex: "*.go", "*.ts")
--max-resultsintNão100Número máximo de resultados
--contextintNão2Linhas de contexto antes e depois de cada match

​
Exemplos

<!-- 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}}'/>
Executa um comando arbitrario no shell. Possui protecoes de segurança contra comandos destrutivos.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--cmdstringSim—Comando a ser executado
--commandstringNão—Alias para --cmd

​
Exemplos

<!-- 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"}}'/>
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.
Executa testes do projeto automaticamente, detectando o framework conforme o diretório.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--dirstringNão"."Diretório onde rodar os testes
--patternstringNão—Padrão de arquivo de teste (ex: "*_test.go")
--timeoutintNão30Timeout em segundos

​
Exemplos

<!-- 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}}'/>
Mostra o status do repositório Git (arquivos modificados, staged, untracked, etc.).Não requer flags.

​
Exemplos

<tool_call name="@coder" args='{"cmd":"git-status","args":{}}'/>
Mostra o diff dos arquivos modificados no repositório.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--filestringNão—Filtrar diff por arquivo específico
--stagedboolNãofalseMostrar apenas alterações staged (prontas para commit)

​
Exemplos

<!-- 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}}'/>
Exibe o histórico de commits do repositório.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--onelineboolNãofalseFormato compacto (uma linha por commit)
--limitintNão10Número máximo de commits exibidos

​
Exemplos

<!-- 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}}'/>
Lista os arquivos alterados no repositório (similar a git diff --name-only).

​
Flags

FlagTipoObrigatórioDefaultDescrição
--stagedboolNãofalseListar apenas arquivos staged

​
Exemplos

<!-- 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}}'/>
Lista as branches do repositório.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--allboolNãofalseIncluir branches remotas

​
Exemplos

<!-- 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}}'/>
Restaura um arquivo a partir do seu backup .bak criado automaticamente pelo write ou patch.

​
Flags

FlagTipoObrigatórioDefaultDescrição
--filestringSim—Caminho do arquivo a ser restaurado

​
Exemplos

<tool_call name="@coder" args='{"cmd":"rollback","args":{"file":"main.go"}}'/>
O rollback só funciona se existir um arquivo .bak correspondente. Os backups são criados automaticamente pelos comandos write e patch.
Remove arquivos .bak criados pelo sistema de backup.Não possui flags obrigatórias.

​
Exemplos

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

​
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:
1

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.
2

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.
3

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.
1

Escrita ou Patch

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

Criacao do Backup

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

Aplicação da Alteracao

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

Rollback Disponível

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

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

Sim. O formato recomendado e JSON. Exemplo:
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"README.md"}}'/>
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 @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.
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 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.
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.
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.
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.