codemap_next_session
Write handoff notes to .codemap/sessions/NEXT_SESSION.md. Use to leave instructions, context, or TODOs for the next person/session working on the project.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
text | string | ✅ Required | Markdown text for handoff document. Can include context, TODOs, warnings, or any notes for the next session. |
Usage Examples
MCP Usage (for AI Agents like Claude)
json
{
"name": "codemap_next_session",
"arguments": {
"text": "# Next Session Notes\n\n## Current Status\n- Authentication system 80% complete\n- JWT validation working\n- Still need to add refresh token logic\n\n## TODO\n- [ ] Implement token refresh endpoint\n- [ ] Add rate limiting to auth routes\n- [ ] Write tests for edge cases\n\n## Known Issues\n- Login route returns 500 on invalid email format (needs validation)\n\n## Context\nWorking in `src/auth/` directory. Database migrations are in `migrations/` and need to be run before testing.\n"
}
}Example Output
JSON Response
json
{
"success": true,
"path": "/path/to/project/.codemap/sessions/NEXT_SESSION.md",
"size": 425
}When to Use This Tool
-
Use
- Leave notes for the next person working on the project
- Document incomplete work or work-in-progress
- Create TODO lists for future sessions
- Warn about known issues or gotchas
- Provide context that won't be obvious later
- Leave critical instructions (migrations, env vars, etc.)
codemap_next_session when you need to:
Common Patterns
End-of-Day Handoff
Perfect for team environments or multi-day features.
Incomplete Feature Warning
Prevents duplicated debugging effort.
Critical Setup Instructions
Ensures important steps aren't forgotten.
1. Finish work for the day
2. codemap_next_session({ text: "Summary + TODOs" })
3. codemap_close({ summary: "Brief summary" })
4. Next person reads NEXT_SESSION.md on orientPerfect for team environments or multi-day features.
Incomplete Feature Warning
1. Working on feature, hit blocker
2. codemap_next_session({ text: "Status + Known Issues" })
3. Next session knows context immediatelyPrevents duplicated debugging effort.
Critical Setup Instructions
1. Made database changes
2. codemap_next_session({ text: "MUST RUN: npm run migrate" })
3. Next session sees warning on startEnsures important steps aren't forgotten.
Pro Tips
- Overwrites existing file: Each call replaces NEXT_SESSION.md completely
- Markdown format: Use headers, lists, code blocks for clarity
- Shows on orient: The file is referenced in session checklists
- Version control friendly: .md file can be committed to git
- Template approach: Keep a standard format for consistency
Best Practices
- Use clear headers (## Current Status, ## TODO, ## Known Issues)
- Include file paths and line numbers when relevant
- Mention any setup steps required (migrations, env vars, etc.)
- Keep it actionable - focus on what needs doing, not what was done
- Update before closing session if situation changes
Common Mistakes
❌ Mistake: Writing a novel - too much detail
✅ Instead: Focus on actionable items and critical context
❌ Mistake: Forgetting to update when plans change
✅ Instead: Rewrite notes if priorities shift during session
❌ Mistake: Using as session summary
✅ Instead: Use
❌ Mistake: Not mentioning critical setup steps
✅ Instead: Always include "Run X before starting" if applicable
❌ Mistake: Leaving vague TODOs like "fix the bug"
✅ Instead: Be specific: "Fix null pointer in UserService.ts line 42"
✅ Instead: Focus on actionable items and critical context
❌ Mistake: Forgetting to update when plans change
✅ Instead: Rewrite notes if priorities shift during session
❌ Mistake: Using as session summary
✅ Instead: Use
codemap_close({ summary }) for summaries, next_session for instructions❌ Mistake: Not mentioning critical setup steps
✅ Instead: Always include "Run X before starting" if applicable
❌ Mistake: Leaving vague TODOs like "fix the bug"
✅ Instead: Be specific: "Fix null pointer in UserService.ts line 42"