Instala Rationale y conecta tus agentes

Cómo encajan las piezas

Rationale tiene tres partes. Un cliente en la máquina de cada persona: un solo binario, sin runtime, que escucha las sesiones de esa persona con su agente. La aplicación en app.rationalehq.com, donde viven las decisiones, las tareas y los registros de auditoría y donde el equipo inicia sesión. Y un servidor MCP remoto en mcp.rationalehq.com, a través del cual asistentes como Claude, ChatGPT y Cursor leen y registran decisiones.

El cliente extrae las decisiones con el agente en el que la persona ya tiene la sesión iniciada (claude -p para Claude Code, codex exec para Codex), en esa misma máquina. Rationale recibe las decisiones extraídas, citas breves y metadatos: id de sesión, números de turno, repositorio, rama, hora. La transcripción nunca sale de la máquina, salvo hacia el proveedor del propio agente, como siempre ha ocurrido.

Antes de empezar

• macOS (un binario universal) o Linux en x86_64 o arm64. Windows todavía no tiene soporte: el instalador lo dice y se detiene.
• Claude Code o Codex con la sesión iniciada en la máquina. El cliente usa esa CLI para extraer las decisiones, con el plan de la propia persona; nunca necesita una clave de API propia.
• Un espacio de trabajo en Rationale. Estamos en acceso anticipado: solicita acceso y configuramos el espacio de trabajo contigo en un día laborable.
• Un proyecto en el espacio de trabajo que liste el remoto git de cada repositorio que quieras capturar. El cliente enruta cada sesión por ese remoto; un repositorio que ningún proyecto lista nunca se captura.
• curl o wget, y sha256sum o shasum, que vienen en cualquier macOS y Linux.

Instala el cliente

Un comando, sin sudo:

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

El instalador deja un solo binario en ~/.local/bin/rationale. Descarga junto al binario, comprueba el tamaño y el sha256 contra el manifiesto de versiones, ejecuta rationale --version y lo renombra a su sitio. Nunca edita los archivos de tu shell: si ~/.local/bin no está en tu PATH, imprime la línea que hay que añadir. No inicia ninguna sesión ni instala hooks; eso lo hace rationale init, a continuación.

O bien, con Homebrew:

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

La primera instalación confía en el TLS del servidor de archivos, como cualquier curl | sh. Cada actualización posterior la verifica el propio cliente contra un manifiesto de versiones firmado (ver Actualizaciones, rollback, desinstalación).

Inicia sesión y configura: rationale init

Ejecútalo una vez por máquina, dentro de un repositorio que tu espacio de trabajo liste:

rationale init

1. Inicio de sesión. Abre el navegador con un código corto (el flujo de dispositivo). Inicias sesión en Rationale y la máquina obtiene su propio token, guardado en ~/.config/rationale/config.json (modo 600). Un inicio de sesión por espacio de trabajo; rationale login añade otro.
2. Comprobación del repositorio. Pregunta cuál de tus espacios de trabajo tiene un proyecto que liste el remoto git de este repositorio. Exactamente uno: se captura ahí. Ninguno: no se captura, y lo dice. Dos: no se captura, y rationale status nombra los dos. Nunca adivina.
3. Hooks. Para Claude Code escribe cuatro entradas en ~/.claude/settings.json (se guarda una copia de seguridad y tus propias entradas no se tocan): Stop, UserPromptSubmit, SessionStart y PostToolUse. Para Codex añade cuatro entradas en ~/.codex/hooks.json; Codex ejecuta un hook solo después de que confíes en él (/hooks en la CLI, o Review hooks en la aplicación), e init y status te lo indican hasta que esté hecho.
4. Watcher. En macOS un job de launchd (~/Library/LaunchAgents/com.rationalehq.client.watcher.plist), en Linux un timer de usuario de systemd (rationale-watcher.timer), cada minuto: capturas, traspasos, resúmenes y actualizaciones. Sin sesión de usuario de systemd, init lo dice, y los hooks siguen capturando cada turno.

rationale status muestra los inicios de sesión, el espacio de trabajo de este repositorio, los hooks, el watcher y la última sesión, en cualquier momento.

Qué pasa mientras trabajas

• Captura. Cuando una sesión termina (el hook Stop de Claude Code, o el watcher en el caso de Codex), el cliente construye un delta compacto de los turnos nuevos, sin salida de herramientas ni razonamiento, y le pide a tu agente que extraiga las decisiones: pregunta, elección, criterios, qué se descartó, cuándo revisarla, los archivos y la tarea a los que se refiere, y las propias palabras de la persona que confirman, corrigen o retiran una anterior. Una extracción fallida se reintenta más tarde y nunca bloquea al agente.
• Avisos antes de la edición. Cuando el agente lee o está a punto de cambiar un archivo al que hay una decisión anclada, el hook le pide a Rationale esas decisiones con un presupuesto de dos segundos y se las muestra al agente antes de la edición: quién decidió, lo esencial y cuántos commits han tocado el archivo desde entonces. Si el servidor va lento, el agente recibe lo esencial desde un índice local. Una decisión que nombra una clase, una tabla o la clave de un ticket se busca dentro del contenido del archivo en tu máquina; ese contenido nunca sale de ella.
• Contexto de una tarea. Escribe el #handle de una tarea en un prompt y el agente arranca con lo que se decidió en ella, quién está en ella y los pull requests abiertos.
• Notas al empezar la sesión. Tus notas del repositorio, del espacio de trabajo y del proyecto llegan al agente cuando empieza una sesión.
• Traspasos. Una sesión con decisiones que lleva 30 minutos en silencio recibe un traspaso escrito para quien retome la tarea: resumen, próximos pasos, preguntas abiertas.
• Nunca estorba. Un hook que falla termina en silencio y deja que el agente continúe. Nada espera a la red salvo el aviso, que tiene su presupuesto.

