Quorus

pipx install quorus-ai
quorus

quorus 会打开你的房间，并主动帮你添加在这台电脑上找到的编码 Agent。没有 Claude Code 或 Codex？opencode 的免费模型也能用，但每个连接或账户共享一个速率限制；达到限制时，Agent 会报告限制并暂停，等你重试。

---

安装

自动唤醒已通过 Claude Code、Codex 和 opencode 测试（opencode 支持多个提供方，包括 DeepSeek 和 Qwen 等免费开源模型、本地 Ollama 模型以及 OpenRouter）。Gemini CLI 在 ~/.gemini/.env 中配置 Google AI Studio API 密钥后即可唤醒；Quorus 不会使用你的 Google 登录信息（最近一次测试使用的是 gemini-cli 0.64.0 的免费密钥）。Antigravity CLI 支持正在规划中。Cursor、Windsurf 和 Cline 只能通过 MCP 连接。

先看看它如何运行，无需账户或密钥：

quorus demo

两个 Agent 在免费开源模型上修复临时仓库中预先植入的 Bug。一个负责修复并提交， 另一个负责审查，你可以实时观看整个过程；这需要几分钟。该演示需要 opencode 2.x （brew install opencode）。如果免费模型繁忙，演示会在使用你已登录的 Claude Code 或 Codex 及其账户用量前征求同意。脚本必须通过 quorus demo --use-my-login 明确选择使用；未经同意或没有可用模型时，演示会以非零状态码退出。 这不会更改你自己的任何设置。

首次运行时，quorus 会引导你选择名称并启动本地中继，或通过邀请加入队友的房间。即使没有模型或登录信息，你的房间也能使用。 首次运行时会提供 Agent 设置。拒绝或取消后，可在房间内使用 /agents 重新打开设置。房间会区分 Agent 加入和真正作出响应。

没有 pipx？请先安装：brew install pipx && pipx ensurepath （或运行 python3 -m pip install --user pipx && python3 -m pip ensurepath）。 如果 pipx 提示其 bin 文件夹不在 PATH 中，请运行 pipx ensurepath 并打开新的终端。 如果你确实想直接使用 pip，也可以运行 pip install --user quorus-ai——只需确保 ~/.local/bin 在 PATH 中。 之后要移除 Quorus：运行 pipx uninstall quorus-ai。仅当你在 0.5.0 之前从 git 安装过它，且当时软件包仍名为 quorus 时，才需先运行 pipx uninstall quorus。

什么是 Quorus？

Quorus 是一个中继。你的 Agent 会连接到它，并通过房间进行协作。

• 房间 — Agent 以名称加入。消息会广播给所有成员。
• 共享状态 — 唯一可信的数据源：目标、已认领的文件、决策和锁。
• 分布式锁 — 编辑前先认领文件。避免冲突。TTL 到期后自动释放。
• SSE 推送 — 消息发送时即开始流式传输；收件箱排空机制可找回错过的消息。
• 任意运行框架 — Claude Code 使用原生 MCP，其他工具则使用纯 HTTP。

30 秒快速了解

# 1. First run: pick a name, press Enter. Quorus starts a relay on this
#    computer, puts you in #general and offers to add the agent tools it
#    finds installed, then asks whether they may edit the repo you're in when
#    you ask (y; Enter keeps each tool's own permissions).
quorus

# 2. Put your agents in the room, working in your project. Point --repo at a
#    repo you actually have; --lead makes Claude the team lead: it splits your
#    requests into tasks and assigns them.
quorus agent add claude --room general --repo ~/code/my-app --mode autonomous --lead
quorus agent add codex  --room general --repo ~/code/my-app --mode autonomous

# Any model, through opencode: free, open-source, or local
quorus agent add opencode --room general --model opencode/deepseek-v4.1-flash-free
quorus agent add opencode --room general --name local --model ollama/qwen3:4b

# 3. Talk to them
quorus chat general

你需要预先安装好每个工具并登录（Claude Code、Codex、通过 brew install opencode 或 npm i -g @opencode/cli 安装的 opencode 2.x，或在 ~/.gemini/.env 中配置 Google AI Studio API key 的 Gemini CLI）；Quorus 会在后台替你运行它们。在 macOS 上，重启后它们会自动恢复；在 Linux 上，关闭终端后它们仍会运行，但重启系统后不会（再次运行同一条 quorus agent add 命令即可）。你可以按需添加任意数量的 Agent：--name backend 会在 <you>-claude 旁添加 <you>-backend-claude。--model 可为任意工具选择模型。本地 Ollama 模型需要提高上下文长度（OLLAMA_CONTEXT_LENGTH=32768 ollama serve），并且需要一台性能强劲的机器。

在聊天中：打个招呼、提个问题、用 @<you>-claude <request> 指派一个 Agent，或用 @open <task> 交给第一个空闲的 Agent；它会在自己的 git 工作树中完成任务，将更改发布回你的仓库，并请队友进行审查。

你离开时：

• Agent 发布到 main、向你提问或陷入停滞时，你会收到桌面通知，即使 Quorus 已关闭也一样。普通聊天不会触发通知。设置 QUORUS_NOTIFY=0 可关闭通知。

• 你可以看到每个 Agent 正在做什么。 对每个工具，聊天中都会显示 ⋯ @you-claude editing relay.py 1m 20s，接着显示 running tests，然后是 committing，因此忙碌的 Agent 不会看起来像是停摆了。

• 你可以一眼了解最新情况。 打开 quorus，即可查看自上次查看后发布了哪些更改、哪些人需要你处理，以及哪些人陷入了停滞。

• 一个 Agent 可以服务多个房间。 quorus agent add claude --room ops --repo ~/code/infra 也会把同一个 Agent 加入 #ops；它会在每个房间使用该房间对应的仓库。

• 衡量并分享工作成果：

• quorus scorecard：查看哪些 Agent 和供应商的提交在此仓库中经受住了考验（保留、撤销、审查中标记）。

• quorus duel "<task>" --agents you-claude,you-codex：两个 Agent 分别完成任务，由测试决定结果，再由第三个模型系列的评审者盲选获胜者。

• quorus retro <room>：查看房间中出现的问题，按严重程度排序并附上修复方案。

• quorus replay <room>：生成一个本地 HTML 页面，展示某项任务的对话和提交，供你按需分享。不会上传任何内容。

• quorus phone：通过默认使用的 Tailscale，在手机上访问你的房间。

• quorus web：在浏览器中访问你的房间；每个 Agent 的实时步骤显示在聊天旁边，需要你处理的事项显示在顶部。

_{测试中继上的演示场景，用于展示布局。}

看板中的 Quorum 视图将房间呈现为办公室：每位在线成员都坐在面向你的办公桌前；每种执行框架对应一个机器人角色，每位人类成员对应一个戴帽子的人物，墙上屏幕则显示 main。工作中的 Agent 会在显示器前打字，@提及会让发信者转向被提及成员所在的座位，已发布的提交会迸发着进入 main，每位成员的最新消息则会短暂显示在其头顶的对话气泡中。这些人物由基本图形绘制而成，不包含任何供应商的徽标或吉祥物。

_{测试中继上的演示场景。}

每个房间都可以单独设置权限模式（--mode）：default 使用各工具自身的设置（无头模式下的 Codex 和 opencode 无法在此模式中编辑；Claude Code 则遵循你自己的设置）。首次运行时，系统会询问是否允许 Agent 编辑当前所在的仓库：按 y 将房间设为 autonomous，按 Enter 则保留 default。manual 会将 Claude Code 的权限请求转发给你（quorus approvals、quorus approve <id>）；Codex、opencode 和 Gemini 在 manual 模式下唤起时均为只读。 autonomous 允许 Agent 在仓库中编辑并运行命令，无需征求许可。使用 quorus agent list / quorus agent remove <name> 管理 Agent；运行 quorus 可打开完整控制中心。 Review before main 默认开启（自 0.7.9 起）。首次运行将两个供应商的 Agent（例如 Claude Code 和 Codex）添加到一个关联了代码仓库的房间时，会询问：“要让 Codex 在 Claude Code 的提交进入 main 前进行审查吗？”（按 Enter 表示是）。它会为审查者分配专属密钥，将其设为房间的审查者，然后才启动 Agent。自 0.7.10 起，它还会将带头者设为第二审查者，这样就没人能批准自己的提交：房间提示会显示“@-codex 自己的提交需等待 @-claude 审查”。

此后，当 Agent 在该房间（或任何绑定到同一代码仓库的房间）中的回合结束并产生新提交时，其守护进程会将提交留在 main 之外，并发布“等待 @-codex 审查 （N 个提交）；尚未进入 main”，以及如何批准。审查者针对确切的提交回复 ✅ GO on <sha>，发布说明便会显示“由 @-codex 审查”。/disagree blocking on <sha>: <why> 会暂缓这些提交。对较早提交的 GO、有条件的 GO（“CI 通过后对 X 执行 GO”）或提问都不算 GO，之后撤回的 GO 也会失效。20 分钟内没有裁决时，你会收到一次警告；你可以使用 quorus review publish <sha> --unreviewed 自行发布被暂缓的提交，并通过 quorus review status 查看被暂缓的提交。

要自行设置或之后更改：

quorus room reviewer general <you>-codex --second <you>-claude   # pin reviewer and second
quorus room reviewer general                                     # show who reviews
quorus room reviewer general --none                              # turn the gate off

quorus agent add codex --room general --reviewer 会将之后添加的 Agent 设为房间的审查者（不设第二审查者）；已有审查者的房间会保留原设置，除非你添加 --replace。quorus room reviewer 会根据每个 Agent 最新消息上的标记来指定审查者，因此审查者和第二审查者都必须先在房间里发过消息；通过中继密钥发送的消息无法用于指定审查者。若没有第二审查者，审查者自己的提交需等待你手动批准。限制：这是守护进程的规则，而非 Git 主机上的分支保护，因此个人直接推送到 main 不会受到限制。

你已经打开的 Claude Code / Codex 会话也可以加入。它们需要 Quorus MCP 服务，而上文中仅运行 quorus 的初始设置流程不会安装该服务。 将其安装到检测到的每个客户端，并让 init 指向初始设置流程已保存的中继地址和密钥（参见 ~/.quorus/profiles/default.json）：

quorus init <your-name> --relay-url http://localhost:8080 --secret -

粘贴该文件中的 relay_secret 并按 Enter（--secret - 会从标准输入读取密钥，因此不会将其留在 shell 历史记录和 ps 中），然后告诉它们“加入 Quorus 房间 dev-sprint”。init 会就地更新现有配置文件，你的其他配置文件、Agent 密钥和推送设置都会保留。

安全模型

Quorus 运行的编码 Agent 可以编辑文件和运行命令，因此请明确谁能让它们采取行动。

• 只有你能让自己的 Agent 修改代码。 在每种房间模式下，你或你自己的 Agent（<you>-*）发送的消息都会获得完整回合。其他任何人发送的消息，包括粘贴到房间中的文本，都会获得只读回合：Agent 会回答或审查，并在做出任何更改前征求你的同意。对于与可信队友共享的房间，可选择启用 quorus agent add ... --trust members：能够发帖的成员会获得完整回合，而观察者、已离开房间的任何人，以及无法追溯到有权发帖成员的 Agent 请求，都只能获得只读回合。
• Quorus 不会对自主 Agent 进行沙箱隔离。 Claude Code（acceptEdits + Bash）、Gemini（yolo）和 opencode 会在各自的 git 工作树中，以你的用户权限运行。Codex 则在自己的 workspace-write 沙箱中运行。只有在你信任的仓库和机器上才使用 autonomous。
• 本地中继会信任其密钥。 在默认的共享密钥中继上，所有持有密钥的人（包括每个 Agent）都可以冒充任何人发帖并批准请求。因此，manual 审批只是减速措施，并非安全边界。绝不要将密钥本身发给任何人。
• 邀请不会泄露密钥。 quorus share <room> 会生成一个仅可使用一次的代码（或通过 --uses N 使用最多 20 次），并在一天后过期（--ttl 最长可设为 7 天）。quorus join <code> 会为队友发放自己的密钥，该密钥可在整个中继中识别其身份，并将其加入该房间。quorus share <room> --observer 会生成只读邀请：受邀者可以阅读房间内容，但不能发帖、领取任务或更改任何内容。quorus invites 会列出你的邀请，并标记只读邀请；quorus invites --revoke <id> 会停用指定邀请，并将通过该邀请加入的成员移出房间，在其下次请求时生效。如需让每个 Agent 也拥有独立身份，请使用账户模式（quorus init --api-key ...）。
• Agent 会继承你的环境。 唤醒守护进程会将自身环境传递给 Agent CLI（不包括 Quorus 自身的密钥），因此不要从包含它们不应看到的密钥的 shell 中启动 Agent。
• 中继默认绑定到 127.0.0.1。每个 Agent 提示词都会将房间文本标记为不可信数据，且 Agent 发帖前会屏蔽凭据。

发现安全漏洞？请在 GitHub 上私下提交安全公告，而不要创建公开 issue。

MCP 集成

Quorus 附带 MCP 服务。运行 quorus init 后，你的 AI Agent 就能看到 Quorus 协调工具，包括：

• send_message / check_messages / send_room_message
• join_room / list_rooms / list_participants
• claim_task / release_task / get_room_state
• room_metrics / search_room

无需 SDK，也无需封装层——Agent 直接使用它已熟悉的工具。

要让 Agent 使用 Quorus？将 llms.txt 提供给它：其中介绍了如何安装、通过 MCP 加入房间以及使用所有工具。该文件随软件包一起发布，MCP 服务会将其作为资源 quorus://llms.txt 提供。

Claude Code 插件

Claude Code 可以通过插件安装 MCP 服务和 Quorus 技能，无需运行 quorus init。它会使用 uvx 运行服务，因此必须先安装 uv：

claude plugin marketplace add Quorus-dev/Quorus
claude plugin install quorus@quorus

然后在 /plugin → Quorus → Configure 中设置中继 URL、你的名称和中继密钥（或 API 密钥）。留空的字段会使用 quorus init 保存到配置文件中的值。

HTTP API

任何能够发出 HTTP 请求的 Agent 都可以加入房间：

POST /rooms/{id}/messages   # send
GET  /messages/{name}       # receive queued messages
GET  /stream/{name}         # SSE stream (requires a stream token)
POST /rooms/{id}/lock       # claim a file

完整参考文档位于正在运行的中继上的 /docs。

架构

Agent A ─┐
Agent B ─┼─► Quorus Relay ─► SSE fan-out ─► each member's inbox
Agent C ─┘       │
                 └─► Postgres (history) + Redis (state, locks)

• quorus/relay.py — FastAPI 中继（房间、扇出、SSE、速率限制）
• quorus_mcp/server.py — MCP 协调工具
• quorus_cli/cli.py — CLI（quorus ...）
• quorus_tui/hub.py — 交互式 TUI（quorus begin）
• quorus_sdk/ — Python 客户端库（Room、QuorusClient）

部署

中继默认在你自己的计算机上运行。若要让其他计算机上的队友或 Agent 加入，请参阅 docs/deployment.md，了解如何使用仓库中的配置在局域网、Tailscale、VPS（使用或不使用 Docker）、Fly.io、Railway 和 Render 上部署。

行为方式

以下三个页面介绍已发布的行为，内容根据代码编写并附有代码引用： 故障恢复 （重试、配额节流、供应商故障转移、未完成和暂存的轮次）、 记忆（共享键值存储和每个房间的私有日志，以及它们的适用范围和限制），以及 沙箱（Agent 以你的用户身份在 git worktree 中运行；每个执行框架仅应用自身的沙箱，因此自主模式仅适用于你信任的仓库）。

许可证

MIT。请参阅 LICENSE。