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

# Git Forge (@forge)

> Pull requests, issues e CI através do gh/glab que VOCÊ já autenticou — leia os checks de um PR, puxe os logs do run que falhou, comente e abra PRs, sem sair do agente. Keyless: o ChatCLI nunca guarda credenciais de forge.

O tool **`@forge`** traz o seu Git forge para dentro do loop do agente. Ele roda operações de pull request, issue e CI através da CLI **que você já autenticou** — [`gh`](https://cli.github.com) para GitHub, [`glab`](https://gitlab.com/gitlab-org/cli) para GitLab — para que o agente feche o ciclo diário **`branch → PR → observar CI → corrigir`** sem você trocar de janela.

<Info>
  O `@forge` é **keyless por design**. O ChatCLI nunca guarda um token de forge: ele delega para o binário `gh`/`glab` no qual o usuário fez login (`gh auth login` / `glab auth login`). O que essas CLIs conseguem fazer com a sua conta, o `@forge` consegue — nada mais, nada menos.
</Info>

<Tip>
  O uso típico é depurar um PR vermelho: `@forge pr-checks 42` mostra quais checks falharam, `@forge ci-logs <run-id>` puxa **apenas os logs dos steps que falharam**, o agente corrige o código, e `@forge pr-comment 42 --body "…"` reporta de volta.
</Tip>

***

## Pré-requisitos

O `@forge` precisa da CLI oficial do forge instalada e autenticada na sua máquina:

<Steps>
  <Step title="Instale a CLI">
    GitHub: instale o [`gh`](https://cli.github.com). GitLab: instale o [`glab`](https://gitlab.com/gitlab-org/cli). Qualquer uma basta — o `@forge` escolhe a certa automaticamente (veja abaixo).
  </Step>

  <Step title="Autentique uma vez">
    ```bash theme={"system"}
    gh auth login      # GitHub
    glab auth login    # GitLab
    ```

    O ChatCLI reaproveita essa sessão. Não há nada para configurar dentro do ChatCLI e nenhum token para colar.
  </Step>

  <Step title="Rode dentro de um repositório">
    O `@forge` lê o remote `origin` para decidir GitHub vs GitLab, então rode o agente a partir de um repo clonado (ou passe `host` explicitamente).
  </Step>
</Steps>

***

## Uso

```text theme={"system"}
<tool_call name="@forge" args='{"cmd":"pr-checks","args":{"number":42}}' />
<tool_call name="@forge" args='{"cmd":"ci-logs","args":{"run":123456}}' />
<tool_call name="@forge" args='{"cmd":"pr-comment","args":{"number":42,"body":"CI está verde agora — o teste flaky foi re-seedado."}}' />
```

Tanto o envelope JSON `{cmd, args}` quanto a forma argv plana são aceitos, e a grafia em dois tokens dobra no comando canônico — `pr view 42` é o mesmo que `pr-view 42`.

### Subcomandos

| Subcomando      | O que faz                                                                           | Gate              |
| :-------------- | :---------------------------------------------------------------------------------- | :---------------- |
| `pr-list`       | Pull requests abertos (`--limit N`)                                                 | read-only         |
| `pr-view`       | Um PR: título, corpo, estado, reviews (`{number}`)                                  | read-only         |
| `pr-diff`       | O diff do PR, com limite (`{number}`)                                               | read-only         |
| `pr-checks`     | Status dos checks de CI do PR (`{number}`)                                          | read-only         |
| `pr-create`     | Abre um PR a partir da branch atual (`--title` obr., `--body`, `--base`, `--draft`) | **security gate** |
| `pr-comment`    | Comenta em um PR (`{number}`, `--body` obr.)                                        | **security gate** |
| `issue-list`    | Issues abertas (`--limit N`)                                                        | read-only         |
| `issue-view`    | Uma issue com sua discussão (`{number}`)                                            | read-only         |
| `issue-comment` | Comenta em uma issue (`{number}`, `--body` obr.)                                    | **security gate** |
| `ci-status`     | Últimos runs de workflow (`--branch BR`, branch atual por default)                  | read-only         |
| `ci-logs`       | Os logs dos **steps que falharam** de um run (`{run-id}`)                           | read-only         |
| `detect`        | Qual CLI de forge seria usada, e por quê                                            | read-only         |

***

## GitHub ou GitLab — decidido por você

O `@forge` escolhe o backend automaticamente:

<Steps>
  <Step title="Host explícito vence">
    Passe `{"host":"github"}` ou `{"host":"gitlab"}` para forçar `gh` ou `glab` naquela chamada.
  </Step>

  <Step title="Senão, o remote git decide">
    Um remote `origin` apontando para uma URL do **GitLab** roteia para `glab`; qualquer outra coisa cai no default `gh` (GitHub).
  </Step>
</Steps>

A superfície de comandos é idêntica nos dois — o `@forge` mapeia o vocabulário do GitLab para você: um **PR** vira um **merge request** (`pr-*` → `mr`), um **comentário** vira uma **note**, e `--base` vira `--target-branch`. Você escreve um único conjunto de comandos; a CLI certa roda por baixo.

```text theme={"system"}
<tool_call name="@forge" args='{"cmd":"detect"}' />
→ Forge CLI: glab (origin remote is a GitLab URL)
```

***

## Exemplo prático: corrigindo um PR vermelho sem sair do agente

```text theme={"system"}
# 1. Quais checks falharam no PR 42?
<tool_call name="@forge" args='{"cmd":"pr-checks","args":{"number":42}}' />
→ ✓ lint   ✗ test (run 987654)   ✓ build

# 2. Leia SÓ os steps que falharam do run que falhou
<tool_call name="@forge" args='{"cmd":"ci-logs","args":{"run":987654}}' />
→ FAIL TestPricing/glm-5.3 … expected 0.15 got 0

# 3. …o agente corrige o código com @coder, re-roda os testes…

# 4. Reporta de volta no PR
<tool_call name="@forge" args='{"cmd":"pr-comment","args":{"number":42,"body":"Corrigido: a tabela de preços não tinha o tier glm-5.3-flash. Enviado 3f0a1c2."}}' />
```

O mesmo fluxo funciona em merge requests do GitLab sem mudança — só a CLI por baixo difere.

***

## Segurança

* **Leituras são auto-aprovadas.** `pr-list`, `pr-view`, `pr-diff`, `pr-checks`, `issue-list`, `issue-view`, `ci-status`, `ci-logs` e `detect` só observam o estado do forge, então rodam sem prompt de confirmação e podem ser paralelizadas.
* **Mutações passam pelo [security gate](/pt/features/coder-security).** `pr-create`, `pr-comment` e `issue-comment` mudam o que outras pessoas veem, então passam pela mesma política de confirmação de qualquer outra tool call com efeito colateral — você (ou sua política) aprova cada uma.
* Nada é escalado silenciosamente: argumentos imparseáveis falham fechados (tratados como *não* read-only), e o tool nunca inventa um token — ele só faz o que o seu `gh`/`glab` logado consegue.

<Note>
  A saída do `@forge` tem limite para impedir que diffs grandes de PR e logs de CI inundem o contexto. Para um diff completo, o agente pode recorrer ao `@coder git-diff` numa branch com checkout.
</Note>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Plugins Agênticos" icon="plug" href="/pt/features/agentic-plugins">
    O catálogo completo de tools builtin e como o agente as usa.
  </Card>

  <Card title="Segurança do Coder Mode" icon="shield-halved" href="/pt/features/coder-security">
    Como o security gate arbitra tool calls que mutam estado.
  </Card>
</CardGroup>