Comandos

Conecta Claude, ChatGPT, Cursor y otros asistentes (MCP)

Los asistentes que hablan el Model Context Protocol leen las decisiones de tu equipo y registran nuevas a través del servidor remoto en https://mcp.rationalehq.com/mcp. Usa OAuth 2.1: pega la URL, inicia sesión una vez en el navegador y autoriza tus espacios de trabajo. Cada herramienta dice si lee o escribe: context_for, list_tasks, record_decision, record_handoff, record_note, pull_request_for y algunas más.

• Claude Code: claude mcp add --scope user --transport http rationale https://mcp.rationalehq.com/mcp, y después el inicio de sesión en el navegador que abre Claude Code.
• Codex: codex mcp add rationale --url https://mcp.rationalehq.com/mcp, y después codex mcp login rationale.
• Claude (claude.ai y la aplicación de escritorio): Settings → Connectors → Add custom connector, con la URL de arriba. Inicia sesión cuando Claude te lo pida.
• ChatGPT: Settings → Connectors → Create, con la URL de arriba (los conectores personalizados necesitan un plan que los permita). Inicia sesión cuando ChatGPT te lo pida.
• Cursor y otros clientes MCP: añade un servidor con esa URL en la configuración MCP del cliente (en Cursor, ~/.cursor/mcp.json) e inicia sesión cuando te lo pida.

Un proyecto puede fijar su espacio de trabajo con ?workspace=slug en la URL. La página Get started de la aplicación muestra los mismos comandos con tus datos ya rellenados.

Conecta GitHub y Jira

En la aplicación, Settings → Connectors. GitHub se instala como una GitHub App en las organizaciones que elijas; Jira se conecta por OAuth a tu sitio de Atlassian. Los dos son por miembro: cada persona ve en Rationale solo los repositorios, pull requests, tickets y proyectos que su propia cuenta puede ver.

Los pull requests, las revisiones y los issues se enlazan a las decisiones que rigen los archivos que cambian. Los tickets y las épicas de Jira se convierten en tareas, y las decisiones siguen al ticket. Sin tracker, las tareas viven en Rationale y los agentes las abren cuando se lo pides.

Qué sale de tu máquina y qué no sale nunca

La extracción, los traspasos y los resúmenes corren con tu propio agente y tu propio plan, así que el costo queda de tu lado y visible: cada captura lleva su costo equivalente. El cliente informa del resultado de una actualización (ok, firma incorrecta, revertida) como un código en su siguiente petición, nunca como un log.

Actualizaciones, rollback, desinstalación

El watcher, nunca un hook, comprueba el manifiesto de versiones firmado como máximo cada seis horas y sustituye el binario en su sitio, conservando el anterior. Cada binario lleva compiladas dos claves públicas de minisign: una clave de versiones que firma cada manifiesto, y una clave de respaldo offline que se usa solo para rotar la primera. Un manifiesto que ninguna de las dos firmó se rechaza; también uno repetido (replay). Las instalaciones con Homebrew solo dicen que existe una versión más nueva.

rationale update
rationale update --rollback

Para irte: rationale uninstall quita los hooks y el watcher; después revoca el dispositivo en la página Devices de la aplicación, lo que invalida su token. La configuración se queda en ~/.config/rationale/ y el estado en ~/.local/state/rationale/ hasta que los borres.

Cuando algo no cuadra

• rationale: command not found: ~/.local/bin no está en tu PATH; el instalador imprimió la línea que hay que añadir al perfil de tu shell.
• Las sesiones no se capturan: ejecuta rationale status. El remoto del repositorio debe estar listado por exactamente un proyecto en uno de tus espacios de trabajo; si dos espacios de trabajo lo reclaman, la captura se detiene hasta que uno lo suelte. Los hooks de Codex capturan solo cuando confías en ellos.
• Los avisos no aparecen: el hook tiene un presupuesto de dos segundos y desiste en silencio con una red lenta; el siguiente lo vuelve a intentar. rationale anchors check PATH muestra lo que un hook diría para un archivo.
• Proxy corporativo: el cliente usa el almacén de certificados de tu plataforma, así que un proxy con su propio certificado raíz funciona sin configuración.
• Cualquier otra cosa: support@rationalehq.com, con la salida de rationale status. No contiene ninguna transcripción ni texto de decisiones.