codemap_close
Close the current session. Runs session:close scripts, saves session summary, resets group display state, and cleans up transaction log. Maintains summary history based on retention settings.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
summary | string | ❌ Optional | Optional summary of what was accomplished this session. Stored in session history for future reference. |
Usage Examples
MCP Usage (for AI Agents like Claude)
json
{
"name": "codemap_close",
"arguments": {
"summary": "Implemented user authentication system with JWT tokens"
}
}Example Output
JSON Response
json
{
"success": true,
"sessionSummary": {
"sessionId": "2026-04-08T14-23-45",
"startedAt": "2026-04-08T14:23:45.123Z",
"duration": "2 hours, 15 minutes",
"summary": "Implemented user authentication system with JWT tokens",
"filesCreated": [
"src/auth/jwt.ts",
"src/middleware/auth.ts",
"tests/auth.test.ts"
],
"filesUpdated": [
"src/api/routes.ts",
"src/config/app.ts",
"package.json",
"tsconfig.json"
],
"filesDeleted": [
"src/auth/old-auth.ts"
],
"filesRenamed": [],
"groupsModified": [
"auth-system",
"api-layer"
],
"notationsAdded": [
"auth-system: Added JWT validation middleware with expiry handling"
],
"annotationsAdded": []
},
"checklist": {
"items": [
{
"text": "Run codemap_audit() to check for architecture violations",
"priority": "high"
},
{
"text": "Create handoff notes with codemap_next_session() if needed",
"priority": "medium"
},
{
"text": "Verify all tests pass before committing",
"priority": "high"
}
]
}
}When to Use This Tool
-
Use
- End a work session properly
- Save session summary for future reference
- Prepare for session reopen (multi-day features)
- Clean up transaction log and reset context
- Trigger session:close scripts and checklists
codemap_close when you need to:
Common Patterns
Standard Close Workflow
Always close sessions to maintain clean session history.
Multi-Day Feature Pattern
Use meaningful summaries for easy session identification.
Quick Close (No Summary)
Summaries are optional but recommended for significant work.
1. Finish work on task/feature
2. codemap_close({ summary: "What you accomplished" })
3. Review checklist items in response
4. Session saved to historyAlways close sessions to maintain clean session history.
Multi-Day Feature Pattern
1. Day 1: Work on feature
2. codemap_close({ summary: "Progress summary" })
3. Save sessionId from response
4. Day 2: codemap_session_reopen({ sessionId })
5. Continue work
6. codemap_close({ summary: "Final summary" })Use meaningful summaries for easy session identification.
Quick Close (No Summary)
1. Minor changes or exploratory work
2. codemap_close()
3. Session saved without descriptionSummaries are optional but recommended for significant work.
Pro Tips
- Summaries are searchable: Session summaries help you find past work. Use descriptive summaries like "Implemented JWT auth" not "worked on stuff".
- Checklist appears on close: Session-close checklists remind you of important steps before finishing (run audit, create handoff notes, etc.).
- Automatic history cleanup: Old sessions are automatically pruned based on retention settings (default: keeps last 5). This prevents history bloat.
- Resets display state: Calling
closeresets group display filters, ensuring fresh context on next session start. - Triggers close scripts: Any scripts registered for
session:close:beforeandsession:close:afterevents run automatically. - Transaction log deleted: The in-memory transaction log is written to permanent history then deleted, freeing resources.
Best Practices
- Always provide meaningful summaries for significant work sessions
- Review the close checklist before finalizing - it contains important reminders
- Use close/reopen pattern for multi-day features rather than leaving sessions open
- Close sessions at logical breakpoints (end of feature, end of day, before switching projects)
- Check the returned file counts to verify expected changes were tracked
Common Mistakes
❌ Mistake: Never closing sessions properly
✅ Instead: Always call
❌ Mistake: Using generic summaries like "worked on project"
✅ Instead: Use specific summaries: "Fixed payment processing bug in checkout flow"
❌ Mistake: Ignoring the close checklist
✅ Instead: Review checklist items - they often remind you to run audit or create handoff notes
❌ Mistake: Closing and immediately starting a new session for the same work
✅ Instead: Use
❌ Mistake: Worrying about closing too often
✅ Instead: Close liberally - it's cheap and maintains clean history
❌ Mistake: Assuming close will fail if no session is active
✅ Instead: Close handles edge cases gracefully - safe to call even if no active session
✅ Instead: Always call
codemap_close() when ending work to save summaries❌ Mistake: Using generic summaries like "worked on project"
✅ Instead: Use specific summaries: "Fixed payment processing bug in checkout flow"
❌ Mistake: Ignoring the close checklist
✅ Instead: Review checklist items - they often remind you to run audit or create handoff notes
❌ Mistake: Closing and immediately starting a new session for the same work
✅ Instead: Use
session_reopen to continue multi-day work❌ Mistake: Worrying about closing too often
✅ Instead: Close liberally - it's cheap and maintains clean history
❌ Mistake: Assuming close will fail if no session is active
✅ Instead: Close handles edge cases gracefully - safe to call even if no active session
Changelog
2 releases- 🐛FixedSession close no longer corrupts
session-transactions.jsonunder concurrent writes. Back-to-backtrack()calls could race and write overlapping JSON fragments (producing}{sequences that failed to parse on next load); replaced with a promise-chain write queue and dirty-flag coalescing so concurrent mutations serialize cleanly.
- 🐛FixedSession close no longer corrupts