AWR
GitHub
Português
English中文Españolहिन्दीPortuguêsРусский日本語한국어DeutschFrançais

Conecte o seu agente

Ver fonte no GitHub

O AWR não executa o seu agente. O cliente de agente (Codex, Claude Code, Kimi, Cursor, Grok) faz o trabalho com as suas próprias ferramentas; o AWR fornece fatos atuais do projeto, contexto de trabalho, claims e memória de sessão recuperável para o mesmo projeto inicializado. Os rótulos de provedor e modelo nos registros de sessão do AWR são apenas metadados — eles nunca iniciam nem configuram o cliente.

Todo cliente suportado segue o mesmo padrão:

  1. Compile os dois executáveis a partir de um checkout do AWR:
cargo build --locked -p awr-cli -p awr-mcp
  1. Inicialize o projeto de destino a partir do seu manifesto-fonte revisado (veja o Quickstart), depois registre o servidor awr-mcp no cliente, apontando --project para o caminho absoluto do projeto. Cada servidor se vincula a uma raiz de projeto canônica; dê nomes distintos a servidores de projetos diferentes.
  2. Verifique a conexão — um arquivo de configuração no disco não é uma conexão ativa — e confirme a identidade do projeto com uma leitura de status antes de qualquer trabalho.
  3. Trabalhe o ciclo de vida compartilhado de sessões: inicie ou retome uma sessão, leia o contexto, faça checkpoint antes do handoff, encerre quando parar. Veja CLI e Ferramentas MCP.

As seções abaixo trazem os caminhos de mesclagem, a configuração e as ressalvas de cada cliente. Quando um cliente documenta hooks automáticos de ciclo de vida, trate-os como não verificados até você ver um acionamento real e um recibo; o fluxo manual de checkpoint/resume sempre funciona.

Codex

O Codex carrega a configuração de projeto apenas para projetos confiáveis; seus clientes CLI, desktop e IDE compartilham a configuração MCP no mesmo host. Escolha uma das duas opções: mescle o modelo de configuração MCP no .codex/config.toml do projeto (substituindo os seus dois caminhos e preservando a configuração existente), ou registre no nível do usuário:

codex mcp add awr -- /absolute/path/to/awr-mcp \
  --project /absolute/path/to/initialized/project
codex mcp get awr --json

Na view /mcp do cliente, confirme um servidor awr conectado e verifique a identidade do projeto antes de trabalhar; um servidor configurado não é prova de uma conexão ativa. Ferramentas de leitura esperadas: awr_project_status, awr_work_ready, awr_work_get, awr_context_compile, awr_search. Ferramentas de mutação: awr_work_transition, awr_event_append, awr_evidence_record. O servidor não requer uma chave de API de modelo.

O Codex é o único cliente com um instalador para hooks automáticos de ciclo de vida: use awr client install para pré-visualizar a configuração exata antes de --accept. A instalação preserva hooks existentes e nunca aprova a confiança deles automaticamente. O Codex documenta SessionStart (startup|resume|clear|compact), PreCompact (manual|auto) e SessionEnd (consultivo, timeout curto). Verifique a entrega real dos acionamentos no cliente — até lá, faça checkpoints manualmente antes do handoff ou da compactação.

Claude Code

O Claude Code se conecta por meio de um adaptador controlado nomeado (adapter id claude_code). Ele não é auto-iniciável: o AWR não vai iniciar o Claude Code para você, nem vai pará-lo por conta própria — esses passos ficam com você. O que o adaptador suporta é ler status, reconectar/retomar e fazer forense de resultados.

Caminho do operador:

  1. Inicie o Claude Code você mesmo.
  2. Vincule-o ao AWR com o cliente genérico e o ID de conversa nativo:
awrj client bind --client generic --external-session claude:<native-id> \
  --work "$AWR_WORK" --session "$AWR_SESSION"
  1. Quando precisar de observações do AWR, reporte as fases por meio do relatório de execução externa da CLI compartilhada.
  2. Em caso de nova tentativa, reconecte a mesma identidade de execução antes de começar qualquer coisa nova.

Kimi

Este guia tem como alvo o Kimi Code 0.41.0 (inspecionado em 2026-09-08); releases mais antigos do kimi-cli usam caminhos de configuração e flags diferentes, então verifique primeiro kimi --version e kimi --help. Use a ferramenta de terminal do Kimi para chamar a CLI do AWR e, opcionalmente, conecte o mesmo projeto via MCP stdio mesclando este servidor no .kimi-code/mcp.json do projeto (nível do usuário: ~/.kimi-code/mcp.json), preservando as outras entradas:

{
  "mcpServers": {
    "awr": { "command": "/absolute/path/to/awr-mcp",
      "args": ["--project", "/absolute/path/to/initialized/project"],
      "cwd": "/absolute/path/to/initialized/project" }
  }
}

A configuração de projeto requer confiança no workspace. Use /mcp-config para a configuração e /mcp para inspecionar o status da conexão; servidores adicionados pela edição da configuração entram nas sessões recém-criadas. Confirme a identidade do projeto com awr_project_status. O rótulo de provedor para os metadados de sessão do Kimi é moonshot.

Os próprios kimi --continue, kimi --session <kimi-conversation-id> e /compact do Kimi operam sobre a conversa dele; seus IDs são separados dos IDs do AWR. Após um compact, compile o contexto para a mesma sessão AWR ativa — um resume explícito do AWR é apenas para um handoff real. O Kimi documenta os hooks SessionStart, SessionEnd, PreCompact e PostCompact, mas esta integração não instala nenhum adaptador automático; use o processo manual de checkpoint.

