> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin @coder

> Ferramenta de engenharia builtin para ler, editar, patchar e executar tarefas com rollback.

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

<Info>
  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`.
</Info>

***

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

***

## Formatos de Argumentos

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

<Tabs>
  <Tab title="Formato JSON (recomendado)">
    O formato JSON e usado dentro do atributo `args` de um `<tool_call>`. A estrutura e:

    ```json theme={"system"}
    {
      "cmd": "<subcomando>",
      "args": {
        "<flag>": "<valor>",
        ...
      }
    }
    ```

    Exemplo completo:

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

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

  <Tab title="Formato CLI-style">
    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:

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

    <Note>
      No formato CLI-style, valores com espacos devem ser colocados entre aspas: `--content "hello world"`.
    </Note>
  </Tab>
</Tabs>

***

## Subcomandos -- Referência Completa

<AccordionGroup>
  <Accordion title="read -- Ler Arquivos" icon="file-lines">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        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
        ```
      </Tab>
    </Tabs>

    <Tip>
      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.
    </Tip>
  </Accordion>

  <Accordion title="write -- Escrever Arquivos" icon="pen">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        write --file hello.txt --content "Hello, World!"
        write --file data.bin --content "SGVsbG8gV29ybGQ=" --encoding base64
        write --file notes.txt --content "Nova linha" --append
        ```
      </Tab>
    </Tabs>

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

  <Accordion title="patch -- Aplicar Patches" icon="code-compare">
    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`                                                                    |

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

    ### Modo Search/Replace

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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"}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        patch --file main.go --search "fmt.Println(\"old\")" --replace "fmt.Println(\"new\")"
        patch --file main.go --search "base64str" --replace "base64str" --encoding base64
        ```
      </Tab>
    </Tabs>

    ### Modo Unified Diff

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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"}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        patch --diff "--- a/main.go\n+++ b/main.go\n@@ -5,3 +5,3 @@\n-old\n+new"
        patch --diff "base64content" --diff-encoding base64
        ```
      </Tab>
    </Tabs>

    <Tip>
      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.
    </Tip>
  </Accordion>

  <Accordion title="tree -- Estrutura de Diretorios" icon="folder-tree">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        tree --dir .
        tree --dir . --glob "*.go"
        tree --dir ./internal --max-entries 500
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="search -- Busca Full-Text" icon="magnifying-glass">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        search --term "TODO" --dir .
        search --term "func main" --dir . --glob "*.go" --context 5
        search --term "error" --dir ./pkg --max-results 20
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="exec -- Executar Comandos" icon="terminal">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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"}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        exec --cmd "go build ./..."
        exec --cmd "ps aux | grep myapp"
        exec --command "ls -la"
        ```
      </Tab>
    </Tabs>

    <Warning>
      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.
    </Warning>
  </Accordion>

  <Accordion title="test -- Rodar Testes" icon="vial">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        test --dir .
        test --dir ./pkg --pattern "*_test.go" --timeout 60
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="git-status -- Status do Repositório" icon="code-branch">
    Mostra o status do repositório Git (arquivos modificados, staged, untracked, etc.).

    **Não requer flags.**

    ### Exemplos

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <tool_call name="@coder" args='{"cmd":"git-status","args":{}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        git-status
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="git-diff -- Diferencas Pendentes" icon="code-compare">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        git-diff
        git-diff --file main.go
        git-diff --staged
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="git-log -- Histórico de Commits" icon="clock-rotate-left">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        git-log
        git-log --oneline --limit 5
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="git-changed -- Arquivos Alterados" icon="file-pen">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        git-changed
        git-changed --staged
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="git-branch -- Lista de Branches" icon="code-branch">
    Lista as branches do repositório.

    ### Flags

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

    ### Exemplos

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <!-- 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}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        git-branch
        git-branch --all
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="rollback -- Reverter Alterações" icon="rotate-left">
    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

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <tool_call name="@coder" args='{"cmd":"rollback","args":{"file":"main.go"}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        rollback --file main.go
        ```
      </Tab>
    </Tabs>

    <Note>
      O `rollback` só funciona se existir um arquivo `.bak` correspondente. Os backups são criados automaticamente pelos comandos `write` e `patch`.
    </Note>
  </Accordion>

  <Accordion title="clean -- Remover Backups" icon="broom">
    Remove arquivos `.bak` criados pelo sistema de backup.

    **Não possui flags obrigatórias.**

    ### Exemplos

    <Tabs>
      <Tab title="JSON">
        ```xml theme={"system"}
        <tool_call name="@coder" args='{"cmd":"clean","args":{}}'/>
        ```
      </Tab>

      <Tab title="CLI-style">
        ```
        clean
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

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

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

```json theme={"system"}
{
  "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"}
    ]
  }
}
```

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

***

## Sistema de Backup

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

<Steps>
  <Step title="Escrita ou Patch">
    Quando você executa `write` ou `patch`, o plugin verifica se o arquivo-alvo já existe.
  </Step>

  <Step title="Criacao do Backup">
    Se o arquivo existe, uma copia e salva com a extensao `.bak` (ex: `main.go` -> `main.go.bak`).
  </Step>

  <Step title="Aplicação da Alteracao">
    O conteúdo novo e escrito (ou o patch e aplicado) no arquivo original.
  </Step>

  <Step title="Rollback Disponível">
    A qualquer momento, você pode usar `rollback --file main.go` para restaurar a versão anterior a partir do `.bak`.
  </Step>

  <Step title="Limpeza">
    Use `clean` para remover todos os arquivos `.bak` quando não precisar mais dos backups.
  </Step>
</Steps>

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

***

## Validação de Caminhos e Segurança

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

<CardGroup cols={2}>
  <Card title="Limite de Workspace" icon="shield">
    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`).
  </Card>

  <Card title="Resolução de Symlinks" icon="link">
    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.
  </Card>

  <Card title="Caminhos Sensiveis" icon="lock">
    Caminhos para arquivos sensiveis do sistema (ex: `/etc/shadow`, `/etc/passwd`) são bloqueados por padrão, impedindo leitura ou escrita.
  </Card>

  <Card title="Comandos Perigosos" icon="triangle-exclamation">
    O subcomando `exec` filtra padroes destrutivos conhecidos como `rm -rf /`, `dd`, fork bombs e outros. Esses comandos são rejeitados antes da execução.
  </Card>
