code-quorum

Las revisiones independientes se han convertido en una parte importante de cómo uso herramientas de agentes. Inspirado por trabajos similares, construí Code Quorum para mi propio uso y lo comparto por si a otros les resulta útil.

Code Quorum es un consejo multiagente para macOS para Claude Code y Codex. El host activo escribe su propia revisión, evaluación o plan mientras los asientos externos trabajan en paralelo. Una puerta estructural contra el sesgo mantiene cada perspectiva independiente hasta la síntesis final.

Puede usar suscripciones existentes de Claude Code, ChatGPT/Codex y Gemini/Antigravity. El asiento de OpenCode usa OpenRouter, con DeepSeek V4 Flash como modelo predeterminado. Se admiten ambos hosts CLI, junto con Codex en la aplicación de escritorio de ChatGPT y la superficie de Code en la aplicación de escritorio de Claude.

El host nunca es también un asiento de subproceso. La división inicio/espera requiere que el host forme su propia respuesta antes de que q_await exponga la salida de los pares, y cada habilidad del consejo llama a la notificación de finalización bloqueante en el mismo turno que su inicio.

Los asientos externos son de solo lectura, pero solo lectura no significa datos locales. Revisa Seguridad y límites de datos antes de usar Code Quorum en material privado.

Cada inicio de consejo MCP que lee repositorios requiere un cwd de proyecto absoluto explícito. Las herramientas MCP rechazan un valor omitido o vacío en lugar de recurrir al caché de complementos o al directorio de ejecución del servidor. Las habilidades del host proporcionan este valor durante el uso normal de /q-* y $code-quorum:q-*. Los archivos de plan y alcance también deben resolverse dentro de ese directorio; las rutas absolutas, el recorrido .. y los escapes de enlaces simbólicos se rechazan antes de leer su contenido.

Flujos de trabajo

El host puede seleccionar un flujo de trabajo a partir de una solicitud en lenguaje natural que coincida. Usa los formularios a continuación para seleccionar uno explícitamente:

uv run quorum --help enumera la superficie exacta del shell. Los modificadores principales son:

Fuentes de investigación y credenciales

q-research consulta las seis fuentes por defecto. Repite --source <nombre> para restringir una ejecución.

Code Quorum lee las credenciales del entorno del proceso y envía tokens solo en los encabezados de autorización. El adaptador de Codex generado reenvía las variables nombradas pero no almacena sus valores en el artefacto del complemento. OpenAlex es la única fuente que requiere una clave para el uso normal; las demás mejoran la fiabilidad o los límites de tasa.

Verifica la búsqueda de Hugging Face desde un checkout con:

uv run quorum research "sentence embedding" --source huggingface --limit 5
uv run pytest tests/test_research_live.py -m live -k huggingface -q

La verificación CLI debe devolver enlaces de modelos y un recuento de fuente HuggingFace distinto de cero. Las pruebas en vivo cubren la búsqueda directa, la autenticación con token configurado, la unión de términos distintivos y la ruta completa de research_topic. Sin un token, la prueba de autenticación se omite mientras las comprobaciones anónimas aún se ejecutan.

Requisitos

Code Quorum actualmente es compatible con macOS y requiere Python 3.13+, el gestor de paquetes uv y los binarios de los asientos que pretendas usar. Cada asiento depende de su propio inicio de sesión o clave; Code Quorum no escribe valores de credenciales en los artefactos de los complementos. Los CLI de los asientos conservan su propia autenticación y estado de ejecución como se describe en SECURITY.md.

El asiento de Gemini depende del sandbox Seatbelt de macOS; Claude usa una lista de permitidos de herramientas de lectura en su lugar. Un host de Codex también necesita un helper LaunchAgent de alcance limitado para sus asientos de Claude y Gemini. Codex y OpenCode no tienen dependencia de Seatbelt pero no están probados en otras plataformas.

Instalación

Clona el checkout estable y configura los asientos:

git clone https://github.com/sdewell/code-quorum.git
cd code-quorum
uv sync
agy  # complete Google OAuth login, then exit
uv run quorum setup-agy                    # one-time Gemini seat config
uv run quorum setup-models --host claude   # use --host codex for Codex
uv run quorum doctor --host claude         # or codex / both
uv run quorum auth-check --seat gemini --host claude

doctor verifica binarios, forma de configuración y preparación del sandbox. No prueba credenciales en vivo. auth-check ejecuta agy models dentro del mismo sandbox usado por el asiento y requiere al menos una fila de modelo válida sin enviar un prompt de modelo. Un inicio de sesión faltante o revocado dirige al usuario de vuelta a agy interactivo; Code Quorum nunca cambia silenciosamente a una ruta API medida.

