isomux-handoff

Continue your unfinished task on a fresh session. Use this when your context is getting full but the work isn't done: you distil what's LEFT (not what happened) into a brief and hand off to a fresh copy of yourself that resumes on just that brief.

1. Write the handoff brief

The brief is FORWARD-LOOKING: only what the next session needs to carry the work forward. It is NOT a summary of this conversation.

Include:

• The goal: what still needs to be accomplished, as concretely as you can.
• The next concrete steps: what you'd do next if you kept going.
• Working state that isn't obvious from disk: dirty files, active worktrees/branches, paths, commits, anything uncommitted, in-flight commands.
• Decisions already made that the fresh session shouldn't relitigate, and any open questions or unconfirmed assumptions to revisit with the boss.
• Pointers: the specific files, docs, or task IDs the work touches.

Deliberately leave OUT:

• A narrative recap of what happened this session ("first I did X, then Y...").
• Anything already in your system prompt, your custom instructions, or isomux memory. The fresh session reloads all of that automatically.
• Generic advice the fresh you would already know.

Keep it tight.

2. Get the boss's approval

Show the boss the exact brief you intend to hand off and wait for their confirmation.

3. Hand off

Hand off to a fresh copy of yourself with the approved brief. This resets your session and delivers the brief into the fresh session in one step, so a clean copy resumes on the brief - instantly, with no wait:

curl -s -X POST localhost:4000/api/agents/<your-own-id>/handoff \
  -H "Authorization: Bearer $ISOMUX_AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"text":"<the approved brief>"}'

Your current turn ends as the reset takes effect; the fresh session picks up the brief on its own. (For a genuine FUTURE reminder or wake-up instead of an immediate handoff, use the scheduled-message path - a POST to your own /messages with a deliverAt - rather than this endpoint.)