# Instale o Rationale e conecte seus agentes · Rationale

> Como instalar o cliente do Rationale no macOS e no Linux, o que o rationale init configura, como o Claude Code e o Codex capturam decisões, como conectar Claude, ChatGPT e Cursor por MCP, e exatamente o que sai da sua máquina.

Source: https://rationalehq.com/pt/docs
Language: pt

Documentação

# Instale o Rationale e conecte seus agentes

Tudo o que uma equipe precisa para usar o Rationale, na ordem em que acontece: instalar o cliente em cada laptop, entrar, deixar que ele capture, conectar os assistentes que falam MCP e saber o que sai das suas máquinas. Escrito para o cliente tal como é distribuído hoje.

Atualizado em outubro de 2026 · cliente 0.9.0

Nesta página

1.  [Como as peças se encaixam](#overview)
2.  [Antes de começar](#requirements)
3.  [Instale o cliente](#install)
4.  [Entre e configure: rationale init](#init)
5.  [O que acontece enquanto você trabalha](#day)
6.  [Comandos](#commands)
7.  [Conecte Claude, ChatGPT, Cursor e outros assistentes (MCP)](#mcp)
8.  [Conecte o GitHub e o Jira](#connectors)
9.  [O que sai da sua máquina, e o que nunca sai](#data)
10.  [Atualizações, rollback, desinstalação](#updates)
11.  [Quando algo não parece certo](#troubleshooting)

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

Comando

O que faz

`rationale init [--url URL]`

Entrar (navegador), verificar este repositório, instalar os hooks e o watcher

`rationale login [--url URL]`

Entrar em outro workspace, ou renovar um login

`rationale status`

Logins, o workspace deste repositório, hooks, watcher, sessão mais recente

`rationale anchors check PATH`

Quais decisões avisariam um agente sobre este arquivo, o essencial de cada uma e o quanto o arquivo mudou desde então

`rationale capture --task HANDLE`

Capturar agora, para uma tarefa; `--dry-run --print-delta` mostra o que seria enviado

`rationale record --title "..." < thread.txt`

Uma thread colada ou notas passam pelo extrator e são registradas como um único turno

`rationale deploy production [--ref REF]`

Informar ao Rationale o que entrou em produção a partir desta máquina: sha, branch, commits

`rationale digest`

Resumir os projetos com resumo pendente, com o seu próprio agente: status, temas, em que ponto estão as tarefas

`rationale pause codex [--hours N]`

Parar de extrair com o seu Codex por um tempo; `rationale resume codex` retoma. Os hooks continuam avisando.

`rationale update [--rollback]`

Verificar a release assinada agora e instalá-la, ou voltar à anterior

`rationale uninstall`

Remover os hooks e o watcher; depois revogue o dispositivo no app

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

Sai da máquina

Nunca sai

As decisões extraídas, com citações curtas das palavras da própria pessoa

A transcrição da sessão

Id da sessão, números dos turnos, remote do repositório, branch, commit, hora e o custo equivalente da extração

Os arquivos do seu repositório: o Rationale guarda caminhos, nunca conteúdo

Os caminhos dos arquivos que um agente lê ou altera, para perguntar quais decisões se aplicam

O conteúdo comparado com os identificadores de uma decisão (lido localmente, no máximo 512 KB)

Um repasse e um resumo do projeto, escritos pelo seu agente

Valores de segredos: recusados no que pessoas e agentes escrevem, removidos das citações

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.

Qualquer outra coisa: [support@rationalehq.com](mailto:support@rationalehq.com)