En un host de Codex, instala y verifica el helper desde una terminal real antes de la verificación de autenticación de Codex:

uv run quorum install-seat-helper-launchagent   # --allowed-root <dir> to widen
uv run quorum seat-helper-status
uv run quorum auth-check --seat gemini --host codex

Cada flujo de trabajo MCP permite cwd bajo ~/Code y ~/src por defecto; el helper de Codex aplica las mismas raíces antes de aceptar solicitudes de Claude o Gemini. Establece CODE_QUORUM_HELPER_ALLOWED_ROOTS o instala el helper con opciones repetidas --allowed-root para usar otras raíces de proyecto. Reinstálalo desde el checkout estable actualizado después de cada actualización de Code Quorum. Los protocolos de helper incompatibles fallan de forma segura, y se rechaza la instalación desde el caché de complementos reemplazable de Codex.

Límites de solo lectura

Cada asiento externo es de solo lectura y se niega a ejecutarse si no se puede aplicar su límite. La aplicación difiere según el asiento: Codex usa su sandbox nativo de solo lectura, Claude expone solo herramientas de lectura, Gemini usa Seatbelt de macOS y OpenCode usa un HOME aislado con permisos restringidos.

El perfil Seatbelt de Gemini deniega otras lecturas del directorio de inicio, con excepciones explícitas para la autenticación y el estado de ejecución de agy. No deniega rutas legibles fuera de $HOME. Code Quorum no proporciona una valla de rutas universal para Claude, Codex u OpenCode. El material del consejo puede salir de la máquina bajo las cuentas de proveedor configuradas por el usuario. La tabla completa de límites, el mapa de salida de datos, la guía de aislamiento estricto y el manejo de credenciales están en SECURITY.md.

Datos y aprobaciones en Codex

Codex trata la aprobación de herramientas, la contención del sistema de archivos y la autorización para enviar material fuera de la máquina como decisiones separadas. Un objetivo como main...HEAD limita el diff de revisión preparado; no restringe el acceso de solo lectura de un asiento externo al directorio de trabajo.

Cuando approvals_reviewer = "auto_review" está habilitado, un inicio de consejo puede necesitar autorización explícita que nombre el payload y los destinatarios. Los usuarios que quieren acceso desatendido pueden optar por herramienta, pero Code Quorum nunca escribe esas entradas de aprobación por sí mismo.

SECURITY.md contiene el ejemplo de autorización de una sola vez, los seis bloques de aprobación de Codex (incluida la herramienta compartida q_await), la guía del proyecto AGENTS.md, los límites de confinamiento de rutas y el procedimiento de actualización que preserva las aprobaciones. Revíselo antes de habilitar flujos de trabajo no supervisados.

Configuración

Cada asiento resuelve su modelo a través de una escalera, gana el primer acierto: bandera por ejecución -> variable de entorno -> la elección registrada por quorum setup-models -> el pin incluido. Las elecciones registradas nunca cambian silenciosamente; un asiento que no puede cumplir una falla de forma ruidosa mientras el resto del consejo continúa.

uv run quorum setup-models --host claude
uv run quorum setup-models --seat codex --model gpt-5.6-terra --effort medium

Configuración de OpenCode

El asiento OpenCode requiere OPENROUTER_API_KEY y no carga su configuración personal de OpenCode. Utiliza un HOME aislado y reconstruye esta configuración generada antes de cada ejecución. El modelo incluido es openrouter/deepseek/deepseek-v4-flash; su chunkTimeout de OpenRouter es de 90000 milisegundos.

Code Quorum establece OPENCODE_DISABLE_PROJECT_CONFIG=1 y OPENCODE_PURE=1. El agente del consejo generado solo permite Read, glob y list, deniega herramientas de shell y mutación, bloquea .env y .env.*, y permite .env.example. Las ejecuciones fallidas o vacías escriben capturas de stdout/stderr sin procesar en ~/.cache/code-quorum/opencode-debug a menos que se establezca CODE_QUORUM_OPENCODE_DEBUG=0. El directorio es 0700, los archivos de captura son 0600, el texto del prompt se omite de los metadatos de comandos y solo se conservan las 20 capturas más recientes. Los flujos sin procesar aún pueden contener material revisado. Consulte ARCHITECTURE.md y SECURITY.md para conocer el diseño completo de los límites.

Deshabilitar un asiento

Si una sonda en vivo falla porque un asiento está ausente o desconectado, quorum setup-models puede marcarlo como disabled en models.toml. Los asientos deshabilitados se omiten en la lista predeterminada y doctor los informa, pero una solicitud explícita de --agent <seat> aún los ejecuta.

