code-quorum

独立评审已成为我使用代理工具的重要部分。受类似工作的启发，我构建了 Code Quorum 供自己使用，并分享出来，希望其他人也能觉得有用。

Code Quorum 是一个面向 Claude Code 和 Codex 的 macOS 多代理评审团。活动主机自行撰写评审、评估或计划，而外部席位并行工作。结构性的反偏见门控确保每个视角在最终综合之前保持独立。

它可以使用现有的 Claude Code、ChatGPT/Codex 和 Gemini/Antigravity 订阅。OpenCode 席位使用 OpenRouter，默认模型为 DeepSeek V4 Flash。支持两种 CLI 主机，以及 ChatGPT 桌面应用中的 Codex 和 Claude 桌面应用中的 Code 界面。

主机永远不会同时作为子进程席位。启动/等待分离要求主机在 q_await 暴露同行输出之前形成自己的答案，并且每个评审团技能都在其启动的同一轮次中调用阻塞式完成通知。

外部席位是只读的，但只读并不意味着数据本地化。在私有材料上使用 Code Quorum 之前，请查看安全与数据边界。

每次读取仓库的 MCP 评审团启动都需要显式的绝对项目 cwd。MCP 工具会拒绝缺失或空值，而不是回退到服务器的插件缓存或运行时目录。主机技能在正常的 /q-* 和 $code-quorum:q-* 使用中提供此值。计划和范围文件也必须在该目录内解析；绝对路径、.. 遍历和符号链接逃逸在读取其内容之前会被拒绝。

工作流

主机可以从匹配的通俗语言请求中选择工作流。使用以下形式显式选择：

uv run quorum --help 列出确切的 Shell 界面。主要修饰符如下：

研究来源和凭据

q-research 默认查询所有六个来源。重复使用 --source <name> 来限制运行。

Code Quorum 从进程环境读取凭据，并仅在授权标头中发送令牌。生成的 Codex 适配器转发命名变量，但不会将其值存储在插件工件中。OpenAlex 是唯一在正常使用中需要密钥的来源；其他来源则提高可靠性或速率限制。

从检出中验证 Hugging Face 搜索：

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

CLI 检查必须返回模型链接和非零的 HuggingFace 来源计数。实时测试涵盖直接搜索、配置令牌认证、独特术语联合以及完整的 research_topic 路径。如果没有令牌，认证测试会跳过，而匿名检查仍会运行。

要求

Code Quorum 目前支持 macOS，需要 Python 3.13+、uv 包管理器以及你打算使用的席位的二进制文件。每个席位依赖其自身的登录或密钥；Code Quorum 不会将凭据值写入插件工件。席位 CLI 保留其自身的认证和运行时状态，如 SECURITY.md 所述。

Gemini 席位依赖 macOS Seatbelt 沙箱；Claude 使用读取工具允许列表。Codex 主机还需要一个范围狭窄的 LaunchAgent 辅助程序来支持其 Claude 和 Gemini 席位。Codex 和 OpenCode 没有 Seatbelt 依赖，但在其他平台上未测试。

安装

克隆稳定检出并配置席位：

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 检查二进制文件、配置形状和沙箱就绪状态。它不测试实时凭据。auth-check 在席位使用的同一沙箱中运行 agy models，并且要求至少有一个有效的模型行，而不发送模型提示。缺失或撤销的登录会将用户引导回交互式 agy；Code Quorum 永远不会静默切换到按量 API 路由。

在 Codex 主机上，在 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

每个 MCP 工作流默认允许 ~/Code 和 ~/src 下的 cwd；Codex 辅助程序在接受 Claude 或 Gemini 请求之前应用相同的根目录。设置 CODE_QUORUM_HELPER_ALLOWED_ROOTS 或使用重复的 --allowed-root 选项安装辅助程序，以使用其他项目根目录。每次 Code Quorum 升级后，从更新的稳定检出重新安装它。不兼容的辅助程序协议会失败关闭，并且从 Codex 的可替换插件缓存安装会被拒绝。

只读边界

每个外部席位都是只读的，如果无法应用其边界，则拒绝运行。执行方式因席位而异：Codex 使用其原生只读沙箱，Claude 仅暴露读取工具，Gemini 使用 macOS Seatbelt，OpenCode 使用具有受限权限的隔离 HOME。

Gemini 的 Seatbelt 配置文件拒绝读取其他主目录，但明确允许 agy 认证和运行时状态。它不拒绝 $HOME 之外的可读路径。Code Quorum 不为 Claude、Codex 或 OpenCode 提供通用路径围栏。评审团材料可以在用户配置的提供商账户下离开机器。完整的边界表、数据出口映射、严格隔离指南和凭据处理见 SECURITY.md。

Codex 上的数据和审批

Codex 将工具审批、文件系统包含和授权将材料发送到机器外视为独立决策。诸如 main...HEAD 之类的目标限制了准备好的评审差异；它不限制外部席位对工作目录的只读访问。

当启用 approvals_reviewer = "auto_review" 时，评审团启动可能需要显式授权，指明负载和接收者。希望无人值守访问的用户可以按工具选择加入，但 Code Quorum 永远不会自行写入这些审批条目。

