agentq

Claude Code 的后台任务调度器

agentq 是 Claude Code 的后台任务调度器：它把各项目 docs/BACKLOG.md 里的待做条目交给独立的 Claude Code 进程实现，测试和审查通过后合并到本地默认分支。

curl -fsSL https://github.com/dodo258/agentq/releases/latest/download/install.sh | sh

脚本下载预编译程序并校验 SHA256，不需要 sudo 和 Go，只依赖 Git。已安装时重跑同一条命令就是升级，配置和任务数据保留。

v0.1.0 · MIT · Go 单文件 · macOS · Linux

在 GitHub 上看源码入门指南

trial-launchd
$ curl -fsSL https://github.com/dodo258/agentq/releases/latest/download/install.sh | sh
✓ 下载 agentq_darwin_arm64.tar.gz
✓ 校验通过
✓ 安装程序和技能
agentq 装好了。
· 你交代的任务由官方 CLI 的独立进程完成，它们能读写这个用户的所有文件（包括本地密钥）、运行命令。
· 任务内容会发给你所用的模型服务，用你自己的账号额度。agentq 本身不收集数据。
· 没有待做时什么都不做，不消耗额度。
按回车同意并启动，输入 n 只安装不启动：⏎
✓ 后台已启动，每 5 分钟看一次待做。

$ agentq add "做一个单页的产品介绍网页（大方向） —— 给一个叫「加法匠」的小工具做介绍页"

$ agentq status
调度：正常
额度：会话 42%；本周 72%
运行中（1/2）：trial-greeting「实现 Greeting(name string) string」

门：trial-launchd「做一个单页的产品介绍网页（大方向）」过门合并，合并提交 72f2bffb8398
图 1一次试跑的终端记录：安装，派一条活，查看状态，过门合并。

安装和用法

装完先说明任务能做什么、用谁的额度，你同意了才启动。

安装结束时，程序说明以下三点，然后询问是否启动：

  1. 任务能读写当前系统用户的所有文件。
  2. 任务内容发给你使用的模型服务，消耗你自己的额度。
  3. 没有待做时不消耗额度。

按回车同意并启动，输入 n 只安装。没有终端时（CI、由 agent 代装）只安装，不替你同意，之后运行 agentq start 启动。

同意后，如果没有 Claude Code CLI 或没有登录，脚本运行官方安装命令和 claude auth login。桌面端不能跑后台任务，只装了桌面端也需要 CLI。

由 agent 代装时，把这句话发给它：

读 https://github.com/dodo258/agentq/blob/main/llms.txt，帮我装 agentq

用法

在项目目录打开 Claude Code（CLI 或桌面端），说明要做什么：

派活：导出失败时重试 3 次，断网时要能看到重试日志

dispatch 技能把这句话写成带验收标准的条目，提交到 docs/BACKLOG.md 并启动后台任务。项目要是 Git 仓库，不要求放在 ~/projects 下。

也可以在终端操作：

agentq add "..."
# 往当前项目的「待做」加一条，项目第一次添加时自动接入
agentq run my-app
# 立刻启动该项目的一条待做
agentq new "..."
# 按一句话新建项目并做出第一版
agentq status
# 查看额度、运行中的任务、各项目待做和最近结束的任务
agentq stop 1105-211629-shop-api
# 停止一个任务，已有改动保留
agentq pause
# 暂停启动新任务，agentq resume 恢复
agentq doctor
# 只读检查安装、CLI 和配置

日常操作见日常使用，所有命令见命令参考。

工作流程

agentq 只管调度、过门和合并，代码由 Claude Code 写。

agentq 负责选择条目、启动和监控进程、运行质量门、合并和记录，不写业务代码。实现和自测由 Claude Code 按随附的 agent-task 技能完成，审查由另一个 Claude Code 进程完成。

你说一句，写进 docs/BACKLOG.md；agentq tick 检查后启动独立的 claude -p 进程，在独立 worktree 里实现、自测，写 ready.json；agentq 运行质量门（测试、审查），通过后由引擎合并并收尾；未通过时退回任务接着改，仍未通过就等你决定；中断或撞上限时用同一会话续跑；结果写进当天汇总和早报
  1. 你说一句Claude Code 会话、Telegram 或命令行 agentq add
  2. docs/BACKLOG.md每个项目一份，从上往下做，随仓库提交
  3. agentq tick每 5 分钟，任务结束时也跑检查暂停、额度、熔断、并发、登录
  4. claude -p独立进程，独立 worktree认领、实现、自测，写 ready.json 就退出
  5. 过门合并态上跑 .agentq/verify，另开进程审查都过了，引擎合到 main
  6. 收尾，告诉你当天汇总和早报、Telegram（可选）、agentq status
  • 中断、撞上限：回到第 4 步，同一会话续跑。
  • 门没过：退回第 4 步接着改；还不过、判不了，等你定（Telegram 卡片（可选）或 agentq gate pass）。
图 2从一句话到合并：六步，两条回路。出自 agentq 仓库 docs/brand/readme/。
每 5 分钟
调度器每 5 分钟运行一次，任务结束时也立刻运行一次，所以排队的条目几秒内开始。
2 个 / 1 个
默认全局同时运行 2 个任务，同一项目 1 个。
不推送
调度器不执行 git push，合并只发生在本地默认分支，推送远程要另外授权。
要开机
任务不依赖终端或客户端，机器要保持开机。

完整规则见调度规则。

质量门

任务只能把分支做到可合并，合不合并由五道门定。

任务只能把分支做到可合并，并写一份 .agentq/ready.json。是否合并由 agentq 按下面五道质量门判定，门都在分支和最新默认分支合并后的代码上运行。