</CardGroup>

***

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

```xml theme={"system"}
<!-- 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:

<CardGroup cols={2}>
  <Card title="7 Estrategias de Recovery" icon="screwdriver-wrench">
    Aspas simples, chaves sem aspas, virgulas finais, plain string wrapping e mais. Veja [Recuperação de JSON](/pt/features/json-recovery) para detalhes.
  </Card>

  <Card title="Escaped Quotes em Shell" icon="terminal">
    Tratamento melhorado de aspas escapadas em comandos shell, evitando falhas de parsing quando o modelo gera `exec --cmd "echo \"hello\""`.
  </Card>

  <Card title="Normalizacao de Aspas Unicode" icon="font">
    Aspas curvas (tipograficas) sao convertidas automaticamente para aspas retas em arquivos de código, prevenindo erros de compilacao.
  </Card>

  <Card title="Execução Concorrente" icon="arrows-split-up-and-left">
    Tool calls que operam em arquivos diferentes sao executadas em paralelo (file-scoped parallelization), acelerando operações de leitura e busca.
  </Card>
</CardGroup>

***

## Notas Importantes

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

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

***

## FAQ do Plugin @coder

<AccordionGroup>
  <Accordion title="O @coder aceita JSON em args?">
    Sim. O formato recomendado e JSON. Exemplo:

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

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Modo Coder" icon="code" href="/pt/core-concepts/coder-mode">
    Como `/coder` orquestra `@coder` num loop ReAct completo.
  </Card>

  <Card title="Coder Security" icon="shield-halved" href="/pt/features/coder-security">
    Policies, allowlist e governança de execução.
  </Card>

  <Card title="Enhanced Permissions" icon="shield-alert" href="/pt/features/enhanced-permissions">
    40+ patterns de imunidade e 90+ allowlist read-only.
  </Card>

  <Card title="JSON Recovery" icon="wrench" href="/pt/features/json-recovery">
    7 estratégias para recuperar JSON malformado em tool calls.
  </Card>

  <Card title="File Staleness" icon="clock-rotate-left" href="/pt/features/file-staleness">
    Rastreio mtime + SHA-256 entre read/write para evitar conflitos.
  </Card>

  <Card title="Cookbook: Corrigir testes" icon="vial" href="/pt/cookbook/coder-fix-tests">
    Receita prática usando `@coder` para consertar testes autônomamente.
  </Card>
</CardGroup>