A background task scheduler for Claude Code

At the end of the install, the program states three things and asks whether to start:

1. Tasks can read and write every file your OS user can.
2. Task content goes to the model service you use, on your own quota.
3. With nothing to do, no quota is used.

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 to start it.

After you agree, the script runs the official installer and claude auth login if the Claude Code CLI is missing or signed out. The desktop app can't run background tasks, so the CLI is needed even if the app is installed.

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

Usage

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.

You can also work from the terminal:

agentq add "..."

# add an item to this project's queue; the first one brings the project in

agentq run my-app

# start one of the project's items now

agentq new "..."

# create a new project and build its first version from one line

agentq status

# quota, running tasks, each project's queue, recently finished tasks

agentq stop 1105-211629-shop-api

# stop a task and keep its changes

agentq pause

# stop starting new tasks; agentq resume undoes it

agentq doctor

# read-only check of install, CLI and config

Every command is listed in the command reference (in Chinese).

agentq picks items, starts and monitors processes, runs the quality 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.

1. You say itA Claude Code session, Telegram or agentq add
2. docs/BACKLOG.mdOne per project, worked top to bottom, committed with the repo
3. agentq tickEvery 5 min and after each jobChecks pause, quota, breaker, concurrency, sign-in
4. claude -pOwn process, own worktreeClaim, build, self-test; writes ready.json, exits
5. GatesRuns .agentq/verify on the merge; a separate process reviewsAll pass: engine merges to main
6. Wraps up, tells youDaily digest, morning report, Telegram (optional), agentq status

• Interrupted or limited: back to step 4, the same session resumes.
• Not passed: sent back to step 4. Still failing, or can't tell: your call (Telegram card (optional) or agentq gate pass).

Every 5 min

The scheduler runs every 5 minutes 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, and pushing to a remote needs separate authorization.

Stays on

Tasks don't depend on a terminal or client, but the machine has to stay on.

Full rules: scheduling (in Chinese).

A task can only get its branch ready to merge and write .agentq/ready.json. agentq decides whether to merge using the five gates below, which 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 filler content	Records only
Product	On 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. On the first agentq init or agentq add, the program generates .agentq/verify from the project's files. If it can't tell what to run, the task has to add the script while implementing.

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 the result can't be determined (for example, the script reports it can't run this time), the item is marked stuck and waits for you:

agentq gate report <job id>

# see why

agentq gate pass <job id> --reason "..."

# let this one through

agentq gate rerun <job id>

# run the gates again without code changes

agentq gate abandon <job id>

# give up and keep the branch

A 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, because tasks have full access to your machine.

Details: quality gates and engine merge (in Chinese).

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. Method: CONTRIBUTING (in Chinese). Rules: scheduling (in Chinese).

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

Pick a backend at install time with --backend codex or --backend opencode (... | sh -s -- --backend codex). The interface for new tools is described in docs/backends.md (in Chinese). The prebuilt binary needs only Git, and building from source uses only the Go standard library.