Instale o Rationale e conecte seus agentes

Como as peças se encaixam

O Rationale tem três partes. Um cliente na máquina de cada pessoa: um único binário, sem runtime, que escuta as sessões de agente dessa pessoa. O app em app.rationalehq.com, onde vivem as decisões, as tarefas e os logs de auditoria, e onde a equipe entra. E um servidor MCP remoto em mcp.rationalehq.com, pelo qual assistentes como Claude, ChatGPT e Cursor leem e registram decisões.

O cliente extrai as decisões com o agente em que a pessoa já fez login (claude -p para o Claude Code, codex exec para o Codex), naquela máquina. O Rationale recebe as decisões extraídas, citações curtas e metadados: id da sessão, números dos turnos, repositório, branch, hora. A transcrição nunca sai da máquina, exceto para o provedor do próprio agente, como sempre aconteceu.

Antes de começar

• macOS (um único binário universal) ou Linux em x86_64 ou arm64. Windows ainda não é suportado: o instalador avisa e para.
• Claude Code ou Codex com login feito na máquina. O cliente usa essa CLI para extrair as decisões, no plano da própria pessoa; ele nunca precisa de uma chave de API própria.
• Um workspace do Rationale. Estamos em acesso antecipado: solicite acesso e configuramos o workspace com você em um dia útil.
• Um projeto no workspace que liste o remote git de cada repositório que você quer capturar. O cliente roteia cada sessão por esse remote; um repositório que nenhum projeto lista nunca é capturado.
• curl ou wget, e sha256sum ou shasum, que todo macOS e Linux tem.

Instale o cliente

Um comando, sem sudo:

curl -fsSL https://rationalehq.com/install.sh | sh

O instalador coloca um único binário em ~/.local/bin/rationale. Ele baixa ao lado do binário, confere tamanho e sha256 contra o manifesto de release, executa rationale --version e o renomeia para o lugar definitivo. Nunca edita os arquivos do seu shell: se ~/.local/bin não está no seu PATH, ele imprime a linha a adicionar. Não faz login nem instala hooks; isso é o rationale init, a seguir.

Com Homebrew, em vez disso:

brew tap rationalehq/tap https://github.com/jorgebasilio/homebrew-tap
brew install rationalehq/tap/rationale

A primeira instalação confia no TLS até o host dos arquivos, como todo curl | sh. Toda atualização posterior é verificada pelo próprio cliente contra um manifesto de release assinado (veja Atualizações, rollback, desinstalação).

Entre e configure: rationale init

Execute uma vez por máquina, dentro de um repositório que seu workspace lista:

rationale init

1. Login. Ele abre o navegador com um código curto (o device flow). Você entra no Rationale e a máquina recebe seu próprio token, guardado em ~/.config/rationale/config.json (modo 600). Um login por workspace; rationale login adiciona outro.
2. Verificação do repositório. Ele consulta qual dos seus workspaces tem um projeto que lista o remote git deste repositório. Exatamente um: capturado ali. Nenhum: não capturado, e ele avisa. Dois: não capturado, e rationale status nomeia os dois. Ele nunca adivinha.
3. Hooks. Para o Claude Code, ele escreve quatro entradas em ~/.claude/settings.json (um backup é mantido, suas próprias entradas ficam intactas): Stop, UserPromptSubmit, SessionStart e PostToolUse. Para o Codex, adiciona quatro entradas em ~/.codex/hooks.json; o Codex só executa um hook depois que você confia nele (/hooks na CLI, ou Review hooks no app), e init e status avisam você até que isso esteja feito.
4. Watcher. No macOS, um job do launchd (~/Library/LaunchAgents/com.rationalehq.client.watcher.plist); no Linux, um timer de usuário do systemd (rationale-watcher.timer), a cada minuto: capturas, repasses, resumos e atualizações. Sem uma sessão de usuário do systemd, o init avisa, e os hooks continuam capturando cada turno.

rationale status mostra os logins, o workspace deste repositório, os hooks, o watcher e a sessão mais recente, a qualquer momento.

O que acontece enquanto você trabalha

