In short:
ak-worktreeopens a separate working folder, with its own branch, for each task, without touching the folder you are in the middle of. It names the branch, picks the base branch and the worktree location, then hands off toak-cookorak-fix. It does not write code.
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 are halfway through one task and need to start another, without stashing or switching branches. Also use it when your machine has many worktrees and you want to check their status and clean up the finished ones.
flowchart LR
A["New task to keep separate"] --> B["ak-worktree"]
B --> C["New worktree or reuse an existing one"]
C --> D["ak-cook"]
C --> E["ak-fix"]
B --> F["Check status, clean up old worktrees, then stop"]The skill comes down to 4 questions:
| Part | Question | Example |
|---|---|---|
| Branch name | What is the new branch called? | "fix the upload timeout" becomes fix/upload-timeout |
| Base branch | Where does the new branch start from? | If the repo has dev, it branches from dev; with only main, from main |
| Worktree location | Where does the worktree folder go? | For repo ~/code/shop, the worktree is ~/code/worktrees/shop-upload-timeout |
| Safe cleanup | Does removing a worktree lose anything? | With 3 uncommitted files, it tells you and waits for your OK before removing |
The one thing to remember: commit or push before cleaning up. The skill checks and asks, but once a folder is removed, its uncommitted changes are gone for good.
Sample prompt for a parallel new task:
/ak-worktree Fix the image upload timeout in the <app name> app| Flag | What it is for | Since ak |
|---|---|---|
--prefix, --no-prefix | Pick the branch prefix, or drop the prefix entirely | 1.0.0 |
--base | Set the base branch | 1.0.0 |
--checkout-submodules | Pull submodules into the new worktree | 1.0.0 |
--worktree-root | Pick the folder that holds the worktree, this time only | 1.0.0 |
--dry-run | Preview, change nothing | 1.0.0 |
--json | Output as JSON | 1.0.0 |
The main input is not a flag: you type a task description, or a project name then the task description when the repo has several projects. The AI picks most flags for you.
Below is the detailed version: the run flow, 6 situations with prompts, each flag explained (when to use it, when you do not need it, what you get), 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-worktree: open a separate worktree for each task" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-worktree". 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-worktree