Cursor

Verificado contra o Cursor 3.18.9 (2026-09-17). Não rode awr client install para o Cursor (Unsupported), e não passe --client cursor no bind (InvalidInput) — use a identidade de cliente genérico mostrada abaixo. Mescle o modelo stdio no .cursor/mcp.json do projeto ou no ~/.cursor/mcp.json do usuário:

{
  "mcpServers": {
    "awr": { "type": "stdio", "command": "/absolute/path/to/awr-mcp",
      "args": ["--project", "/absolute/path/to/initialized/project"] }
  }
}

A tabela de campos stdio do Cursor exige "type": "stdio" e não aceita cwd. O AWR só precisa de um command absoluto mais --project. Recarregue a janela e verifique Output → MCP Logs em caso de falha na inicialização; quando os dois arquivos de configuração existem, confirme em Customize qual deles a Agent Window anexou. Duas ressalvas:

Ferramentas agrupadas. Na árvore de código atual, o tools/list padrão retorna oito ferramentas de domínio (awr_query, awr_context, awr_work, awr_evidence, awr_session, awr_continuity, awr_change, awr_compaction) em vez de nomes de ferramentas planos. Teste o status por meio de awr_query:

{"child_tool": "awr_project_status", "arguments": {}}

Os nomes planos continuam chamáveis, mas não estão no catálogo padrão; defina AWR_MCP_TOOL_EXPOSURE_MODE=flat somente se o seu build do Cursor não conseguir rotear por domínios. Os releases empacotados não expõem o awr_query agrupado — compile a partir da árvore de código para essa rota e verifique primeiro o catálogo de ferramentas do seu build.

Cloud Agents não conseguem alcançar um awr-mcp em um laptop nem 127.0.0.1; eles precisam de uma porta de entrada HTTPS alcançável com raízes de projeto no lado do servidor. O serviço HTTP compartilhado do AWR usa um bearer token (não o OAuth do Cursor):

{
  "mcpServers": {
    "awr": { "url": "http://127.0.0.1:8080/mcp",
      "headers": { "Authorization": "Bearer ${env:AWR_ENGINEERING_TOKEN}" } }
  }
}

Para identidade, vincule o cliente genérico com o ID de conversa nativo, falhando se ele estiver vazio para que você nunca vincule o literal cursor::

: "${HOST_CONVERSATION_ID:?set the native host conversation ID first}"
AWR_EXTERNAL="cursor:${HOST_CONVERSATION_ID}"
awrj client bind --client generic --external-session "$AWR_EXTERNAL" \
  --work "$AWR_WORK" --session "$AWR_SESSION"

O Cursor documenta os hooks sessionStart, sessionEnd e preCompact em .cursor/hooks.json, mas não há instalador para esse dialeto — faça checkpoints manualmente até você ter um acionamento de hook real e um recibo de checkpoint.

Grok

Verificado contra o Grok Build 1.0.13 (2026-09-08). Use a ferramenta de terminal do Grok para chamar a CLI do AWR, ou conecte o seu cliente MCP stdio a partir do diretório do projeto:

cd /absolute/path/to/initialized/project
grok mcp add --scope project awr -- /absolute/path/to/awr-mcp \
  --project /absolute/path/to/initialized/project
grok mcp doctor awr --json

add --scope project escreve ou atualiza .grok/config.toml (o escopo de usuário é o padrão quando a flag é omitida); use um nome de servidor distinto se awr já se referir a outro projeto. A tabela equivalente é:

[mcp_servers.awr]
command = "/absolute/path/to/awr-mcp"
args = ["--project", "/absolute/path/to/initialized/project"]

Use /mcps no Grok Build para inspecionar e atualizar as conexões, depois chame awr_project_status e verifique a identidade do projeto. A confiança no projeto é um pré-requisito separado: uma pasta não confiável deixa o servidor sem iniciar, então revise o projeto no fluxo normal de confiança do cliente primeiro. O rótulo de provedor para os metadados de sessão do Grok é xai.

A continuação nativa de conversas do Grok é separada da recuperação de sessões do AWR:

grok --cwd "$AWR_PROJECT" --continue
grok --cwd "$AWR_PROJECT" --resume <grok-conversation-id>

O --session-id do Grok cria uma nova conversa — não é um ID do AWR nem uma flag de resume. Após a compactação nativa, compile o contexto para a mesma sessão AWR ativa; use o fluxo explícito de resume do AWR apenas para um handoff real.

O Grok Build documenta eventos de sessão e de compactação no seu sistema de hooks, mas nenhum adaptador automático é instalado aqui; use o processo manual de checkpoint até você verificar um acionamento real e um recibo. Os conectores personalizados do Grok web exigem uma URL MCP alcançável — um caminho de executável local não pode ser inserido como essa URL; o serviço HTTP compartilhado do AWR pode cumprir esse papel, mas implantá-lo e atender aos requisitos de autenticação do conector é um passo separado que este guia não verifica.

Próximos passos

  • Ferramentas MCP — toda a superfície de ferramentas que o seu cliente pode chamar uma vez conectado.
  • Fluxo de trabalho diário — o ciclo iniciar-trabalhar-checkpoint-retomar, seja qual for o cliente que você usa.