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

# ACP — ChatCLI dentro da sua IDE

> chatcli acp transforma o ChatCLI num agente nativo de IDE via Agent Client Protocol: IDEs JetBrains e Zed dirigem os engines reais de chat/agent/coder com tool calls estruturadas, plano ao vivo, slash commands e dialogs nativos de permissão — sem emulação de terminal, sem output raspado.

O **Agent Client Protocol (ACP)** é um protocolo aberto que permite a editores e IDEs hospedar agentes de código externos como cidadãos de primeira classe: a IDE renderiza nativamente o raciocínio, as tool calls, o plano e os pedidos de permissão do agente, enquanto o agente roda como um processo separado falando JSON-RPC via stdio.

`chatcli acp` é o servidor ACP do ChatCLI. Tudo que você configurou no ChatCLI — providers, modelos, memória, contextos, skills, plugins, servidores MCP — passa a dirigir o chat de IA da sua IDE.

<Info>
  O que a IDE renderiza nos runs de agent/coder é totalmente **estruturado** — não um transcript de terminal em stream:

  * **Raciocínio** — chega como thought chunks nativos (colapsáveis na maioria dos clientes).
  * **Tool calls** — cada ação é uma tool call de primeira classe com título humano ("Reading: main.go"), kind semântico (read, edit, execute, search…), status ao vivo e os arquivos tocados. Leituras bem-sucedidas mostram *qual* arquivo foi lido — nunca um despejo do conteúdo no chat.
  * **Plano** — a lista de tarefas do coder vira um painel de plano ao vivo, marcado conforme o agente progride.
  * **Resposta final** — prosa limpa do assistente, renderizada como markdown pela IDE.
  * **Dialogs de permissão** — comandos perigosos pausam o run e disparam o dialog nativo Allow/Reject da IDE.
</Info>

## Início rápido

```bash theme={"system"}
# 1. Garanta que o chatcli funciona standalone primeiro
chatcli --version

# 2. Suba o servidor ACP (a IDE faz isso por você depois de configurada)
chatcli acp
```

O processo fala JSON-RPC delimitado por linha em stdin/stdout. Todo logging vai para o logger de arquivo — o canal do protocolo fica limpo.

## IDEs JetBrains (IntelliJ IDEA, GoLand, WebStorm, …)

O AI Assistant da JetBrains hospeda agentes ACP customizados nativamente (macOS e Linux; agentes ACP não exigem assinatura de IA).

<Steps>
  <Step title="Abra a configuração de agente customizado">
    Na tool window **AI Chat**, abra o dropdown de agentes e escolha **Add Custom Agent**. A IDE cria e abre o `~/.jetbrains/acp.json`.
  </Step>

  <Step title="Registre o ChatCLI">
    ```json ~/.jetbrains/acp.json theme={"system"}
    {
      "default_mcp_settings": {
        "use_custom_mcp": true,
        "use_idea_mcp": false
      },
      "agent_servers": {
        "ChatCLI": {
          "command": "/usr/local/bin/chatcli",
          "args": ["acp"],
          "env": {
            "LLM_PROVIDER": "CLAUDEAI",
            "LLM_MODEL": "claude-sonnet-4-6"
          }
        }
      }
    }
    ```

    * `command` precisa ser um **caminho absoluto** (`which chatcli` para descobrir).
    * `env` é opcional — com ele você fixa provider/modelo para a IDE independentemente das sessões do terminal; sem ele, o ChatCLI sobe com a resolução normal de `.env`/ambiente.
  </Step>

  <Step title="Selecione o ChatCLI e converse">
    De volta ao AI Chat, escolha **ChatCLI** no dropdown de agentes e mande um prompt. Agentes customizados aparecem com um ícone próprio.
  </Step>
</Steps>

<Note>
  `use_custom_mcp` / `use_idea_mcp` controlam quais servidores MCP a **IDE** oferece aos agentes. O ChatCLI traz a própria configuração de cliente MCP (`~/.chatcli/mcp_servers.json`) de qualquer forma — as tools que você configurou no ChatCLI continuam funcionando dentro da IDE.
</Note>

## Zed

Adicione o ChatCLI em `agent_servers` no `settings.json` do Zed:

```json theme={"system"}
{
  "agent_servers": {
    "ChatCLI": {
      "command": "/usr/local/bin/chatcli",
      "args": ["acp"],
      "env": { "LLM_PROVIDER": "CLAUDEAI" }
    }
  }
}
```

Depois abra o Agent Panel e selecione **ChatCLI**.

## Modos de sessão

Toda sessão ACP roda em um de três modos, anunciados ao cliente no `session/new` e trocáveis a qualquer momento:

| Modo    | O que é                                                                                                              | Default |
| ------- | -------------------------------------------------------------------------------------------------------------------- | ------- |
| `chat`  | Conversa direta com o modelo — sem ferramentas, com o pipeline completo de experiência (memória, contextos, skills). |         |
| `agent` | O loop ReAct autônomo completo com todas as ferramentas do ChatCLI.                                                  | ✓       |
| `coder` | O loop focado em código: ler/editar arquivos, executar comandos, iterar — com plano ao vivo.                         |         |

Troque de modo pelo seletor da IDE, ou simplesmente digite o comando no prompt:

```
/coder            → muda esta sessão para o modo coder
/coder conserte os testes quebrados   → muda E já executa a tarefa
/chat             → volta para conversa pura
```

Mudanças de modo são confirmadas ao cliente via `current_mode_update`, então o seletor da IDE sempre reflete a realidade.

## Slash commands na IDE

Digite `/` na caixa de prompt: a IDE autocompleta a superfície de comandos do ChatCLI (anunciada via `available_commands_update`). Três grupos:

**Trocas de modo** — `/chat`, `/agent`, `/coder` (e `/run` como alias de agent).

**Comandos headless** — executam de verdade, com o output devolvido no chat:

| Categoria             | Comandos                                                                                                   |
| --------------------- | ---------------------------------------------------------------------------------------------------------- |
| Modelo e provider     | `/switch <provider> [--model <m>]`, `/provider`, `/model`, `/max-tokens`                                   |
| Configuração          | `/config` (panorama e todas as seções: `/config providers`, `/config agent`, `/config ui theme <nome>`, …) |
| Sessão                | `/session`, `/newsession`, `/compact`, `/export`                                                           |
| Contexto e memória    | `/context`, `/memory`                                                                                      |
| Pipeline de qualidade | `/thinking`, `/refine`, `/verify`, `/reflect`, `/moa`                                                      |
| Integrações           | `/mcp`, `/websearch`, `/skill`, `/plugin`                                                                  |
| Diagnóstico           | `/cost`, `/metrics`, `/ratelimit`, `/version`, `/help`                                                     |

**Todo o resto** — comandos que precisam de um terminal vivo (`/menu`, `/gateway`, `/schedule`, `/auth`, …) respondem com uma mensagem clara de "não disponível pela conexão da IDE" em vez de falhar em silêncio.

<Note>
  Um prompt que apenas *começa* com barra — um path como `/usr/local/bin explica isso`, uma palavra com typo — **não** é sequestrado: tokens desconhecidos fluem para o modelo como texto normal do usuário.
</Note>

<Warning>
  Comandos que pediriam confirmação num terminal (ex.: `/context rm <nome>`) rodam com o stdin em quarentena no servidor: qualquer confirmação é respondida como **negada, fail-safe**. Manutenção destrutiva é melhor feita no REPL do terminal.
</Warning>

## Dialogs de permissão

Servidores de agente unattended historicamente enfrentam uma escolha dura: auto-aprovar tudo ou bloquear tudo. O ACP tem uma resposta melhor — `session/request_permission` — e o ChatCLI a usa:

* Quando o coder quer executar um comando classificado como **perigoso** (deletes recursivos, force push, escalação de privilégio…), o run pausa e a IDE mostra o dialog nativo de aprovação com **Allow once** / **Reject once**.
* Qualquer coisa que não seja um *Allow* explícito — reject, dialog fechado, crash do cliente, timeout — **nega** o comando. O agente vê a recusa in-band e replaneja.
* O mesmo gate cobre blocos shell propostos pelo agente no modo agent.

Clientes que não implementam o pedido de permissão (ou drivers headless como o `agent_task` do MCP) recebem o comportamento estrito: comandos perigosos são recusados.

## Seus servidores MCP funcionam aqui também

O processo ACP é um boot completo do ChatCLI — incluindo o **cliente MCP**. Se o `~/.chatcli/mcp_servers.json` existe, todos os servidores MCP configurados são conectados no startup e as tools deles entram na caixa de ferramentas do agente, exatamente como no terminal:

* Peça ao agente algo que precise de uma tool MCP ("veja as issues abertas do Jira", "consulte o banco de staging") e ele chama a tool do servidor conectado autonomamente. Na IDE, a chamada renderiza como uma **tool call estruturada nativa** igual a qualquer built-in.
* **Hot reload** — editar o `mcp_servers.json` reconecta servidores ao vivo; sem reiniciar IDE nem agente. `/mcp` na caixa de prompt mostra status de conexão e tools.
* Servidores remotos com OAuth precisam ser autorizados antes (rode `@mcp-login` no terminal uma vez; os tokens persistem no keychain).