质量门什么时候运行检查内容默认档位
测试门每次运行项目的 .agentq/verify挡合并
审查门只改 markdown 文档时跳过独立进程审查改动，阻塞项要有文件、行号、证据和复现步骤挡合并
补丁门改动类型是修复时同一模块 30 天内第三次修复。调成 error 后退回任务，要求重写该模块只记录
界面门改到界面文件时项目脚本截图，agentq 检查不是空白，审查进程只对渲染坏、溢出、看不清和占位内容阻塞只记录
成品门agentq new 的第一版和标了 （成品） 的条目运行项目的烟测 .agentq/smoke，通过后生成交付单只记录

项目可以在 .agentq/gates.json 调整档位。第一次 agentq init 或 agentq add 时，程序按项目文件生成 .agentq/verify；判断不了时，任务要在实现时补上。

质量门未通过时，原因退回任务，同一会话接着修改，最多 2 轮。仍未通过或无法判定（比如脚本说这次跑不了）时，条目标记为卡住，等你决定：

agentq gate report <任务id>
# 查看原因
agentq gate pass <任务id> --reason "..."
# 放行这一次
agentq gate rerun <任务id>
# 不改代码重新运行质量门
agentq gate abandon <任务id>
# 放弃，分支保留

任务绕过质量门自己合并的不算通过，agentq 会标出来并通知你。质量门针对的是模型偷懒和误操作，不是安全边界：任务在你的机器上有完整权限。

细节见质量门和引擎合并。

断了能续

进程退出、撞上限、状态文件坏了，都有固定的处理。

情况处理
进程中途退出、机器重启核对 BACKLOG 后用同一会话续跑，已合并的不重做
撞上用量上限冷却到重置时间，再用同一会话续跑
额度快用完到 90% 时不启动新任务，agentq run 到 98% 时拒绝
任务启动后立刻失败连续 3 个任务在 3 分钟内退出时熔断，暂停启动 30 分钟，再次失败时时长翻倍，最长 4 小时
任务失控单次运行有预算上限，子代理失控时自动停止，超时默认 4 小时。已有改动保留
状态文件损坏读不了时不收尾也不启动。内容损坏时备份坏文件，按任务记录重建，那一轮不启动新任务
运行数据增长任务记录默认保留 90 天，日志定期截断

这些路径有假 CLI 和暴力测试覆盖，真实撞限还没有跑过。暴力测试会杀进程、写坏状态文件、制造并发、写满磁盘、跳变时钟，依赖全部是假的，目前只在 macOS 上跑过。方法见 CONTRIBUTING，规则见调度规则。

Telegram

可选。给机器人发需求、回复决定，合并和失败都推送过来。

Telegram 是可选的。配好后可以给机器人发需求，也可以带截图。

  • 回复「要你定」的消息或点按钮，决定写回条目，任务继续。
  • 回复任务提醒，接上那个任务。
  • 状态、额度、暂停、恢复 由代码直接回答，不消耗额度。
  • 打开 router_enabled 后，发一句新项目的描述，比如 一个记录读书笔记的网页工具，agentq 新建项目并做出第一版，合并后推送结果。这条的真实 Telegram 往返没有验证过。

每天最多推送 10 条，23:00 到 08:00 的消息攒到早上发，同类消息 30 分钟内合并。任务合并后推送合并提交，失败、中断、卡住也推送。没配 Telegram 时用本机通知。

完成推送和决定卡片按钮在真实 Telegram 上走通，回复链和完整对话往返只用假服务测过。配置方法见 Telegram 指南。

Telegram 对话：机器人问整体想要什么感觉，给 A、B、C 三个方向；选了 B；做完后推送已合并和合并提交
图 3一次真实试跑的 Telegram 对话：选方向，做完推送合并提交。截图来自 agentq 仓库 docs/brand/readme/。

支持范围

哪些真实走到了合并，哪些只能编译、还没跑过，照实写。

项目状态
Claude Code CLI默认后端。2.1.316 在 macOS 上真实走到合并，包括审查门、界面门、agentq new、launchd 后台和桌面端派活
Codex CLI手动选择。codex-cli 0.166.0 在 macOS 上真实走到合并和 SIGTERM 续跑。Router、闲时找活、主动感知、发版准备在它上面不启动，没有美元上限
opencode实验，真实的 opencode 没跑过
macOSarm64 是主要平台。amd64 能交叉编译，没有在 Intel Mac 上跑过
Linux需要 systemd --user。amd64 在 CI 上跑测试和真实 systemd 验收，没跑过真实任务。arm64 能交叉编译
WSL、WindowsWSL 未验证，Windows 不支持

还没有真实验证的

  • 真实撞限和令牌失效
  • Codex 桌面端派活
  • Linux 上的真实任务和暴力测试
  • opencode 的任何运行
  • 门和裸 CLI 在真实项目上的对比

每项详情见支持矩阵。

权限和限制

  • 无人值守写代码需要 bypassPermissions。任务以你的系统用户运行，有你的全部文件权限，能读本地密钥（包括 App Store Connect 私钥和 SSH key），能运行任意命令。提示词和 deny 规则不是安全边界。agentq 能防模型偷懒和误操作，防不了存心破坏。
  • 在高敏感的机器上，用单独的系统用户或容器运行，主动感知用只读的 App Store Connect key，不放生产凭据。详见 SECURITY。
  • 机器要开着。睡眠和重启后任务继续，关机期间不运行。
  • 命令输出、推送和 BACKLOG 的节标题目前是中文，条目内容不限语言。

安装时用 --backend codex 或 --backend opencode 选择后端（... | sh -s -- --backend codex）。接新工具的接口见 docs/backends.md。预编译程序只依赖 Git，源码构建只用 Go 标准库。