A background task scheduler for Claude Code
agentq hands the to-do items in each project's docs/BACKLOG.md to separate Claude Code processes, then merges the work to the local default branch once tests and a review pass.
$ curl -fsSL https://github.com/dodo258/agentq/releases/latest/download/install.sh | shDownloads a prebuilt binary and checks its SHA256. Needs Git, not sudo or Go. Running the same command on an existing install upgrades it and keeps your configuration and task data.
v0.1.0MITsingle Go binarymacOS · Linux
$ 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「做一个单页的产品介绍网页（大方向）」过门合并，合并提交 72f2bffb8398Install and use
Install once. After that, one line in Claude Code puts work in the queue.
At the end of the install, it states three things and asks whether to start
Press Enter to agree and start, or type n to install only. With no terminal (CI, or an agent installing for you) it installs only and never agrees on your behalf; run agentq start later. If the Claude Code CLI is missing or signed out, the script runs the official installer and claude auth login.
To have an agent install it, send it this line
Read https://github.com/dodo258/agentq/blob/main/llms.txt and install agentq for me
Assign work
Open Claude Code in your project (the CLI or the desktop app) and say what you want done:
派活：Retry an export 3 times when it fails, and show the retries in a log when offline
派活 ("assign this") triggers the dispatch skill. It writes the request as an item with acceptance criteria, commits it to docs/BACKLOG.md and starts the background task. The project must be a Git repository. It doesn't have to sit under ~/projects.
Or from a terminal:
agentq add "..." # add an item to this project's queueagentq run my-app # start one of that project's items nowagentq new "..." # create a project from one line and build v1agentq status # quota, running tasks, each project's queueagentq stop <job id> # stop a task and keep its changesagentq pause # start no new tasks; agentq resume to undoagentq doctor # read-only check of install, CLI and configHow it works
agentq schedules, runs the gates, merges and keeps records. It writes no product code.
Claude Code does the implementation and self-testing, following the bundled agent-task skill, and a separate Claude Code process does the review.
- You say itA Claude Code session, Telegram, or
agentq add - docs/BACKLOG.mdOne per project, worked top to bottom, committed with the repo
- agentq tickEvery 5 minutes and after each job; checks pause, quota and the breaker
- claude -pOwn process, own worktree: claim, build, self-test, write
ready.json, exit - GatesRuns
.agentq/verifyon the merge, a separate process reviews; if all pass, the engine merges - Wrap up, tell youDaily digest and morning report; Telegram (optional),
agentq status
- Gate failed: the work goes back to the task; still failing or undecidable, it waits for you.
- Interrupted or limited: the same session resumes.
- Every 5 min
- The scheduler runs, and again whenever a task ends, so a queued item starts within seconds.
- 2 / 1
- By default 2 tasks run at once, with at most 1 per project.
- No push
- The scheduler never runs
git push. Merges happen on the local default branch; pushing needs separate authorization. - Stay on
- Tasks don't depend on a terminal or client, but the machine has to stay on.
Quality gates
A task can only get its branch ready to merge. agentq decides whether it merges.
When a task is done it writes .agentq/ready.json. The five gates below run on the branch merged with the latest default branch.
| Gate | When it runs | What it checks | Default level |
|---|---|---|---|
| Test | Every time | Runs the project's .agentq/verify | Blocks the merge |
| Review | Skipped for markdown-only changes | A separate process reviews the change. A blocking finding needs a file, line, evidence and reproduction steps | Blocks the merge |
| Patch | When the change is a fix | A third fix to the same module within 30 days. Set to error, it sends the task back to rewrite that module | Records only |
| UI | When UI files change | A project script takes screenshots, agentq checks they aren't blank, and a review process blocks only on broken rendering, overflow, unreadable text or placeholder content | Records only |
| Product | The first version from agentq new and items marked （成品） | Runs the project's smoke test .agentq/smoke and produces a handoff sheet if it passes | Records only |
A project can change the levels in .agentq/gates.json. When a gate fails, the reason goes back to the task and the same session continues, for at most 2 rounds. If it still fails or can't be decided, the item is marked stuck and waits for you:
agentq gate report <job id> # see whyagentq gate pass <job id> --reason "..." # let this one throughagentq gate rerun <job id> # run the gates again, no code changesagentq gate abandon <job id> # give up and keep the branchA task that merges by itself around the gates doesn't count as passed; agentq flags it and notifies you. The gates guard against a model cutting corners or making mistakes. They are not a security boundary: tasks have full access to your machine.
Picks up where it stopped
A process exits, the machine reboots, a usage limit hits: the same session continues.
| Situation | Response |
|---|---|
| A process exits midway, or the machine reboots | Checks the BACKLOG and resumes the same session. Merged work isn't redone |
| A usage limit is hit | Cools down until the reset time, then resumes the same session |
| Quota is nearly gone | Starts no new tasks at 90%. agentq run is refused at 98% |
| Tasks fail right after starting | Three tasks exiting within 3 minutes trip a breaker that stops new starts for 30 minutes. Another failure doubles that, up to 4 hours |
| A task runs away | Each run has a budget cap, subagent runaway stops it automatically, and the default timeout is 4 hours. Its changes are kept |
| The state file breaks | Unreadable: nothing is wrapped up or started. Corrupt: the bad file is backed up, state is rebuilt from task records, and no new task starts that round |
| Run data grows | Task records are kept 90 days by default, and logs are trimmed |
These paths are covered by a fake CLI and a stress test. A real usage limit has not been run yet. The stress test kills processes, corrupts state files, forces concurrency, fills the disk and jumps the clock, all with fake dependencies, and has only run on macOS so far.
Telegram
Optional. Once set up, you can message the bot with requests and screenshots.
- Reply to a “decide” message or tap a button. The decision is written back to the item and the task continues.
- Reply to a task alert to pick that task back up.
状态,额度,暂停and恢复(status, quota, pause, resume) are answered by code and use no quota.- With
router_enabledon, send one line describing a new project; agentq creates it, builds the first version and reports after the merge. This round trip has not been verified on real Telegram.
At most 10 notifications a day. Messages between 23:00 and 08:00 wait for the morning, and messages of one kind within 30 minutes are combined. Without Telegram, agentq uses local desktop notifications.
Completion notices and decision card buttons work on real Telegram. Reply threads and full conversation round trips have only been tested against a fake service.
Support
How far each item has been verified, stated plainly.
| Item | Status |
|---|---|
| Claude Code CLI | Default backend. 2.1.316 has reached a merge for real on macOS, including the review gate, the UI gate, agentq new, the launchd background and assigning work from the desktop app |
| Codex CLI | Choose it by hand. codex-cli 0.166.0 has reached a merge and resumed after SIGTERM for real on macOS. Router, suggestions, sensing and release prep do not start on it, and it has no dollar cap |
| opencode | Experimental. The real opencode has never been run |
| macOS | arm64 is the main platform. amd64 cross-compiles and has not run on an Intel Mac |
| Linux | Needs systemd --user. amd64 runs the tests and a real systemd acceptance in CI, with no real task run. arm64 cross-compiles |
| WSL, Windows | WSL is unverified. Windows is not supported |
Not yet verified for real
- A usage limit and an expired token
- Assigning work from the Codex desktop app
- Real tasks and stress tests on Linux
- Any opencode run
- The gates compared with a bare CLI on real projects
Permissions and limits
- Unattended coding needs
bypassPermissions. A task runs as your OS user with all your file permissions, can read local secrets and can run any command. Prompts and deny rules are not a security boundary. - On a sensitive machine, run it under a separate OS user or in a container, and keep production credentials off it.
- The machine has to be on. Tasks continue after sleep or a reboot, but nothing runs while it's off. Tasks spend your own model quota.
- Command output, notifications and BACKLOG section headings are in Chinese for now. Item text can be in any language. Most guides are in Chinese.