ACP — ChatCLI dentro da sua IDE

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.

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.

Início rápido

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

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.

Registre o ChatCLI

~/.jetbrains/acp.json

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

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.

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.

Zed

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

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

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.

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.

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

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.

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 — o subcomando irmão: a superfície completa do ChatCLI como tools MCP
Coder Plugin — o que o engine do coder consegue fazer
Coder Security — a classificação de comandos perigosos por trás dos dialogs de permissão
Referência de Comandos — a superfície completa de slash commands
Variáveis de Ambiente — knobs de provider/modelo/segurança

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

ACP — ChatCLI dentro da sua IDE

Início rápido

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

Zed

Modos de sessão

Slash commands na IDE

Dialogs de permissão

Seus servidores MCP funcionam aqui também

Por baixo do capô (para integradores)

Notas operacionais

Troubleshooting

Veja também

​Início rápido

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

​Zed

​Modos de sessão

​Slash commands na IDE

​Dialogs de permissão

​Seus servidores MCP funcionam aqui também

​Por baixo do capô (para integradores)

​Notas operacionais

​Troubleshooting

​Veja também

Início rápido

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

Zed

Modos de sessão

Slash commands na IDE

Dialogs de permissão

Seus servidores MCP funcionam aqui também

Por baixo do capô (para integradores)

Notas operacionais

Troubleshooting

Veja também