SECURITY.md 包含一次性授权示例、全部六个 Codex 审批块（包括共享的 q_await 工具）、项目 AGENTS.md 指南、路径限制以及保留审批的更新流程。在启用无人值守工作流之前，请先审阅它。

配置

每个席位通过一个阶梯解析其模型，先命中者优先：每次运行的标志 -> 环境变量 -> quorum setup-models 记录的选项 -> 随附的固定值。记录的选项不会静默更改；无法满足该选项的席位会大声失败，而其余委员会继续运行。

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

OpenCode 配置

OpenCode 席位需要 OPENROUTER_API_KEY，并且不会加载您的个人 OpenCode 配置。它使用隔离的 HOME，并在每次运行前重建此生成的配置。随附的模型是 openrouter/deepseek/deepseek-v4-flash；其 OpenRouter chunkTimeout 为 90000 毫秒。

Code Quorum 设置 OPENCODE_DISABLE_PROJECT_CONFIG=1 和 OPENCODE_PURE=1。生成的委员会代理仅允许 Read、glob 和 list，拒绝 shell 和变更工具，阻止 .env 和 .env.*，并允许 .env.example。失败或空的运行会将原始 stdout/stderr 捕获写入 ~/.cache/code-quorum/opencode-debug，除非设置了 CODE_QUORUM_OPENCODE_DEBUG=0。目录权限为 0700，捕获文件为 0600，提示文本从命令元数据中省略，并且仅保留最新的 20 个捕获。原始流仍可能包含已审阅的材料。有关完整边界设计，请参阅 ARCHITECTURE.md 和 SECURITY.md。

禁用席位

如果实时探测因席位缺失或已注销而失败，quorum setup-models 可以在 models.toml 中将其标记为 disabled。默认名册会跳过已禁用的席位，并由 doctor 报告，但显式的 --agent <seat> 请求仍会运行它们。

作为插件安装

Claude Code：

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

对于 Claude Code CLI，在启动主机之前加载 OPENROUTER_API_KEY 和可选的研究密钥。例如：

source ~/.zshrc.local
claude

对于 Claude 桌面应用，在打开它之前，将密钥提供给当前 macOS 登录会话：

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

launchctl 值会被随后启动的每个应用程序继承，直到它被取消设置、注销或机器重启。启动 Claude Code，然后移除登录会话副本；已运行的应用会保留其副本以供插件子进程使用：

launchctl unsetenv OPENROUTER_API_KEY

安装或升级插件后，或更改密钥后，请完全退出 Claude Code 并启动新的 Claude Code 会话。插件重载可以获取代码更改，但无法更改运行中主机继承的环境。

Claude 插件使用 uv run --directory ${CLAUDE_PLUGIN_ROOT} quorum-mcp 启动其 MCP 服务器，因此 uv 和 Python 3.13+ 必须位于 PATH 中。

Codex：

注册公共市场并安装插件：

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

对于 ChatGPT 桌面应用，注册市场后完全退出并重新打开应用。打开 插件，选择 个人，选择 Code Quorum，然后点击 安装。

在任一 Codex 界面安装插件后，从真实终端准备稳定检出：

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

Codex 启动器直接启动该检出的已准备 .venv。因此，MCP 启动不依赖于可写的 uv 缓存、网络下载或可替换插件目录内的环境。每次升级后，拉取检出，运行 uv sync，并在启动新的 Codex 线程之前重新安装辅助程序。

在 Codex CLI 中，打开 /hooks 以审阅并信任每个 code-quorum 命令钩子。Codex 会跳过插件钩子，直到每个当前定义哈希被信任。更改的定义需要重新审阅并信任该更改的定义。

生成的启动器为具有最小 PATH 的桌面应用恢复标准用户和 Homebrew 二进制目录（~/.local/bin、~/.opencode/bin、/opt/homebrew/bin 和 /usr/local/bin）。

对于 Codex CLI，在启动 Codex 之前加载密钥环境。对于 ChatGPT 桌面应用，在当前 macOS 登录会话中设置密钥：

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

该值对随后启动的每个应用程序可见，直到它被移除。启动 Codex，然后移除登录会话副本；运行中的应用会保留它已继承的值：

launchctl unsetenv OPENROUTER_API_KEY

插件升级或密钥更改后，完全退出并重新打开 Codex，并启动全新的 Codex 线程。不要恢复重启前创建的线程；其工具注册表可能仍引用先前的插件进程。

对于保留审批的更新，切勿将 codex plugin remove 作为常规路径。请遵循 SECURITY.md 中已验证的序列。

设计

ARCHITECTURE.md 描述了共享的 CLI/MCP 主干、席位适配器、轮次模型、反偏见机制、打包和故障边界。简而言之：第 1 轮不包含同行输出，后续轮次按立场对同行进行匿名化，并且主机在 q_await 之前不会收到委员会矩阵。

致谢

这些项目启发了工作流形态；未复制任何代码、提示或文档：

• SnakeO/claude-co-commands - 在同行输出之前独立的主机工作。

• agentic-box/owlex - 多代理委员会架构和认知角色。

• karpathy/llm-council - 按内容而非模型身份进行匿名同行评审。

许可证

MIT.