• Captura. Quando uma sessão termina (o hook Stop do Claude Code, ou o watcher para o Codex), o cliente monta um delta compacto dos turnos novos, sem saída de ferramentas nem raciocínio, e pede ao seu agente que identifique as decisões: pergunta, escolha, critérios, o que foi descartado, quando revisitar, os arquivos e a tarefa a que se referem, e as palavras da própria pessoa que confirmam, corrigem ou retiram uma anterior. Uma extração que falha é tentada de novo mais tarde e nunca bloqueia o agente.
• Avisos antes da edição. Quando o agente lê ou está prestes a alterar um arquivo ao qual uma decisão está ancorada, o hook pede ao Rationale essas decisões, com um orçamento de dois segundos, e as mostra ao agente antes da edição: quem decidiu, o essencial e quantos commits tocaram o arquivo desde então. Se o servidor está lento, o agente recebe o essencial de um índice local. Uma decisão que nomeia uma classe, uma tabela ou uma chave de ticket é procurada dentro do conteúdo do arquivo, na sua máquina; esse conteúdo nunca sai dela.
• Contexto para uma tarefa. Digite o #handle de uma tarefa em um prompt e o agente começa com o que foi decidido nela, quem está nela e os pull requests abertos.
• Notas no início da sessão. Suas notas para o repositório, o workspace e o projeto chegam ao agente quando uma sessão começa.
• Repasses. Uma sessão com decisões que fica em silêncio por 30 minutos recebe um repasse escrito para quem pegar a tarefa: resumo, próximos passos, questões em aberto.
• Nunca no caminho. Um hook que falha sai em silêncio e deixa o agente continuar. Nada espera pela rede, exceto o aviso, que tem seu orçamento.

Comandos

Conecte Claude, ChatGPT, Cursor e outros assistentes (MCP)

Assistentes que falam o Model Context Protocol leem as decisões da sua equipe e registram novas pelo servidor remoto em https://mcp.rationalehq.com/mcp. Ele usa OAuth 2.1: cole a URL, entre uma vez no navegador e autorize seus workspaces. Cada ferramenta diz se lê ou escreve: context_for, list_tasks, record_decision, record_handoff, record_note, pull_request_for e algumas mais.

• Claude Code: claude mcp add --scope user --transport http rationale https://mcp.rationalehq.com/mcp, depois o login no navegador que o Claude Code abre.
• Codex: codex mcp add rationale --url https://mcp.rationalehq.com/mcp, depois codex mcp login rationale.
• Claude (claude.ai e o app de desktop): Settings → Connectors → Add custom connector, com a URL acima. Entre quando o Claude pedir.
• ChatGPT: Settings → Connectors → Create, com a URL acima (conectores personalizados exigem um plano que os permita). Entre quando o ChatGPT pedir.
• Cursor e outros clientes MCP: adicione um servidor com essa URL nas configurações de MCP do cliente (no Cursor, ~/.cursor/mcp.json) e entre quando for solicitado.

Um projeto pode fixar seu workspace com ?workspace=slug na URL. A página Get started do app mostra os mesmos comandos com os seus dados preenchidos.

Conecte o GitHub e o Jira

No app, Settings → Connectors. O GitHub é instalado como um GitHub App nas organizações que você escolher; o Jira se conecta por OAuth ao seu site Atlassian. Os dois são por membro: cada pessoa vê no Rationale apenas os repositórios, pull requests, tickets e projetos que a própria conta pode ver.

Pull requests, revisões e issues são ligados às decisões que regem os arquivos que eles alteram. Tickets e épicos do Jira viram tarefas, e as decisões seguem o ticket. Sem um tracker, as tarefas vivem no Rationale e os agentes as abrem quando solicitados.

O que sai da sua máquina, e o que nunca sai

Extração, repasses e resumos rodam com o seu próprio agente, no seu próprio plano, então o custo fica do seu lado e visível: cada captura carrega seu custo equivalente. O cliente informa o resultado de uma atualização (ok, assinatura inválida, revertida) como um código na sua próxima requisição, nunca como um log.

Atualizações, rollback, desinstalação

O watcher, nunca um hook, verifica o manifesto de release assinado no máximo a cada seis horas e troca o binário no lugar, mantendo o anterior. Duas chaves públicas minisign são compiladas em cada binário: uma chave de release que assina todos os manifestos e uma chave de backup offline usada apenas para rotacionar a primeira. Um manifesto que nenhuma das duas assinou é recusado; um manifesto reapresentado (replay) também. Instalações pelo Homebrew apenas avisam que existe uma versão mais nova.

rationale update
rationale update --rollback

Para sair: rationale uninstall remove os hooks e o watcher; depois revogue o dispositivo na página Devices do app, o que invalida seu token. A configuração fica em ~/.config/rationale/ e o estado em ~/.local/state/rationale/ até você apagá-los.

Quando algo não parece certo

• rationale: command not found: ~/.local/bin não está no seu PATH; o instalador imprimiu a linha a adicionar ao perfil do seu shell.
• As sessões não são capturadas: execute rationale status. O remote do repositório precisa estar listado por exatamente um projeto em um dos seus workspaces; dois workspaces reivindicando-o interrompem a captura até que um deles o retire. Os hooks do Codex só capturam depois que você confia neles.
• Os avisos não aparecem: o hook tem um orçamento de dois segundos e desiste em silêncio numa rede lenta; o próximo tenta de novo. rationale anchors check PATH mostra o que um hook diria para um arquivo.
• Proxy corporativo: o cliente usa o armazenamento de certificados da sua plataforma, então um proxy com certificado raiz próprio funciona sem configuração.
• Qualquer outra coisa: support@rationalehq.com, com a saída de rationale status. Ela não contém transcrição nem texto de decisão.