STATECONSOLE

How to hand off work between AI coding sessions

Give the next session enough context to continue the same task without rereading the old conversation. A short handoff records what changed, what you verified and what to do first, whether you return to the same assistant or switch tools.

1. Leave a handoff before closing the session

Record the goal, current branch and revision, and any uncommitted changes the next session needs to keep. Name the relevant files, one decision or blocker, and the first action to take next. For a check you ran, include the command or steps, tested revision, environment, result and a reference to the evidence.

Keep the note with your work, such as in a task or a Markdown file you can share with the next session. Leave out credentials, private data and unrelated chat history.

2. Separate instructions from current state

Standing instructions
Put durable rules such as test commands, conventions and boundaries in the files your tool uses. See the documentation for Codex project instructions and Claude Code project instructions for how each tool loads them.
Current working state
Put the current revision, recent results, pending decisions and next action in the handoff. Refresh it when the work changes.

StateConsole can display reported state from a supported local PROJECT_STATUS.md. It does not transfer chat history between tools or verify test results. The handoff below is ordinary Markdown; use the project status guide for the complete StateConsole file format.

3. Worked example: hand off a CSV export fix

Fictional example: continue the CSV export task from the QA checklist guide after fixing the comma case. The revision and results below are illustrative.

Before: “CSV fix done, tests passed.”

After — goal and revision
Preserve two fields per CSV row, even when the name contains a comma. Branch fix/csv-export, revision a1b2c3d, no uncommitted changes. The exporter now writes 2,"Design, Inc." so the name stays in one field.
Checks run and evidence
On that revision, exported and parsed the plain-name and comma-name fixtures on a local test build. Both rows parsed as two fields. See the output attached to the QA record.
Still unverified and next action
The larger fixture was not run. Confirm the revision, then export the larger fixture and compare the output row count to the input. Record the result before calling that case verified.

4. Reconcile the note with the repository

  1. Read the applicable repository instructions and the handoff.
  2. Compare the note with the current branch, revision and working tree. Preserve unrelated changes. Flag discrepancies before editing.
  3. Review any evidence that supports the note. Results apply to the revision and conditions tested; recheck affected behavior when either changes.
  4. Confirm the first next action, then update the handoff with what actually happened.
Starter prompt for the next session
Read the repository instructions and the handoff note. Check the current branch, revision, and working tree. If they differ from the note, report the mismatch and wait before editing. Otherwise, summarize the remaining uncertainty and propose the first next action.

5. Copy the Markdown handoff template

Paste the template into your own note or task. Fill in the facts before sharing it with the next session.

Session handoff · Markdown

# AI coding session handoff

- Goal:
- Branch and revision:
- Uncommitted changes (or none):
- What changed (include relevant paths):
- Decision, open question, or blocker:
- Checks run and evidence (command, result, revision, environment):
- Still unverified:
- First next action: