In short:
ak-handoffwrites a 9-section Markdown file for the agent that continues the work: the mission, the guardrails, the repo state, decisions, checks already run, risks and the first safe step. By default it only writes the file, and you paste a reminder line into the new session. Add--dispatchand it hands the file to a runtime you choose throughak-orchestrate. It does not edit code and does not write progress reports for people.
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 to switch sessions, models or runtimes in the middle of unfinished work, or when you want another agent to continue right away. You do not need it when you only want to see where the project stands (branches, worktrees, plans): that is the job of ak-watzup.
flowchart LR
A["Unfinished work"] --> B["ak-handoff"]
B --> C["9-section handoff file"]
C --> D["New session reads the file, checks the repo, continues"]
B -->|"--dispatch"| E["ak-orchestrate hands it to the runtime you choose"]It keeps 4 principles:
| Principle | Question | Example |
|---|---|---|
| Continuation contract | What does the new agent need to know to continue without guessing again? | 9 fixed sections, in order: Mission and current status, Scope and guardrails, Current state, Decisions and rationale, Work performed, Verification, Open risks and blockers, Exact next actions, Source pointers. Exact next actions opens with **First safe step**, for example "read src/auth/callback.ts and its test". |
| No invention when data is missing | What if this session has no information for a section? | If no test was run, the Verification section says exactly Not captured in this session. The section is not dropped and does not say "TBD". When the new agent sees this line, it knows it must find the evidence itself. |
| Secret redaction | Can tokens or passwords from commands that ran leak into the file? | A JWT in the output is replaced with [REDACTED:jwt], and a DB connection string with a password becomes [REDACTED:db-url]. The end of Work performed records only how many values were redacted, never the values. |
| The reader is an agent | Who is this file written for? | For an AI agent about to continue this exact work. For a report to a person about the project's status (branches, worktrees, plans), use ak-watzup. |
The file is a snapshot taken when it was written: the repo can change afterwards, so the new agent must compare the Current state section with the repo before working. With --dispatch, you must choose --agent yourself: it does not pick or switch runtimes for you.
Sample prompt when switching sessions mid-task:
/ak-handoff "fix the OAuth callback returning 500 on <app name>"| Flag | What it is for | Since ak |
|---|---|---|
--output | Writes the file to a path you choose | 2.10.0 |
--include-diff | Adds lines changed per file and up to the first 200 diff lines | 2.10.0 |
--include-status | Adds a snapshot of git status --short | 2.10.0 |
--force | Allows overwriting an existing handoff file | 2.10.0 |
--dispatch --agent <id> | Writes the handoff, then hands it to the runtime you choose | 2.17.0 |
--handoff | Hands off an existing handoff file instead of taking a new snapshot | 2.17.0 |
--cwd | Sets the root folder for the dispatched job | 2.17.0 |
--model | Picks the model for a CLI runtime | 2.17.0 |
--yes | Approves the job's writes in advance | 2.17.0 |
--task | Another way to write the focus text | 2.17.0 |
Below is the detailed version: the run flow, 5 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-handoff: record unfinished work so a fresh agent can continue" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-handoff". 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-handoff
