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, revisiona1b2c3d, no uncommitted changes. The exporter now writes2,"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
- Read the applicable repository instructions and the handoff.
- Compare the note with the current branch, revision and working tree. Preserve unrelated changes. Flag discrepancies before editing.
- Review any evidence that supports the note. Results apply to the revision and conditions tested; recheck affected behavior when either changes.
- Confirm the first next action, then update the handoff with what actually happened.
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.
# 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: