AI引擎调度工具

代理多路复用器

内置线束适配器的跨引擎调度层：codex、claude、gemini、experimental agy和Grok Build CLI。一个CLI、一个JSON结果契约、适配器边界等等。

去重写。 agent mux最近从TypeScript重写为Go——静态二进制，基于goroutine的监督，没有运行时依赖关系。 TS版本保留在 agent-mux-ts 支。 看 docs/ 以获取完整的技术参考。

它做什么

AI编码工具（Codex、Claude Code、Gemini CLI、experimental agy和Grok Build CLI）功能强大但相互隔离——每个工具都有自己的CLI标志、事件格式、沙盒模型和会话生命周期。agent mux通过一个JSON合约和提示驱动的工作者身份将它们连接起来。

Workers被定义为具有YAML frontmatter的markdown文件。提示是工人。没有配置文件，没有角色表，没有间接性。

核心原则

1. 工具，而不是编排器。 调用LLM决定做什么。agent mux处理如何做。
2. 完成的工作是神圣的。 工件在超时和进程死亡期间持续存在。每个调度都有一个工件路径。
3. 错误是转向信号。 每个错误都会告诉呼叫者什么失败了，为什么失败，以及下一步要尝试什么。
4. 单镜头，精心策划的背景。 一次及时的派遣击败了一群指定不足的工人。
5. 对配置进行提示。 工人身份存在 .md 具有frontmatter默认值的文件。二进制文件是通用的。
6. 最简单可行的调度。 CLI标志>frontmatter>硬编码默认值。只在需要时升级。

快速开始

包管理器安装：

brew install buildoak/tap/agent-mux
go install github.com/buildoak/agent-mux/cmd/agent-mux@latest

安装任何包管理器后，请从以下步骤开始：

agent-mux onboard

agent-mux onboard --dry-run 解释安装流程，而不更改文件或 派遣工人。它告诉安装代理使用最新的 代理mux技能和参考：

https://github.com/buildoak/agent-mux/tree/main/skill
https://github.com/buildoak/agent-mux/blob/main/skill/SKILL.md
https://github.com/buildoak/agent-mux/blob/main/skill/references/first-run.md
https://github.com/buildoak/agent-mux/blob/main/skill/references/config-and-profiles.md

有关完整的代理首次启动序列，请参阅 技能/参考资料/第一次运行.md.

从签出安装源代码：

git clone https://github.com/buildoak/agent-mux && cd agent-mux
go build -o agent-mux ./cmd/agent-mux
./agent-mux --version

--version 返回包含版本字符串和已安装二进制文件的JSON 出处：解析的可执行路径、Go构建/模块元数据、VCS元数据 如果可用，以及Go版本。

查看有哪些员工可供选择：

./agent-mux config prompts
./agent-mux config prompts --json
./agent-mux config engines
./agent-mux config engines --json
./agent-mux config engines --refresh-models --engine agy --json   # explicit agy model-cache refresh
./agent-mux config engines --refresh-models --engine grok --json  # explicit Grok model-cache refresh

config prompts 反映您的本地 ~/.agent-mux/prompts/ 目录。 config engines --json 是调度验证的主动引擎/模型/能力真实来源。对于Codex，它每个进程查询一次PATH解析的CLI：live codex debug models，在失败时捆绑目录，然后是保守的传统回退。成功的目录会相互替换；他们从来没有联合过。

GPT-5.6 Sol Max和Ultra 需要一个明确的模型和一个实时或捆绑的目录来证明所请求的层：

./agent-mux preview -E codex -m gpt-5.6-sol -e max -C /repo "Hard bounded task"
./agent-mux -E codex -m gpt-5.6-sol -e ultra -C /repo "Hardest bounded task"

Codex 0.144.1报告了Sol和Terra的Max和Ultra，Luna的Max，GPT-5.5/5.4/5.4-mini仅通过xhigh。Ultra可能会触发本地Codex合作，但代理商mux不承诺授权。实时跟踪的选择加入配置文件示例 示例/配置文件；现有的个人资料不会更改。

基于配置文件的调度 （引擎、型号、工作量、超时、系统提示均已从配置文件中解决）：

./agent-mux -P=lifter -C /repo "Add retry logic to client.ts with exponential backoff"

最小调度 （JSON通过 --stdin --规范机器调用）：

printf '{"engine":"codex","prompt":"Review src/core.go for timeout edge cases","cwd":"/repo"}' \
  | ./agent-mux --stdin

--stdin 是规范的机器调用，并暗示 --yes，确实如此 除非呼叫者选择 不同的模式。

异步调度 （开火，稍后收集）：

./agent-mux -P=lifter --async -C /repo "Implement retries in client.ts" > /tmp/agent-mux-ack.json
ID=$(jq -r .dispatch_id < /tmp/agent-mux-ack.json)

./agent-mux wait "$ID"
./agent-mux result "$ID" --json

调度输出始终是stdout上的单个JSON对象。生命周期子命令(list, status, result, inspect, wait)默认为人类可读但接受 --json.stderr携带NDJSON事件流和心跳线。

档案

工人身份存在 ~/.agent-mux/prompts/<name>.md每个文件都是一个markdown文档，其中包含可选的YAML frontmatter，用于设置分派默认值：

---
engine: codex
model: gpt-5.4
effort: high
timeout: 1800
description: "Scoped implementation with built-in verification"
---

# Lifter

You are a lifter. You build what was specified, verify it works, and report back.
...

-P=lifter 负载 ~/.agent-mux/prompts/lifter.md，应用frontmatter默认值，并将markdown正文作为系统提示注入。

DispatchSpec.Effort 是规范深度场，默认为 highCodex的初始和恢复命令转发相同的值。 --reasoning 仍然是一个版本的弃用别名；不同的明确 --effort 和 --reasoning 值在飞行前失败。

解析顺序 （后来获胜）：硬编码默认值->frontmatter->CLI标志/JSON字段。显式标志总是覆盖frontmatter。

agent-mux config prompts 发现所有具有完整元数据的配置文件。 agent-mux config prompts --json 将目录作为JSON数组发出，以供编程使用。

发动机

引擎CLIs必须单独安装——代理mux会分派给它们，它不会捆绑它们。

agy 是CLI的第一个实验性支持。代理mux在内部调用本地 agy CLI及其固定 --sandbox，拒绝操作员提供的便携式沙箱/权限/推理/最大转弯/完全访问选项，将提供商诊断信息存储在私有位置 agy.log，并不意味着插件、MCP、浏览器自动化、谷歌服务或提供商服务操作。

grok 是通过保守的无头合约对Grok Build CLI的支持。当前内置默认值为 grok-4.5，已通过Grok CLI验证 0.2.93；用以下命令刷新列表 agent-mux config engines --refresh-models --engine grok --json Grok CLI更新后。默认的v1路径仍归适配器所有 --prompt-file 加 --output-format streaming-json；代理mux编写私有提示/会话/调试sidecar，为恢复预先声明一个精确的UUID会话，默认省略本机沙盒标志，禁用本机子代理、内存、自动更新、alt屏幕、web搜索、图像/多模式表面、自定义沙盒策略和本机允许/拒绝规则。它接受模型、努力、明确支持的Grok沙盒配置文件，包括 off，并选择加入AgentMUX拥有的v1.5报告控件。对于v1.5， grok-worker-report-schema=agent-mux.worker-report.v1 通过相同的私有提示文件传输请求纯文本/代码的结构化工作器报告； worker_report.json 是经过净化的规范公共产物，而 grok_prompt.md 并恢复提示Sidecar保持私有。原始本地 prompt-json 和 json-schema 不是面向用户的直通选项。v1.5报告路径是伪造的，适用于仅限有界文本的工作人员报告，并在Grok CLI 0.2.93上经过验证，适用于有界文本调度，但它仍然是可选的，并不意味着媒体、搜索、工具、ACP、MCP、插件、内存或子代理。显式添加目录、权限模式、推理、完全访问、最大圈数、web/X、映像、本机允许/拒绝、插件/MCP/钩子、跟踪/导出、调试文件、最佳n、子代理和内存控制被拒绝。它不声称X搜索、网络搜索、图像输入/输出、结构化工具遥测、令牌使用、成本使用或GAAL本机会话索引。

特征

• 基于配置文件的调度 -- -P=<name> 从单个markdown文件加载引擎、模型、工作量、超时、技能和系统提示。一面旗帜代替了六面。
• 恢复和信号 --开始后续调度 --recover=<id> 以包括先前的上下文。实时微调/重定向需要一个实时FIFO或具有恢复功能的引擎；agy在发现其Antigravity对话ID后使用简历支持的收件箱投递。
• 两相超时 --当适配器支持软超时时，它会发出一个结束信号，宽限期允许干净退出，硬超时则会终止。Agy使用普通的stdout，不会收到软超时结束提示。文物在每个阶段都得到了保存。
• 异步调度 --火与遗忘 --async.稍后使用收集结果 wait 或 result.
• 事件流 --事件流引擎在stderr上发出NDJSON，但事件丰富性是特定于适配器的。Codex、Claude和Gemini可以显示结构化的工具/文件活动；Grok在没有结构化工具/文件遥测的情况下公开无头文本/错误/结束事件；Agy只是普通的stdout。
• 钩子 --基于模式的拒绝/警告规则根据线束事件进行评估。
• 技能注入 --负载 SKILL.md 将Runbook放入调度提示中。技能需要脚本、参考和设置。
• 超时和诊断 --全球调度超时是唯一的硬后盾。工作人员被信任在超时内完成。5秒看门狗周期更新 status.json 为了实时可观察性。过程组信号确保孙子们和马具一起死亡。法医工具(status.json, events.jsonl, steer nudge)取代自动死亡，用于无声工作者诊断。
• 持久的坚持 --每一份报告都写 meta.json 和 result.json 在...之下 ~/.agent-mux/dispatches/<id>/.线束启动前创建的工件目录。
• 配置提示 -- agent-mux config prompts 列出所有可发现的配置文件，包括引擎、型号、工作量、超时和描述。

认证

对于个人使用，您现有订阅中的OAuth令牌是主要的 auth-path--不需要API密钥。当OAuth不可用时设置env-var。 如果有任何身份验证路径可用，代理多路复用器将尝试分派-- MISSING_API_KEY 这是一个警告，而不是一个艰难的失败。

关于克劳德发动机的注意事项： 代理mux调用 claude CLI二进制文件 直接——它不是SDK或API包装器。供您个人使用 Claude Code订阅，OAuth登录是自然路径。集 ANTHROPIC_API_KEY 当OAuth不可用时。

文档

许可证

麻省理工学院