Session Management
How AI agents track multi-turn development workflows
What are Sessions?
Sessions provide continuity and context tracking for AI agents working across multiple conversations. A session tracks an AI agent's work over time, capturing:
- Files Modified - What code was changed
- Labels & Groups - How code was organized
- Annotations - Architectural decisions and notes
- Summary - What was accomplished
Session Lifecycle
Sessions follow a clear lifecycle that ensures proper tracking and handoff between work sessions:
- Start - Begin tracking with session start
- Work - Read, write, search, organize code
- Close - End with summary and archive to
.codemap/sessions/ - Archive - Session permanently saved for future reference
Reopening Sessions
Continue work from a previous session when working on multi-day features or continuing after interruption. All file operations, labels, groups, and context from the original session are restored.
Next Session Handoff
Leave detailed notes for the next session to ensure continuity. The handoff document can include next steps, blockers, decisions made, and areas needing attention.
# Start a new session
codemap session-start
# Close current session
codemap close "Completed user authentication"
# Reopen a previous session
codemap session-reopen 2026-04-05T02-53-34# List all sessions
codemap session-list
# Read specific session details
codemap session-read 2026-04-05T02-53-34
# Write handoff notes
codemap next-session "## Next Steps\n- Add rate limiting\n- Complete tests"Start a session at the beginning of each work period, even for quick tasks. This ensures your work is tracked and can be resumed later if interrupted.
All closed sessions are archived in .codemap/sessions/. Commit this directory to version control to maintain a complete project history across your team.
Detailed handoff notes in NEXT_SESSION.md dramatically improve continuity when you or another developer picks up the work. Include what's done, what's next, and any blockers.