Skip to main content
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:

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:
Exemplo completo:
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

Exemplos

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

Exemplos

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

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

Modo Search/Replace

Modo Unified Diff

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

Exemplos

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

Flags

Exemplos

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

Flags

Exemplos

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

Exemplos

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

Exemplos

Mostra o diff dos arquivos modificados no repositório.

Flags

Exemplos

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

Flags

Exemplos

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

Flags

Exemplos

Lista as branches do repositório.

Flags

Exemplos

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

Flags

Exemplos

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


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

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