Como funciona

Como o Rationale funciona, e o que sai da sua máquina

Cada passo do Rationale, o que ele executa na sua máquina e o que sai dela. A página inicial mostra os quatro passos; esta página diz o que cada um faz, quais comandos rodam, quais hooks são instalados e, para cada evento, o que sai da sua máquina e o que nunca sai, verificado no código do cliente (0.9.0) e na API com que ele fala.

Verificado em 6 de outubro de 2026 · cliente 0.9.0

Em resumo

As decisões são extraídas na máquina de cada pessoa pela CLI do agente que ela já usa (claude -p ou codex exec). A transcrição vai para o provedor desse agente, como já ia, e nunca para o Rationale.
O Rationale recebe as decisões extraídas, citações curtas das palavras da própria pessoa e metadados: id e título da sessão, números dos turnos, repositório, branch, commit, hora, modelo e custo.
Antes de um agente editar um arquivo, as decisões correspondentes chegam até ele. Os caminhos são comparados na sua máquina; um caminho que não corresponde a nada nunca sai dela.
Quatro hooks, escritos uma vez nas configurações do Claude Code. rationale uninstall os remove.
Claude Code hoje, Codex em beta, qualquer cliente MCP para ler e registrar. Cursor em seguida.

1 · Capturar: quando um turno termina

Instale o cliente uma vez por laptop. A partir daí, cada vez que o seu agente termina um turno, ele executa o hook Stop do cliente (Claude Code; Codex depois que você confia nos hooks). O hook inicia uma captura em segundo plano e retorna na hora, então o agente nunca espera. Um watcher faz o mesmo a cada minuto para qualquer turno que um hook tenha perdido: uma falha, uma janela fechada, uma sessão parada por um minuto com turnos novos.

A captura lê a transcrição da sessão na sua máquina e monta um delta compacto dos turnos novos: suas mensagens, as respostas do agente e as ferramentas que ele chamou, com a entrada cortada em 200 caracteres. A saída das ferramentas, o raciocínio e o texto que o agente injeta por conta própria ficam de fora. Até 120 turnos vão em um bloco, com até 30 turnos anteriores como contexto somente de leitura, para que um bloco curto não seja lido isolado.

O delta vai para a CLI do próprio agente na sua máquina, com o seu login: claude -p para uma sessão do Claude Code, codex exec para uma sessão do Codex. Uma sessão do Codex nunca vai para a Anthropic, e uma sessão do Claude Code nunca vai para a OpenAI. Para o Claude Code a chamada é enxuta: um system prompt, um esquema JSON, sem ferramentas, sem configurações, sem hooks, sem servidores MCP, sem arquivo de sessão, então ela nunca aparece no seu histórico. Para o Codex é o codex exec documentado, efêmero, somente leitura, em uma pasta vazia, com os hooks do cliente desligados.

Só são capturadas as sessões em um repositório que um dos seus projetos lista. O cliente pergunta ao Rationale qual dos seus workspaces lista o remote git do repositório e guarda a resposta por dez minutos. Nenhum projeto: nada é extraído nem enviado. Dois workspaces: nada também, e rationale status nomeia os dois. Uma extração que falha é tentada de novo depois de 5, 15 e 60 minutos enquanto o mesmo bloco continuar falhando, e nunca bloqueia o agente.

O que chega ao Rationale é o resultado: as decisões, mais id e título da sessão, números dos turnos, repositório, branch, commit, a hora do último turno, agente, modelo, duração, tokens e custo equivalente. O endpoint que recebe uma captura não tem nenhum campo que possa carregar uma transcrição.

2 · Registrar: o que uma decisão contém

Uma decisão não é um resumo da sessão. Ela tem uma pergunta, a escolha, os critérios que a guiaram com o seu peso, as opções descartadas e por quê, suposições, e o que faria a equipe revisitá-la. Está ancorada a caminhos no repositório e a identificadores (uma classe, uma tabela, uma chave de ticket), e diz do que trata: negócio, produto ou técnica. As palavras da própria pessoa que a decidiu ficam citadas.

Toda decisão é registrada como inferida: um agente a extraiu. Ela passa a confirmada só por meio de uma pessoa: um clique no app, as próprias palavras dela em uma sessão (o cliente verifica a citação na transcrição antes de enviá-la, então um agente dizendo que alguém confirmou não basta), ou o merge do pull request que a carregava. As duas origens ficam visíveis, e os agentes veem a diferença.