Instalar como complemento

Claude Code:

/plugin marketplace add sdewell/code-quorum
/plugin install code-quorum@code-quorum

Para la CLI de Claude Code, cargue OPENROUTER_API_KEY y las claves de investigación opcionales antes de iniciar el host. Por ejemplo:

source ~/.zshrc.local
claude

Para la aplicación de escritorio de Claude, haga que las claves estén disponibles para la sesión de inicio de sesión actual de macOS antes de abrirla:

source ~/.zshrc.local
launchctl setenv OPENROUTER_API_KEY "$OPENROUTER_API_KEY"

El valor de launchctl es heredado por cada aplicación lanzada posteriormente hasta que se elimine, se cierre la sesión o la máquina se reinicie. Inicie Claude Code y luego elimine la copia de la sesión de inicio de sesión; la aplicación ya en ejecución conserva su copia para los subprocesos del complemento:

launchctl unsetenv OPENROUTER_API_KEY

Después de instalar o actualizar el complemento, o después de cambiar una clave, salga de Claude Code por completo e inicie una nueva sesión de Claude Code. Una recarga del complemento puede recoger los cambios de código, pero no puede cambiar el entorno heredado por el host en ejecución.

El complemento de Claude inicia su servidor MCP con uv run --directory ${CLAUDE_PLUGIN_ROOT} quorum-mcp, por lo que uv y Python 3.13+ deben estar en PATH.

Codex:

Registre el marketplace público e instale el complemento:

codex plugin marketplace add sdewell/code-quorum --ref main
codex plugin add code-quorum@code-quorum
codex plugin list

Para la aplicación de escritorio de ChatGPT, salga por completo y vuelva a abrir la aplicación después de registrar el marketplace. Abra Plugins, elija Personal, seleccione Code Quorum y haga clic en Instalar.

Después de que cualquiera de las superficies de Codex instale el complemento, prepare el checkout estable desde una terminal real:

uv sync
uv run quorum install-seat-helper-launchagent
uv run quorum seat-helper-status

El lanzador de Codex inicia directamente el .venv preparado de ese checkout. Por lo tanto, el inicio de MCP no depende de una caché de uv escribible, descargas de red ni un entorno dentro del directorio de complemento reemplazable. Después de cada actualización, haga pull del checkout, ejecute uv sync y reinstale el helper antes de iniciar un nuevo hilo de Codex.

En la CLI de Codex, abra /hooks para revisar y confiar en cada hook de comando de code-quorum. Codex omite los hooks del complemento hasta que se confíe en cada hash de definición actual. Una definición cambiada requiere una nueva revisión y confianza para esa definición cambiada.

El lanzador generado recupera los directorios binarios estándar de usuario y Homebrew (~/.local/bin, ~/.opencode/bin, /opt/homebrew/bin y /usr/local/bin) para una aplicación de escritorio con un PATH mínimo.

Para la CLI de Codex, cargue el entorno de claves antes de lanzar Codex. Para la aplicación de escritorio de ChatGPT, establezca las claves en la sesión de inicio de sesión actual de macOS:

source ~/.zshrc.local
launchctl setenv OPENROUTER_API_KEY "$OPENROUTER_API_KEY"

El valor es visible para cada aplicación lanzada posteriormente hasta que se elimine. Inicie Codex y luego elimine la copia de la sesión de inicio de sesión; la aplicación en ejecución conserva el valor que ya heredó:

launchctl unsetenv OPENROUTER_API_KEY

Después de una actualización del complemento o un cambio de clave, salga por completo y vuelva a abrir Codex e inicie un hilo de Codex completamente nuevo. No reanude un hilo creado antes del reinicio; su registro de herramientas puede seguir refiriéndose al proceso de complemento anterior.

Para actualizaciones que preservan las aprobaciones, nunca use codex plugin remove como ruta normal. Siga la secuencia verificada en SECURITY.md.

Diseño

ARCHITECTURE.md describe el núcleo compartido CLI/MCP, los adaptadores de asiento, el modelo de rondas, los mecanismos contra sesgos, el empaquetado y los límites de fallo. La versión corta: la ronda 1 no contiene salida de pares, las rondas posteriores anonimizan a los pares por postura, y el host no recibe la matriz del consejo hasta q_await.

Atribución

Estos proyectos inspiraron la forma del flujo de trabajo; no se copió código, prompts ni documentación:

• SnakeO/claude-co-commands - trabajo de host independiente antes de la salida de pares.

• agentic-box/owlex - arquitectura de consejo multiagente y roles cognitivos.

• karpathy/llm-council - revisión de pares anonimizada por contenido en lugar de identidad del modelo.

Licencia

MIT.