agentq

Claude Code 的后台任务调度器

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

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

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

v0.1.0MITGo 单文件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　一次试跑的终端记录：安装，派一条活，查看状态，过门合并。

安装和用法

装一次。之后在 Claude Code 里说一句，活就排进队。

安装结束时，程序说明三点，再问是否启动

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

按回车同意并启动，输入 n 只安装。没有终端时（CI、由 agent 代装）只安装，不替你同意，之后运行 agentq start 启动。没有 Claude Code CLI 或没有登录时，脚本运行官方安装命令和 claude auth login。

由 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 <任务id>  # 停止一个任务，已有改动保留agentq pause        # 暂停启动新任务，agentq resume 恢复agentq doctor       # 只读检查安装、CLI 和配置

工作流程

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，另开进程审查；都过了，由引擎合并
  6. 收尾，告诉你写进当天汇总和早报；Telegram（可选）、agentq status
  • 门没过：退回任务接着改；还不过或判不了，等你定。
  • 中断、撞上限：用同一会话续跑。
图 2　一条待做从写下到合并。虚线是两条回路：门没过退回接着改，中断或撞上限时用同一会话续跑。
每 5 分钟
调度器运行一次，任务结束时也立刻运行，排队的条目几秒内开始。
2 个 / 1 个
默认全局同时运行 2 个任务，同一项目 1 个。
不推送
调度器不执行 git push，合并只发生在本地默认分支，推送远程要另外授权。
要开机
任务不依赖终端或客户端，机器要保持开机。

质量门

任务只能把分支做到可合并。合不合并，由 agentq 判定。

任务做完写一份 .agentq/ready.json。下面五道门都在分支和最新默认分支合并后的代码上运行。

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

项目可以在 .agentq/gates.json 调整档位。门没过时，原因退回任务，同一会话接着改，最多 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 上跑过。

Telegram

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

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

每天最多推送 10 条，23:00 到 08:00 的消息攒到早上发，同类消息 30 分钟内合并。没配 Telegram 时用本机通知。

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

Telegram 对话：机器人问整体想要什么感觉，给 A、B、C 三个方向；选了 B；做完后推送已合并和合并提交
图 3　开工前问一次大方向，做完推送合并提交。和图 1 是同一次试跑。

支持范围

每一项验证到哪一步，如实写。

项目状态
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。任务以你的系统用户运行，有你的全部文件权限，能读本地密钥，能运行任意命令。提示词和 deny 规则不是安全边界。
  • 在高敏感的机器上，用单独的系统用户或容器运行，不放生产凭据。
  • 机器要开着。睡眠和重启后任务继续，关机期间不运行。任务消耗你自己的模型额度。
  • 命令输出、推送和 BACKLOG 的节标题目前是中文，条目内容不限语言。

每项详情见支持矩阵