As decisões são numeradas por workspace (D-42), mantidas como versões imutáveis e criptografadas em repouso. O servidor lê só identificadores, estados, âncoras e carimbos de tempo. Cada leitura e cada confirmação é escrita no log de auditoria do workspace. O extrator também informa quando a pessoa confirmou, corrigiu ou retirou uma decisão anterior na conversa, e quando o agente perguntou sobre uma.

Uma sessão que não nomeou nenhuma tarefa envia suas decisões para a caixa de entrada do projeto, onde a equipe as vincula, mantém ou retira. Uma repetição de uma decisão já registrada é vinculada, não registrada duas vezes.

3 · Dar contexto: #handle, notas e MCP

Uma tarefa é um #handle: um slug legível, único no workspace, ao qual tudo se liga: sessões, decisões, repasses, pull requests, tickets. Digite-o em qualquer prompt e o hook UserPromptSubmit envia ao Rationale o handle, o repositório e a branch, nada mais do prompt. De volta vem o contexto da tarefa: seu estado, suas decisões ativas por área, seus últimos repasses e seus pull requests abertos. A sessão fica vinculada à tarefa, então suas capturas seguintes caem lá.

Uma branch com o nome do handle também vincula a sessão, sem digitar nada. Quando uma sessão começa, o hook SessionStart busca suas notas: instruções permanentes que você deu aos seus agentes ("responda em espanhol", "nunca mexa nos controllers v1") para o workspace e o projeto deste repositório, em até 300 tokens e dois segundos. Para isso, só o remote do repositório sai da sua máquina.

Assistentes sem hooks se conectam por MCP: Claude (claude.ai e o app de desktop), ChatGPT, Cursor, o próprio Claude Code e o próprio Codex, e qualquer cliente que fale o protocolo. O servidor remoto em https://mcp.rationalehq.com/mcp usa OAuth 2.1 com PKCE: cole a URL, faça login uma vez, autorize seus workspaces. Não há chaves de API. Suas ferramentas são context_for, search, list_tasks, list_inbox, list_notes, pull_request_for, record_decision, record_outcome, record_handoff, record_note, remove_note, open_task, set_visibility, answer_overlap e suggest_same_person; cada uma declara se lê ou escreve, para que o seu cliente possa perguntar antes de uma escrita.

As decisões de negócio vêm primeiro, apresentadas como restrições que as escolhas de produto e técnicas não anulam. Tudo o que um agente registra por MCP é inferido, com as palavras da pessoa citadas, porque nada pode verificar uma conversa que o Rationale não viu.

4 · Avisar: antes da edição, não na revisão

O hook PostToolUse roda depois de cada chamada de ferramenta e termina em poucos milissegundos para as ferramentas que não observa. Ele observa Read, Edit, Write, MultiEdit e NotebookEdit, e os comandos Bash que nomeiam um arquivo, porque os agentes leem com cat, sed e grep tanto quanto com Read; para o Codex, comandos de shell e apply_patch. Ler é o momento que importa: o modelo ainda precisa escrever a sua alteração.

O hook mantém um índice das decisões ancoradas do repositório, atualizado em segundo plano no início da sessão e depois de cada turno: de cada decisão o número, caminhos, identificadores, área, commit e o essencial (pergunta e escolha). Ele compara o caminho do arquivo com esse índice na sua máquina e, para decisões que nomeiam uma classe, uma tabela ou uma chave de ticket, lê o arquivo aqui (texto, no máximo 512 KB) para procurá-las. O conteúdo nunca sai. Um arquivo que não corresponde a nada não gera nenhuma requisição.

Havendo correspondência, uma única requisição pede ao Rationale o texto do aviso: o repositório, o caminho relativo ao repositório, como cada decisão correspondeu, quais decisões o agente já tem no contexto e, depois de editar um arquivo que o pull request aberto de outra pessoa também altera, as linhas recém-alteradas. A resposta chega em até dois segundos: no máximo três decisões completas e o resto por número, quem decidiu cada uma, se uma pessoa a confirmou e quantos commits tocaram o arquivo desde então. Se o Rationale está lento ou fora do ar, o agente recebe o essencial do índice local. Cada aviso mostrado é uma leitura auditada.

Uma vez por arquivo por sessão; de novo se as decisões mudarem. Um arquivo cujas decisões já estão todas no contexto do agente não recebe aviso. É contexto, nunca um bloqueio: o hook nunca muda as permissões do agente nem o interrompe. Um hook que falha sai em silêncio.