<Note>
  As conexões são estabelecidas de forma assíncrona no boot: um prompt enviado nos primeiríssimos segundos pode ainda não enxergar as tools de um servidor lento — elas entram no catálogo assim que a conexão completa.

  Uma diferença conceitual em relação ao `chatcli mcp-server`: o ACP não tem lista de tools voltada ao cliente, então a IDE nunca invoca tools MCP diretamente — o **agente** as usa por você. Invocação direta de tool (hub passthrough) é recurso do modo mcp-server.
</Note>

## Por baixo do capô (para integradores)

O ChatCLI implementa o ACP **protocol version 1**. Métodos:

| Método             | Notas                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialize`       | Retorna `agentInfo {name: "chatcli", version}`, capabilities (`embeddedContext: true`), sem auth.                                                         |
| `session/new`      | Retorna `sessionId` + `modes`; `available_commands_update` segue imediatamente após a resposta.                                                           |
| `session/set_mode` | Valida o modo, confirma via `current_mode_update`.                                                                                                        |
| `session/prompt`   | Aceita blocos `text`, `resource_link` e `resource` embutido. Um prompt por vez por sessão — prompt sobreposto é rejeitado, não enfileirado.               |
| `session/cancel`   | Interrompe o prompt em voo (`stopReason: "cancelled"`); qualquer tool call anunciada e não terminada é fechada como `failed` — nenhum spinner fica órfão. |

Kinds de `session/update` emitidos: `agent_thought_chunk`, `agent_message_chunk`, `tool_call`, `tool_call_update`, `plan`, `current_mode_update`, `available_commands_update`. Tool calls carregam `kind` (`read`/`edit`/`delete`/`move`/`search`/`execute`/`think`/`fetch`/`other`), `status`, `rawInput`, `locations` (paths para follow-along) e conteúdo limitado para exibição — o modelo sempre recebe o output completo; a visão do chat recebe um resumo limitado.

Menções de arquivo da IDE funcionam nos dois sentidos: blocos `resource_link` chegam como referências que as ferramentas do agente abrem sozinhas, e blocos `resource` (conteúdo embutido) são injetados como contexto anexado.

## Notas operacionais

* **Um run por vez** — runs de agent/coder serializam no processo (compartilham o estado do engine). O prompt de uma segunda sessão espera o run atual terminar; um segundo prompt na *mesma* sessão é rejeitado enquanto há um em voo.
* **Ambiente** — o processo ACP é um boot normal do ChatCLI: `.env`, logins OAuth no keychain, catálogos de provider, config de cliente MCP e skills resolvem exatamente como no terminal.
* **Sessões são in-process** — sessões da IDE mapeiam para o histórico do processo. `/newsession` e `/compact` agem sobre ele; `session/load` ainda não é implementado.
* **Logs** — stdout é o protocolo; diagnóstico vai para o arquivo de log padrão do ChatCLI. Coloque `LOG_LEVEL=debug` no bloco `env` do agente ao investigar.

## Troubleshooting

| Sintoma                                                  | Correção                                                                                                                                                                               |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agente não aparece no dropdown da IDE                    | Valide a sintaxe do `~/.jetbrains/acp.json`; reinicie a IDE.                                                                                                                           |
| Agente falha ao iniciar                                  | Use o caminho **absoluto** do binário em `command`; teste `chatcli acp` num terminal — digite `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}` e espere uma resposta JSON. |
| Respostas vazias no modo chat                            | Provider/modelo não resolvível no ambiente do processo ACP — defina `LLM_PROVIDER`/`LLM_MODEL` (ou as API keys) no bloco `env`.                                                        |
| Um comando responde "não disponível pela conexão da IDE" | Ele precisa de um terminal vivo — rode no REPL. O autocomplete de `/` lista tudo que funciona headless.                                                                                |
| Comando perigoso recusado em silêncio                    | Seu cliente não implementa `session/request_permission`; o ChatCLI falha em modo seguro. Rode pelo terminal, ou aprove pelo dialog num cliente que suporte.                            |

## Veja também

* [MCP Server](/pt/features/mcp-server) — o subcomando irmão: a superfície completa do ChatCLI como tools MCP
* [Coder Plugin](/pt/features/coder-plugin) — o que o engine do coder consegue fazer
* [Coder Security](/pt/features/coder-security) — a classificação de comandos perigosos por trás dos dialogs de permissão
* [Referência de Comandos](/pt/reference/command-reference) — a superfície completa de slash commands
* [Variáveis de Ambiente](/pt/reference/environment-variables) — knobs de provider/modelo/segurança