AI Task Master (aitm)

Autonomous task orchestrator. Goal in, merged PRs out.

Give aitm a sentence, walk away, come back to a stack of merged pull requests. It runs a Planner → Worker → Reviewer loop against a real repo using the Vercel AI SDK and OpenRouter, and ships the work as PR-sized commits with CI gating and review-comment handling baked in.

💡 Inspired by the (now deprecated) developerz-ai/claude-task-master. aitm is the spiritual successor — same idea (a task-master that drives the work to merge), rebuilt on the Vercel AI SDK + OpenRouter, provider-agnostic, with concurrent PR groups, MCP client support, and a much smaller surface area.

✨ Why aitm?

Coding agents are great at single steps, terrible at staying on task across hours. aitm closes that gap:

• 🧭 Planner splits a goal into ordered, PR-sized task groups.
• 🛠️ Worker branches, codes, and opens the PR.
• 👀 Reviewer drives review-comment resolution and pushes fixes.
• 🚀 Auto-merge waits for CI green, then merges — by default.
• 🧱 Two commands to learn (aitm start, aitm merge-pr). That's it.

No babysitting. No prompt-stuffing. No bespoke agent framework.

⚡ Install

bun  install -g @developerz.ai/aitm    # recommended for local dev
npm  install -g @developerz.ai/aitm    # works the same
deno install -A npm:@developerz.ai/aitm

The package is scoped (@developerz.ai/aitm); the installed command is still aitm.

Plain ESM + a bun build --compile single-file binary. No runtime lock-in.

🚀 Quickstart

export OPENROUTER_API_KEY=sk-or-...
cd path/to/your/repo
aitm start "add JWT auth to /login" --max-prs 3

aitm plans the goal into up to 3 PR-sized groups, opens a branch per group, works through them in parallel, opens each PR, watches CI, addresses review comments, and auto-merges. Need a human gate?

aitm start "migrate Mongo → Postgres" --no-automerge
# ... review the PR in your browser ...
aitm merge-pr

Interrupted? aitm resume picks the run back up — it reads the goal from .ai-task-master/, so you never retype it (and never accidentally resume onto a slightly different goal than the plan was built for). aitm --version tells you which build you're on.

🎯 Use cases

🧠 How it works

                                   ┌───────────────┐
                                   │  CLAUDE.md /  │  (coding style for subagents)
                                   │   AGENTS.md   │
                                   └──────┬────────┘
                                          │
   goal ──▶ Planner ──▶ task groups ──▶ Orchestrator ──▶ Worker  ──▶  PR
                                              │             │           │
                                              │             └──▶  ✅ CI / 👀 Reviewer
                                              ▼                         │
                                          StateStore ◀──── auto-merge ◀─┘

• Provider: any OpenAI-compatible endpoint through one credential — OpenRouter by default, or point baseURL at z.ai GLM, a self-hosted gateway, or another provider. No Anthropic SDK. See 🔀 Providers & profiles.
• Coding style: aitm reads your repo's CLAUDE.md or AGENTS.md and feeds it to subagents as a style signal.
• State: every run persists to .ai-task-master/ so resume-after-crash is one command — including a human-readable plan.md (per-task checkboxes) and progress.md (timestamped lifecycle log). aitm clean wipes it for a fresh start. aitm update self-updates to the latest npm release (--check to only check; never automatic).
• One checkout: groups run sequentially in your working tree on aitm/<group> branches — no worktrees, no hidden copies. Within a group, the Worker is the single owner: it edits small/cohesive tasks itself, and only fans out parallel leaf editors for genuinely large work (many files, multi-area debugging).

📺 Reading the console stream

Every line is prefixed with who is talking and where the run is:

