In short:
ak-teamsets up a runtime Agent Team: one lead splits the work, several teammates run in parallel, each with its own context, and they message each other directly. The lead merges the results, checks them itself, then reports to you and hands off toak-journal. If the runtime has no team feature, it stops and reports the error instead of quietly switching to plain subagents.
Disclosure: I maintain AgentKit and have an affiliate relationship with it: the AgentKit link in this post is an affiliate link; buying through it gets you 30% off.
Summary
Use it when you have a big job that splits into several independent streams: 3 or more, or several hypotheses worth debating. You do not need it for small or sequential work like one lint pass or a plan, code, test chain: use plain subagents.
flowchart LR
A["Big job, splits into independent streams"] --> B["ak-team"]
X["Small or sequential work"] --> Y["Plain subagent"]
B --> C["Combined report or merged, checked code"]
C --> D["ak-journal"]
B --> E["Stop: runtime has no team feature"]Before each team, you need 4 things clear:
| Point | Question | Example |
|---|---|---|
| Work pattern | What kind of work is this team doing? | research, cook, review or debug |
| File ownership | Who may edit which files? | Dev 1 owns src/api/*, dev 2 owns src/ui/*, the tester owns only test files |
| Lead role | Who splits the work, merges results and owns the final answer? | A teammate says "done", the lead still reads the report and runs the shared tests |
| Team or plain subagent | Is this worth a whole team? | 3 or more independent streams means a team |
An idle teammate is waiting, not finished. The lead watches the shared task state and messages, and never guesses from who has gone quiet.
Sample prompt for parallel implementation from a plan:
/ak-team cook plans/<plan name>/plan.md --devs 2 --worktree --plan-approval
Constraints: dev 1 only edits src/api/*, dev 2 only edits src/ui/*.
Done when: the shared tests pass after both parts are merged.| Flag | What it is for | Since ak |
|---|---|---|
--devs, --researchers, --reviewers, --debuggers | Sets how many people are on the team | 1.0.0 |
--delegate | The lead only coordinates and does no work itself | 1.0.0 |
--plan-approval, --no-plan-approval | Turns plan review before code edits on or off | 1.0.0 |
--worktree | Each teammate writes code in its own worktree | 1.0.0 |
Below is the detailed version: the run flow, 5 real situations with prompts, each flag explained (when to use it, when you do not need it, what you get, which flags it combines with), the change history by ak release, and common pitfalls. The detailed version and the interactive page are for subscribers. Your agent can also search them through the portal's MCP.
Opens when your account has subscriber access
This guide is for subscribers
Once your account has access, the full piece, the interactive visual and the agent call all open.
- Sign in or create a modernEngineer accountReading access belongs to your account email.
- Choose a plan on the pricing page1, 3 or 12 months, paid by VietQR bank transfer. Access opens about a minute after the money arrives.
- Or redeem a Facebook subscriber codePeople supporting the page on Facebook get an activation code by message each month.
Already a subscriber? Sign in to read.
Use this piece in your agent
Get an API keyCopy the text below and paste it into Claude Code, Codex or whichever agent you use. The agent reads the piece and checks it against the repo you have open.
Read "ak-team: run a parallel agent team on big work" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-team". If the modernengineer MCP server is not connected, stop and walk me through connecting it from https://modernengineer.dev/en/mcp.
2. Summarize the main steps of the piece and point out which apply to this repo.
3. Propose concrete changes and ask me before editing any file.Connect MCP in Claude Code (once)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Reading the full piece over MCP needs an API key from a subscriber account or one that bought this guide. Without access, the agent only gets the opening.
- Version
- v1.0.0
- Updated
- 22/10/2026
- Licence
- All rights reserved
- Slug
- ak-team