O que sai da sua máquina

Uma linha por evento. Cada linha foi verificada no código do cliente (rationale-client 0.9.0) e na API que recebe cada requisição. Onde a sua própria CLI roda, a linha diz o que vai para o provedor do seu agente: esse tráfego vai para onde as suas sessões já vão, com a sua própria conta.

Quando	Sai da sua máquina	Nunca sai
Um turno termina (hook `Stop`; o watcher para turnos perdidos)	Para o provedor do seu agente, pelo seu próprio `claude -p` ou `codex exec`: os turnos novos em forma compacta (suas mensagens, as respostas do agente, as ferramentas que ele chamou com a entrada cortada), com até 30 turnos anteriores como contexto. Para o Rationale: as decisões encontradas, com as palavras da pessoa citadas e os caminhos a que estão ancoradas; quais decisões anteriores a pessoa confirmou, corrigiu ou retirou, com a citação e o turno; id e título da sessão, números dos turnos, remote do repositório, branch, commit, hora do último turno, agente, modelo, duração, tokens, custo equivalente, versão do cliente.	A transcrição. A saída das ferramentas e o raciocínio, nem mesmo para o seu provedor. Valores de segredos: recusados ao escrever, removidos das citações. Uma sessão do Codex nunca vai para a Anthropic; uma do Claude Code nunca para a OpenAI.
O agente lê ou edita um arquivo (`PostToolUse`: Read, Edit, Write, MultiEdit, NotebookEdit, comandos Bash que nomeiam um arquivo; comandos de shell e `apply_patch` no Codex)	Nada, a menos que o caminho ou o conteúdo do arquivo corresponda ao índice local, ou o caminho esteja no pull request aberto de um colega. Então, para o Rationale: o remote do repositório, o caminho relativo ao repositório, como cada decisão correspondeu (número, tipo, âncora, commits desde então), as decisões já no contexto do agente, a ferramenta, o id da sessão e, depois de editar um arquivo que está no pull request de alguém, os intervalos de linhas recém-alterados.	O conteúdo do arquivo: os identificadores são procurados lendo-o aqui, no máximo 512 KB. Caminhos que não correspondem a nada. O comando e a sua saída.
Você digita `#handle` em um prompt (`UserPromptSubmit`)	O handle (até três por prompt), o remote do repositório, a branch, o id da sessão, o agente. O contexto da tarefa volta.	O prompt. Um prompt sem `#handle` não gera nenhuma requisição.
Uma sessão começa (`SessionStart`, também depois de `/clear` ou de uma compactação)	O remote do repositório, o id da sessão e o agente, para buscar suas notas (no máximo dois segundos). Em segundo plano: o remote e o digest do índice guardado, para atualizar as decisões ancoradas (`unchanged` volta quando nada mudou); e o remote sozinho, para perguntar qual workspace o lista (em cache por dez minutos).	A pasta de trabalho, seus arquivos, o ambiente.
Um cliente MCP chama uma ferramenta (Claude, ChatGPT, Cursor ou qualquer cliente, por `mcp.rationalehq.com`)	O que o agente passa à ferramenta: um `#handle`, caminhos ou refs, o nome de um projeto, números de decisão, palavras de busca, ou o que ele registra (uma decisão, um resultado, um repasse, uma nota, uma tarefa, com as palavras da pessoa citadas). Por MCP não há índice local: os caminhos que o agente passa a `context_for` chegam ao Rationale como estão. Cada decisão lida ou escrita é um evento auditado.	A conversa. O código. Uma consulta de busca não é guardada nem registrada em log.
Um resumo está na hora (o watcher pergunta uma vez por hora; uma vez por dia por projeto, ou depois de dez decisões novas)	Para o Rationale: um pedido de reserva, vazio. O Rationale devolve as tarefas do projeto, os últimos repasses, os tópicos anteriores e as decisões ativas em forma curta. Para o provedor do seu agente, por `claude -p` (ou `codex exec` em uma máquina sem Claude Code): essa entrada, nunca uma transcrição. Para o Rationale: o status (feito, em andamento, a seguir), os tópicos com as decisões que cada um cobre e onde a IA os colocou, onde cada tarefa está, tensões entre decisões, uma área e identificadores para decisões que não os têm, as condições de revisão agora atendidas, mais modelo, duração, tokens e custo.	Transcrições, código, arquivos.
Uma sessão fica em silêncio (o watcher, 30 minutos sem turno novo, só sessões com decisões)	Para o provedor do seu agente: os últimos 60 turnos da sessão em forma compacta, pela mesma CLI. Para o Rationale: o repasse que ele escreveu (resumo, próximos passos, questões em aberto), o id da sessão e o agente.	Os turnos em si. Uma sessão sem decisões não recebe repasse; uma para a qual o Rationale não tem tarefa não é perguntada de novo.
Você faz deploy (`rationale deploy production`, opcional, para equipes que fazem deploy das suas máquinas)	O remote do repositório, o ambiente, o sha do commit e a sua branch, até 500 shas de commits alcançáveis a partir dele, o nome da ferramenta. O Rationale marca os pull requests e as decisões que estão em produção.	Mensagens de commit, diffs, código.
Você faz login (`rationale init`, `rationale login`)	O nome da sua máquina (o nome do computador no macOS, senão o hostname) e a versão do cliente, para iniciar o fluxo de dispositivo. Você digita um código no navegador, logado no Rationale. O token do dispositivo chega uma vez e é salvo legível só por você (`~/.config/rationale/config.json`, modo 600).	Uma senha: não existe. O Rationale faz login por link no e-mail.
Você cola uma thread (`rationale record`, uma thread do Slack ou notas de reunião, opcional)	Para o provedor do seu agente: o texto, pelo mesmo extrator. Para o Rationale: as decisões encontradas e o título que você deu, como uma captura de um turno marcada `paste`.	O texto em si.
Cada requisição ao Rationale	A versão do cliente (`User-Agent`), quais agentes executam os hooks nesta máquina (`claude_code=4/4, codex=0/4`: nomes e contagens) e, uma vez depois de cada atualização, o código do resultado (ok, assinatura inválida, revertida). Como todo servidor, o Rationale vê o endereço IP de onde vem uma requisição. Com a atualização do índice, contadores por repositório: leituras e edições verificadas e correspondentes, repetições, tempos esgotados, ids de avisos que o agente citou ou seguiu com outra edição, tempos de resposta.	Nada de uma sessão. Caminhos: os contadores são só contagens e ids.
A cada seis horas, a verificação de atualização (o watcher, nunca um hook)	Um `GET` do manifesto assinado da versão e da sua assinatura em `app.rationalehq.com/client`, que redireciona para os arquivos no GitHub, com a versão do cliente no `User-Agent`. O binário é baixado ao lado do atual, verificado (assinatura minisign, tamanho, sha256, uma execução de `--version` de dois segundos) e trocado; o anterior fica guardado para `rationale update --rollback`.	Nada sobre você ou suas sessões. Instalações pelo Homebrew só avisam que existe uma versão mais nova.