[aitm group 2/5 pr-open 21:46:29] group g2: pushing and opening PR     ← cyan: the harness
[k3 worker g2 group 2/5 working 21:47:03] Using tool: bash → bun test  ← orange: a subagent
[k3 editor:auth.ts #2 g2 group 2/5 working 21:47:10] Using tool: …     ← a leaf editor (only on big fan-out work)

Anatomy: [<model> <subagent> <group> <state> <time>] — the subagent name renders blue
(a routed specialist's name, the bare role, or editor:<file> with #N when several editors
share a basename), the state tag (group 2/5 working) magenta, and the timestamp dim at
the end. Dim lines are the model's reasoning. Colors are TTY-gated (NO_COLOR respected); the
same lifecycle lines are also appended to .ai-task-master/progress.md.

🧰 Requirements

💡 Claude-conventioned projects: aitm will pick up CLAUDE.md as its coding-style source automatically. The provider is still OpenRouter — the file is only a style signal.

🧩 Two-command philosophy

start and merge-pr are the commands that do the work; resume continues an interrupted start.

• 🟢 With automerge on (default): start runs the whole loop end-to-end.
• 🟡 With --no-automerge: start stops after each PR opens; you call aitm merge-pr once you're happy.

Everything else — planning, task grouping, branch management, retries, review-comment handling — happens inside those two calls.

🚩 Key flags

💡 Both --key value and --key=value forms are accepted: --max-prs=3 works the same as --max-prs 3.

When you need --admin

Green CI is not always enough to merge. If the base branch requires an approving review, a required check the run can't satisfy, or any other protection rule, gh pr merge is refused with:

Pull request #NNN is not mergeable: the base branch policy prohibits the merge.

The run then blocks with a finished, green PR it isn't allowed to land. --admin merges past the rule — what you want for an unattended run on a repo you own:

aitm start "…" --admin
aitm merge-pr --pr 42 --admin

It needs repo-admin rights and it is a real override: the review requirement is bypassed, not satisfied. On a repo where those reviews are the point, leave it off and merge by hand. --admin also advances a CI timeout to the review stage instead of blocking; it does not skip CI or ignore failing checks — those still route to the fix loop.

⚙️ Configuration

User config lives at ~/.aitm.json; per-project overrides at .ai-task-master/config.json:

aitm config set models.smart anthropic/claude-opus-4.7
aitm config set models.coding anthropic/claude-sonnet-4.6
aitm config set models.fast    openai/gpt-5-mini
aitm config set autoMerge true --project
aitm config set llmStepTimeoutMs 900000   # per-step LLM deadline (default 15 min)
aitm config list

llmStepTimeoutMs bounds a single LLM step — one provider request plus that step's tool calls
— not the whole run, so a stalled provider can't hang an unattended run while long multi-step Worker
passes still run to completion. It must clear the bash tool's 600 s ceiling plus a slow high-effort
completion; the floor is 1000 ms. On expiry the step is aborted and surfaces as a blocked/errored
group (the SDK does not auto-retry a timeout).

See docs/config.md for the full schema.

🔀 Providers & profiles

aitm talks to one OpenAI-compatible endpoint. The default is OpenRouter; override the base URL to run against any other OpenAI-compatible provider — z.ai's GLM coding plan, a self-hosted gateway, OpenAI, … One credential, no Anthropic SDK. The only hard requirement is OpenAI-style function/tool calling (OpenRouter, z.ai GLM, and OpenAI all support it).

Profiles bundle the provider triple (key + base URL + per-tier models) under a name, so you switch the whole provider in one command — version-manager style (think nvm use):

# Create profiles from built-in presets (openrouter | zai), add your key:
aitm profile add openrouter --preset openrouter --api-key "sk-or-..."
aitm profile add z.ai       --preset zai        --api-key "<your z.ai key>"

aitm profile use z.ai                  # switch the active provider…
aitm start "add a /healthz endpoint with a test" --max-prs 1   # …now running on z.ai GLM
aitm profile use openrouter            # …and back

aitm profile list                      # '*' marks the active profile; keys shown masked

✅ Verified end-to-end against z.ai GLM — the Planner/Worker/Reviewer loop runs on glm-5.2 / glm-5-turbo through the GLM coding endpoint (https://api.z.ai/api/coding/paas/v4).

Prefer editing JSON? The same thing as plain config:

// ~/.aitm.json
{
  "openrouterApiKey": "<your z.ai key>",
  "baseURL": "https://api.z.ai/api/coding/paas/v4",
  "models": { "generic": "glm-5.2", "smart": "glm-5.2", "coding": "glm-5.2", "fast": "glm-5-turbo" }
}

Provider routing & fallback

OpenRouter serves the same model id through multiple upstream providers, and they differ sharply in tool-calling reliability. Two config keys (also settable per profile) steer the routing — mapped onto OpenRouter's provider controls:

aitm config set providerRouting.requireParameters true          # only route to endpoints that support every request parameter
aitm config set providerRouting.order '["anthropic","openai"]'  # try these providers first
aitm config set providerRouting.sort throughput                 # or "price" / "latency"
aitm config set fallbackModels.coding '["anthropic/claude-opus-4.7","openai/gpt-5"]'  # fail over on a provider/model outage

Every subagent call carries tool definitions (the submit contract), so requireParameters: true is recommended — it guarantees the request lands on an endpoint that won't silently drop them. The caveat: it narrows the provider pool and can make a thinly-served model unroutable. providerRouting.{order, allowFallbacks, requireParameters, sort, only, ignore} all map to the OpenRouter provider block; fallbackModels.<tier> becomes the top-level models fallback array for that capability. amazon-bedrock is always excluded (it rejects the structured-output parameter) — this built-in ignore can't be removed.

Full walkthrough in docs/providers.md; profile command reference in docs/commands/profile.md.

🧪 Try it on a sandbox repo

# 1. Clone a throwaway repo
git clone https://github.com/you/scratch && cd scratch

# 2. Drop a tiny CLAUDE.md so subagents know the style
echo "# CLAUDE.md\n- TypeScript strict.\n- No comments unless necessary." > CLAUDE.md

# 3. Set your key and go
export OPENROUTER_API_KEY=sk-or-...
aitm start "add a /healthz endpoint with a test" --max-prs 1

A single PR opens, CI runs, it merges. Total wall-clock: a few minutes.

📚 Docs

🤝 Contributing

PRs welcome. House style is in CLAUDE.md: SOLID, one responsibility per module, every module ships with a paired *.test.ts, no any, no default exports, conventional commits, no emoji in source.

bun install
bun test          # unit + integration
bun run typecheck
bun run lint

📄 License

MIT.