# Cómo funciona Rationale y qué sale de tu máquina · Rationale > Los cuatro pasos de Rationale en detalle: captura en tu máquina con tu propio agente, el registro de decisiones, contexto por #handle y MCP, avisos antes de la edición. Una tabla con qué sale de tu máquina en cada evento, comprobada contra el código del cliente. Source: https://rationalehq.com/es/how-it-works Language: es Cómo funciona # Cómo funciona Rationale y qué sale de tu máquina Cada paso de Rationale, qué ejecuta en tu máquina y qué sale de ella. La página de inicio muestra los cuatro pasos; esta página dice qué hace cada uno, qué comandos corren, qué hooks se instalan y, para cada evento, qué sale de tu máquina y qué no sale nunca, comprobado contra el código del cliente (0.9.0) y la API con la que habla. Comprobado el 6 de octubre de 2026 · cliente 0.9.0 En resumen - Las decisiones se extraen en la máquina de cada persona con la CLI del agente que ya usa (`claude -p` o `codex exec`). La transcripción va al proveedor de ese agente, como iba de todos modos, y nunca a Rationale. - Rationale recibe las decisiones extraídas, citas breves de las propias palabras de la persona y metadatos: id y título de la sesión, números de turno, repositorio, rama, commit, hora, modelo y costo. - Antes de que un agente edite un archivo, le llegan las decisiones que coinciden. Las rutas se comparan en tu máquina; una ruta que no coincide con nada nunca sale de ella. - Cuatro hooks, escritos una vez en la configuración de Claude Code. `rationale uninstall` los quita. - Claude Code hoy, Codex en beta, cualquier cliente MCP para leer y registrar. Cursor, lo siguiente. En esta página 1. [1 · Captura: cuando termina un turno](#capture) 2. [2 · Registro: qué contiene una decisión](#record) 3. [3 · Dar contexto: #handle, notas y MCP](#context) 4. [4 · Avisar: antes de la edición, no en la revisión](#warn) 5. [Qué sale de tu máquina](#data) 6. [Instalar en dos minutos](#install) 7. [Los hooks, y cómo quitarlos](#hooks) 8. [Agentes y conectores hoy](#agents) ## 1 · Captura: cuando termina un turno Instala el cliente una vez por portátil. Desde entonces, cada vez que tu agente termina un turno, ejecuta el hook `Stop` del cliente (Claude Code; Codex una vez que confías en los hooks). El hook arranca una captura en segundo plano y vuelve de inmediato, así que el agente nunca espera. Un watcher hace lo mismo cada minuto con cualquier turno que un hook se haya saltado: un fallo, una ventana cerrada, una sesión inactiva un minuto con turnos nuevos. La captura lee la transcripción de la sesión en tu máquina y construye un delta compacto de los turnos nuevos: tus mensajes, las respuestas del agente y las herramientas que llamó, con su entrada cortada a 200 caracteres. La salida de las herramientas, el razonamiento y el texto que el agente inyecta por su cuenta se quedan fuera. En un bloque van hasta 120 turnos, con hasta 30 turnos anteriores como contexto de solo lectura, para que un bloque corto no se lea aislado. El delta va a la propia CLI del agente en tu máquina, con tu sesión iniciada: `claude -p` para una sesión de Claude Code, `codex exec` para una de Codex. Una sesión de Codex nunca va a Anthropic, y una de Claude Code nunca va a OpenAI. Para Claude Code la llamada es mínima: un system prompt, un esquema JSON, sin herramientas, sin configuración, sin hooks, sin servidores MCP, sin archivo de sesión, así que nunca aparece en tu historial. Para Codex es el `codex exec` documentado, efímero, de solo lectura, en una carpeta vacía y con los hooks del cliente apagados. Solo se capturan las sesiones en un repositorio que alguno de tus proyectos lista. El cliente le pregunta a Rationale cuál de tus espacios de trabajo lista el remoto git del repositorio y guarda la respuesta diez minutos. Ningún proyecto: no se extrae ni se envía nada. Dos espacios de trabajo: tampoco, y `rationale status` nombra a ambos. Una extracción fallida se reintenta a los 5, 15 y 60 minutos mientras el mismo bloque siga fallando, y nunca bloquea al agente. Lo que llega a Rationale es el resultado: las decisiones, más id y título de la sesión, números de turno, repositorio, rama, commit, la hora del último turno, agente, modelo, duración, tokens y costo equivalente. El endpoint que recibe una captura no tiene ningún campo que pueda llevar una transcripción. ## 2 · Registro: qué contiene una decisión Una decisión no es un resumen de la sesión. Tiene una pregunta, la elección, los criterios que la guiaron con su peso, las opciones descartadas y por qué, supuestos, y qué haría que el equipo la revisara. Está anclada a rutas del repositorio y a identificadores (una clase, una tabla, la clave de un ticket), y dice de qué trata: negocio, producto o técnica. Las propias palabras de la persona que la decidió quedan citadas. Toda decisión se registra como inferida: la extrajo un agente. Pasa a confirmada solo a través de una persona: un clic en la aplicación, sus propias palabras en una sesión (el cliente comprueba la cita contra la transcripción antes de enviarla, así que un agente diciendo que alguien confirmó no basta), o el merge del pull request que la llevaba. Los dos orígenes quedan visibles, y los agentes ven la diferencia. Las decisiones se numeran por espacio de trabajo (D-42), se guardan como versiones inmutables y se cifran en reposo. El servidor lee solo identificadores, estados, anclas y marcas de tiempo. Cada lectura y cada confirmación se escribe en el registro de auditoría del espacio de trabajo. El extractor también informa cuando la persona confirmó, corrigió o retiró una decisión anterior en la conversación, y cuando el agente preguntó por una. Una sesión que no nombró ninguna tarea envía sus decisiones a la bandeja de entrada del proyecto, donde el equipo las vincula, las conserva o las retira. Una repetición de una decisión ya registrada se vincula, no se registra dos veces. ## 3 · Dar contexto: #handle, notas y MCP Una tarea es un `#handle`: un slug legible, único en el espacio de trabajo, al que se adjunta todo: sesiones, decisiones, traspasos, pull requests, tickets. Escríbelo en cualquier prompt y el hook `UserPromptSubmit` envía a Rationale el handle, el repositorio y la rama, nada más del prompt. De vuelta llega el contexto de la tarea: su estado, sus decisiones activas por área, sus últimos traspasos y sus pull requests abiertos. La sesión queda vinculada a la tarea, así que sus capturas posteriores caen ahí. Una rama con el nombre del handle también vincula la sesión, sin escribir nada. Cuando empieza una sesión, el hook `SessionStart` trae tus notas: instrucciones permanentes que diste a tus agentes ("respóndeme en español", "nunca toques los controladores v1") para el espacio de trabajo y el proyecto de este repositorio, en menos de 300 tokens y dos segundos. Para eso solo sale de tu máquina el remoto del repositorio. Los asistentes que no tienen hooks se conectan por MCP: Claude (claude.ai y la aplicación de escritorio), ChatGPT, Cursor, los propios Claude Code y Codex, y cualquier cliente que hable el protocolo. El servidor remoto en `https://mcp.rationalehq.com/mcp` usa OAuth 2.1 con PKCE: pega la URL, inicia sesión una vez, autoriza tus espacios de trabajo. No hay claves de API. Sus herramientas son `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` y `suggest_same_person`; cada una declara si lee o escribe, para que tu cliente pueda preguntarte antes de una escritura. Las decisiones de negocio van primero, planteadas como restricciones que las elecciones de producto y técnicas no anulan. Todo lo que un agente registra por MCP es inferido, con las palabras de la persona citadas, porque nada puede comprobar una conversación que Rationale no vio. ## 4 · Avisar: antes de la edición, no en la revisión El hook `PostToolUse` corre después de cada llamada a una herramienta y termina en unos milisegundos para las herramientas que no vigila. Vigila Read, Edit, Write, MultiEdit y NotebookEdit, y los comandos Bash que nombran un archivo, porque los agentes leen con `cat`, `sed` y `grep` tan a menudo como con Read; para Codex, los comandos de shell y `apply_patch`. Leer es el momento que importa: el modelo todavía tiene que escribir su cambio. El hook guarda un índice de las decisiones ancladas del repositorio, refrescado en segundo plano al empezar la sesión y después de cada turno: de cada decisión su número, rutas, identificadores, área, commit y lo esencial (pregunta y elección). Compara la ruta del archivo con ese índice en tu máquina y, para las decisiones que nombran una clase, una tabla o la clave de un ticket, lee el archivo aquí (texto, 512 KB como máximo) para buscarlas. El contenido nunca sale. Un archivo que no coincide con nada no provoca ninguna petición. Si coincide, una sola petición le pide a Rationale el texto del aviso: el repositorio, la ruta relativa al repositorio, cómo coincidió cada decisión, qué decisiones tiene ya el agente en su contexto y, tras editar un archivo que también cambia el pull request abierto de otra persona, las líneas recién cambiadas. La respuesta llega en menos de dos segundos: como máximo tres decisiones completas y el resto por número, quién decidió cada una, si una persona la confirmó y cuántos commits han tocado el archivo desde entonces. Si Rationale va lento o está caído, el agente recibe lo esencial desde el índice local. Cada aviso mostrado es una lectura auditada. Una vez por archivo y sesión; otra vez si cambian las decisiones. Un archivo cuyas decisiones ya están todas en el contexto del agente no recibe aviso. Es contexto, nunca un bloqueo: el hook nunca cambia los permisos del agente ni lo detiene. Un hook que falla termina en silencio. ## Qué sale de tu máquina Una fila por evento. Cada fila se comprobó contra el código del cliente (rationale-client 0.9.0) y la API que recibe cada petición. Donde corre tu propia CLI, la fila dice qué va al proveedor de tu agente: ese tráfico va a donde ya van tus sesiones, con tu propia cuenta. Cuándo Sale de tu máquina Nunca sale **Termina un turno** (hook `Stop`; el watcher para los turnos perdidos) **Al proveedor de tu agente**, a través de tu propio `claude -p` o `codex exec`: los turnos nuevos en forma compacta (tus mensajes, las respuestas del agente, las herramientas que llamó con su entrada recortada), con hasta 30 turnos anteriores como contexto. **A Rationale**: las decisiones encontradas, con las palabras de la persona citadas y las rutas a las que están ancladas; qué decisiones anteriores confirmó, corrigió o retiró la persona, con la cita y su turno; id y título de la sesión, números de turno, remoto del repositorio, rama, commit, hora del último turno, agente, modelo, duración, tokens, costo equivalente, versión del cliente. La transcripción. La salida de las herramientas y el razonamiento, ni siquiera a tu proveedor. Los valores de secretos: rechazados al escribirlos, tachados de las citas. Una sesión de Codex nunca va a Anthropic; una de Claude Code nunca a OpenAI. **El agente lee o edita un archivo** (`PostToolUse`: Read, Edit, Write, MultiEdit, NotebookEdit, comandos Bash que nombran un archivo; comandos de shell y `apply_patch` en Codex) Nada, salvo que la ruta o el contenido del archivo coincida con el índice local, o la ruta esté en el pull request abierto de un compañero. Entonces, a Rationale: el remoto del repositorio, la ruta relativa al repositorio, cómo coincidió cada decisión (número, tipo, ancla, commits desde entonces), las decisiones que ya están en el contexto del agente, la herramienta, el id de sesión y, tras editar un archivo que está en el pull request de alguien, los rangos de líneas recién cambiados. El contenido del archivo: los identificadores se buscan leyéndolo aquí, 512 KB como máximo. Las rutas que no coinciden con nada. El comando y su salida. **Escribes `#handle` en un prompt** (`UserPromptSubmit`) El handle (hasta tres por prompt), el remoto del repositorio, la rama, el id de sesión, el agente. De vuelta llega el contexto de la tarea. El prompt. Un prompt sin `#handle` no provoca ninguna petición. **Empieza una sesión** (`SessionStart`, también tras `/clear` o una compactación) El remoto del repositorio, el id de sesión y el agente, para traer tus notas (dos segundos como máximo). En segundo plano: el remoto y el digest del índice que guarda, para refrescar las decisiones ancladas (vuelve `unchanged` cuando nada cambió); y el remoto solo, para preguntar qué espacio de trabajo lo lista (en caché diez minutos). La carpeta de trabajo, tus archivos, el entorno. **Un cliente MCP llama a una herramienta** (Claude, ChatGPT, Cursor o cualquier cliente, por `mcp.rationalehq.com`) Lo que el agente pasa a la herramienta: un `#handle`, rutas o refs, el nombre de un proyecto, números de decisión, palabras de búsqueda, o lo que registra (una decisión, un resultado, un traspaso, una nota, una tarea, con las palabras de la persona citadas). Por MCP no hay índice local: las rutas que el agente pasa a `context_for` llegan a Rationale tal cual. Cada decisión leída o escrita es un evento auditado. La conversación. El código. Una consulta de búsqueda no se guarda ni se registra. **Toca un resumen** (el watcher pregunta una vez por hora; una vez al día por proyecto, o tras diez decisiones nuevas) **A Rationale**: una petición de reserva, vacía. Rationale devuelve las tareas del proyecto, los últimos traspasos, los temas anteriores y las decisiones activas en forma breve. **Al proveedor de tu agente**, a través de `claude -p` (o `codex exec` en una máquina sin Claude Code): esa entrada, nunca una transcripción. **A Rationale**: el estado (hecho, en curso, siguiente), los temas con las decisiones que cubre cada uno y dónde los colocó la IA, dónde está cada tarea, tensiones entre decisiones, un área e identificadores para las decisiones que no los tienen, las condiciones de revisión que ahora se cumplen, más modelo, duración, tokens y costo. Transcripciones, código, archivos. **Una sesión se queda en silencio** (el watcher, 30 minutos sin turno nuevo, solo sesiones con decisiones) **Al proveedor de tu agente**: los últimos 60 turnos de la sesión en forma compacta, a través de la misma CLI. **A Rationale**: el traspaso que escribió (resumen, próximos pasos, preguntas abiertas), el id de sesión y el agente. Los turnos en sí. Una sesión sin decisiones no recibe traspaso; una para la que Rationale no tiene tarea no se vuelve a preguntar. **Despliegas** (`rationale deploy production`, opcional, para equipos que despliegan desde sus máquinas) El remoto del repositorio, el entorno, el sha del commit y su rama, hasta 500 shas de commits alcanzables desde él, el nombre de la herramienta. Rationale marca los pull requests y las decisiones que están en producción. Mensajes de commit, diffs, código. **Inicias sesión** (`rationale init`, `rationale login`) El nombre de tu máquina (el nombre del equipo en macOS, si no el hostname) y la versión del cliente, para iniciar el flujo de dispositivo. Introduces un código en el navegador, con tu sesión de Rationale iniciada. El token del dispositivo llega una vez y se guarda legible solo por ti (`~/.config/rationale/config.json`, modo 600). Una contraseña: no hay. Rationale inicia sesión por enlace al correo. **Pegas un hilo** (`rationale record`, un hilo de Slack o las notas de una reunión, opcional) **Al proveedor de tu agente**: el texto, a través del mismo extractor. **A Rationale**: las decisiones encontradas y el título que diste, como una captura de un turno marcada `paste`. El texto en sí. **Cada petición a Rationale** La versión del cliente (`User-Agent`), qué agentes ejecutan sus hooks en esta máquina (`claude_code=4/4, codex=0/4`: nombres y recuentos) y, una vez tras cada actualización, su código de resultado (ok, firma incorrecta, revertida). Como todo servidor, Rationale ve la dirección IP desde la que llega una petición. Con el refresco del índice, contadores por repositorio: lecturas y ediciones comprobadas y coincidentes, repeticiones, tiempos de espera, ids de avisos que el agente citó o siguió con otra edición, tiempos de respuesta. Nada de una sesión. Rutas: los contadores son solo recuentos e ids. **Cada seis horas, la comprobación de actualizaciones** (el watcher, nunca un hook) Un `GET` del manifiesto firmado de la versión y de su firma desde `app.rationalehq.com/client`, que redirige a los archivos en GitHub, con la versión del cliente en el `User-Agent`. El binario se descarga junto al actual, se verifica (firma minisign, tamaño, sha256, una ejecución de `--version` de dos segundos) y se intercambia; el anterior se conserva para `rationale update --rollback`. Nada sobre ti ni sobre tus sesiones. Las instalaciones con Homebrew solo avisan de que hay una versión más nueva. El contenido de las decisiones, las notas y los traspasos se cifra en reposo con claves guardadas aparte de la base de datos. Nuestro personal ve identificadores, estados y anclas, nunca el contenido, y cada vista del personal se escribe en tu registro de auditoría. La [página de seguridad](https://rationalehq.com/es/security) tiene la visión técnica; la [política de privacidad](https://rationalehq.com/es/privacy), la legal. ## Instalar en dos minutos Un comando, sin sudo, macOS o Linux. Deja un binario en `~/.local/bin/rationale` y nada más: todavía sin hooks, sin inicio de sesión. ``` curl -fsSL https://rationalehq.com/install.sh | sh ``` O con Homebrew: ``` brew tap rationalehq/tap https://github.com/jorgebasilio/homebrew-tap brew install rationalehq/tap/rationale ``` Después, dentro de un repositorio que tu espacio de trabajo lista: ``` rationale init ``` 1. **Inicia sesión desde el navegador.** La terminal muestra un código y abre la página de inicio de sesión de la aplicación. Un inicio de sesión por espacio de trabajo; `rationale login` añade otro. 2. **Este repositorio.** Comprueba cuál de tus espacios de trabajo lista el remoto git de este repositorio. Listado por uno: se captura. Por ninguno: lo dice y pregunta si lo acabas de listar. 3. **Agentes en esta máquina.** Escribe los cuatro hooks en el `~/.claude/settings.json` de Claude Code (se guarda una copia de seguridad; tus propias entradas no se tocan) y, si Codex está aquí, en `~/.codex/hooks.json`, y te explica el paso de confianza que Codex exige. Cursor se detecta y se informa, todavía no se captura. 4. **Watcher.** Un job de launchd en macOS, un timer de usuario de systemd en Linux, cada minuto: captura cualquier turno que un hook se saltó, escribe traspasos, ejecuta resúmenes y comprueba actualizaciones. Sin sesión de usuario de systemd, los hooks siguen capturando cada turno. Listo. Trabaja como siempre. `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. Para leer y registrar desde Claude, ChatGPT o Cursor, añade el servidor MCP; la [documentación](https://rationalehq.com/es/docs#mcp) tiene los pasos de cada cliente. Para Claude Code: ``` claude mcp add --scope user --transport http rationale https://mcp.rationalehq.com/mcp ``` ## Los hooks, y cómo quitarlos `rationale init` añade cuatro entradas al objeto `hooks` de `~/.claude/settings.json`. Cada una ejecuta el binario instalado con el nombre del evento; el binario decide qué hacer, así que una actualización nunca reescribe tu configuración. Los tiempos límite son lo máximo que puede tardar un hook; vuelven mucho antes. Hook Se ejecuta cuando Qué hace Límite `Stop` El agente termina un turno Arranca una captura de los turnos nuevos en segundo plano y vuelve 10 s `UserPromptSubmit` Envías un prompt Con un `#handle`: vincula la sesión a la tarea y añade el contexto de la tarea. Si no, nada. 15 s `PostToolUse` Después de cada llamada a una herramienta (sin matcher) Una lectura o edición de un archivo: se compara en local y, si coincide, se añaden las decisiones ancladas. Cualquier otra herramienta: termina de inmediato. 3 s `SessionStart` Una sesión empieza o se reanuda, o tras `/clear` o una compactación Añade tus notas; refresca el índice de anclas en segundo plano 5 s Una entrada se ve así; el comando es la ruta absoluta del binario, nunca una búsqueda en el PATH: ``` "Stop": [{ "hooks": [{ "type": "command", "command": "/Users/you/.local/bin/rationale hook claude-code stop", "timeout": 10 }] }] ``` Un hook nunca bloquea al agente: todo error se absorbe y el hook termina con 0; un fallo grave termina con un código que Claude Code muestra como error no bloqueante. Los hooks no hacen nada en un repositorio que ningún proyecto lista. Para Codex, las cuatro entradas van a `~/.codex/hooks.json`, también sin matcher; Codex las ejecuta solo después de que confíes en ellas (`/hooks` en la CLI, Review hooks en la aplicación), y el cliente nunca escribe esa confianza por ti. Para quitarlo todo: ``` rationale uninstall ``` Quita los cuatro hooks de Claude Code y de Codex, guardando una copia de seguridad de cada archivo de configuración, y quita 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 local en `~/.local/state/rationale/` hasta que los borres; el binario es un solo archivo que puedes eliminar. ## Agentes y conectores hoy Qué está en producción, qué está en beta y qué viene después. Nombramos lo que no cubrimos en vez de darlo por hecho. Agente o herramienta Estado Qué funciona Claude Code En producción Captura tras cada turno, avisos antes de las ediciones (Read, Edit, Write, MultiEdit, NotebookEdit, Bash), contexto por `#handle`, notas al empezar la sesión, traspasos, resúmenes Codex (la CLI, la aplicación de escritorio de ChatGPT y la extensión del IDE) Beta Captura y contexto una vez que confías en los hooks; avisos en comandos de shell y `apply_patch`; extracción con `codex exec` con tu propia cuenta de ChatGPT, que se pausa sola un día si OpenAI informa de actividad inusual Claude (claude.ai y la aplicación de escritorio), ChatGPT, Cursor, cualquier cliente MCP En producción Leer las decisiones de tu equipo y registrar nuevas a través del servidor MCP remoto. Sin captura ni avisos antes de la edición: eso viene de los hooks. Captura en Cursor Siguiente `rationale init` detecta Cursor y lo informa; sus sesiones todavía no se capturan Gemini CLI Siguiente Sin construir GitHub En producción Una GitHub App en las organizaciones que elijas: pull requests, revisiones e issues vinculados a las decisiones de los archivos que cambian; el merge de un pull request confirma las decisiones capturadas en su rama Jira En producción OAuth con tu sitio de Atlassian: tickets y epics se convierten en tareas, las decisiones siguen al ticket Sin tracker En producción Las tareas viven en Rationale; los agentes las abren cuando lo pides Linear, Slack Siguiente Sin construir. Cuéntanos qué usa tu equipo al solicitar acceso. Acceso anticipado: [solicita acceso](https://app.rationalehq.com/request-access) y configuramos tu espacio de trabajo contigo, en un día laborable. Cualquier otra cosa: [support@rationalehq.com](mailto:support@rationalehq.com)