O conteúdo das decisões, das notas e dos repasses é criptografado em repouso com chaves guardadas separadas do banco de dados. Nossa equipe vê identificadores, estados e âncoras, nunca o conteúdo, e cada visualização da nossa equipe é escrita no seu log de auditoria. A página de segurança tem a visão técnica; a política de privacidade, a jurídica.

Instalar em dois minutos

Um comando, sem sudo, macOS ou Linux. Ele coloca um binário em ~/.local/bin/rationale e nada mais: ainda sem hooks, sem login.

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

Ou com o Homebrew:

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

Depois, dentro de um repositório que o seu workspace lista:

rationale init

Faça login pelo navegador. O terminal mostra um código e abre a página de login do app. Um login por workspace; rationale login adiciona outro.
Este repositório. Ele verifica qual dos seus workspaces lista o remote git deste repositório. Listado por um: capturado. Por nenhum: ele avisa e pergunta se você acabou de listá-lo.
Agentes nesta máquina. Ele escreve os quatro hooks no ~/.claude/settings.json do Claude Code (um backup é mantido; suas próprias entradas ficam intactas) e, se o Codex estiver aqui, em ~/.codex/hooks.json, e explica o passo de confiança que o Codex exige. O Cursor é detectado e informado, ainda não capturado.
Watcher. Um job do launchd no macOS, um timer de usuário do systemd no Linux, a cada minuto: captura qualquer turno que um hook perdeu, escreve repasses, roda resumos e verifica atualizações. Sem uma sessão de usuário do systemd, os hooks continuam capturando cada turno.

Pronto. Trabalhe como sempre. rationale status mostra os logins, o workspace deste repositório, os hooks, o watcher e a sessão mais recente, a qualquer momento. Para ler e registrar a partir do Claude, do ChatGPT ou do Cursor, adicione o servidor MCP; a documentação tem os passos de cada cliente. Para o Claude Code:

claude mcp add --scope user --transport http rationale https://mcp.rationalehq.com/mcp

Os hooks, e como removê-los

rationale init adiciona quatro entradas ao objeto hooks de ~/.claude/settings.json. Cada uma executa o binário instalado com o nome do evento; o binário decide o que fazer, então uma atualização nunca reescreve as suas configurações. Os limites de tempo são o máximo que um hook pode levar; eles retornam bem antes.

Hook	Roda quando	O que faz	Limite
`Stop`	O agente termina um turno	Inicia uma captura dos turnos novos em segundo plano e retorna	10 s
`UserPromptSubmit`	Você envia um prompt	Com um `#handle`: vincula a sessão à tarefa e adiciona o contexto da tarefa. Senão, nada.	15 s
`PostToolUse`	Depois de cada chamada de ferramenta (sem matcher)	Uma leitura ou edição de arquivo: comparada localmente, as decisões ancoradas adicionadas se houver correspondência. Qualquer outra ferramenta: sai na hora.	3 s
`SessionStart`	Uma sessão começa ou é retomada, ou depois de `/clear` ou de uma compactação	Adiciona suas notas; atualiza o índice de âncoras em segundo plano	5 s

Uma entrada fica assim; o comando é o caminho absoluto do binário, nunca uma busca no PATH:

"Stop": [{ "hooks": [{ "type": "command", "command": "/Users/you/.local/bin/rationale hook claude-code stop", "timeout": 10 }] }]

Um hook nunca bloqueia o agente: todo erro é absorvido e o hook sai com 0; uma falha grave sai com um código que o Claude Code mostra como erro não bloqueante. Os hooks não fazem nada em um repositório que nenhum projeto lista. Para o Codex, as quatro entradas vão para ~/.codex/hooks.json, também sem matcher; o Codex só as executa depois que você confia nelas (/hooks na CLI, Review hooks no app), e o cliente nunca escreve essa confiança por você.

Para remover tudo:

rationale uninstall

Ele remove os quatro hooks do Claude Code e do Codex, mantendo um backup de cada arquivo de configuração, e remove o watcher. Depois revogue o dispositivo na página Devices do app, o que invalida o seu token. A configuração fica em ~/.config/rationale/ e o estado local em ~/.local/state/rationale/ até você apagá-los; o binário é um único arquivo que você pode remover.

Agentes e conectores hoje

O que está em produção, o que está em beta e o que vem a seguir. Nomeamos o que não cobrimos em vez de deixar implícito.

Agente ou ferramenta	Status	O que funciona
Claude Code	Em produção	Captura depois de cada turno, avisos antes das edições (Read, Edit, Write, MultiEdit, NotebookEdit, Bash), contexto por `#handle`, notas no início da sessão, repasses, resumos
Codex (a CLI, o app de desktop do ChatGPT e a extensão do IDE)	Beta	Captura e contexto depois que você confia nos hooks; avisos em comandos de shell e `apply_patch`; extração com `codex exec` na sua própria conta do ChatGPT, que se pausa sozinha por um dia se a OpenAI informar atividade incomum
Claude (claude.ai e o app de desktop), ChatGPT, Cursor, qualquer cliente MCP	Em produção	Ler as decisões da sua equipe e registrar novas pelo servidor MCP remoto. Sem captura e sem avisos antes da edição: isso vem dos hooks.
Captura no Cursor	A seguir	O Cursor é detectado e informado pelo `rationale init`; suas sessões ainda não são capturadas
Gemini CLI	A seguir	Não construído
GitHub	Em produção	Um GitHub App nas organizações que você escolher: pull requests, revisões e issues vinculados às decisões dos arquivos que alteram; o merge de um pull request confirma as decisões capturadas na sua branch
Jira	Em produção	OAuth com o seu site Atlassian: tickets e epics viram tarefas, as decisões seguem o ticket
Sem tracker	Em produção	As tarefas vivem no Rationale; os agentes as abrem quando você pede
Linear, Slack	A seguir	Não construídos. Conte o que sua equipe usa ao solicitar acesso.

Acesso antecipado: solicite acesso e configuramos o seu workspace com você, em um dia útil.

Qualquer outra coisa: support@rationalehq.com