codemap_session_start

Start a new session. Orients to the project, checks for premature termination, initializes session tracking, and loads all persistent stores (groups, labels, macros, routines, checklists).

sessionstartorientinitializationtracking

Parameters

Name	Type	Required	Description
`rootPath`	`string`	✅ Required	Root directory of the project to start a session for

Usage Examples

MCP Usage (for AI Agents like Claude)

json

{
  "name": "codemap_session_start",
  "arguments": {
    "rootPath": "/path/to/your/project"
  }
}

Example Output

JSON Response

json

{
  "success": true,
  "sessionStarted": true,
  "rootPath": "/path/to/your/project",
  "stats": {
    "files": 299,
    "symbols": 3099,
    "dependencies": 173
  },
  "parsers": [
    {
      "name": "@egentica/codemap-parser-typescript",
      "version": "0.1.0",
      "extensions": ".ts, .tsx, .js, .jsx"
    },
    {
      "name": "@egentica/codemap-parser-vue",
      "version": "0.1.0",
      "extensions": ".vue"
    }
  ],
  "checklist": {
    "items": [
      {
        "text": "Review .codemap/sessions/NEXT_SESSION.md to see if there are any outstanding tasks",
        "priority": "high"
      },
      {
        "text": "Label files with appropriate architectural patterns as you encounter them",
        "priority": "medium"
      },
      {
        "text": "Update status labels as implementation progresses",
        "priority": "medium"
      }
    ]
  }
}

ℹ️When to Use This Tool

codemap_session_start

Begin a new work session on a project
Initialize session tracking for file operations
Load project context (stats, parsers, checklists)
Check if a previous session was left open (orphaned)
Switch to a different project with full initialization

💡Common Patterns

Standard Session Start Workflow

1. codemap_session_start({ rootPath: "/project" })
2. Review session response (stats, checklist, existing activity)
3. Check for orphaned sessions or pending tasks
4. Begin working on project
5. Later: codemap_close() to properly end session

Always start sessions explicitly to ensure proper tracking.

Multi-Day Feature Development

1. Day 1: codemap_session_start({ rootPath: "/project" })
2. Work on feature...
3. Day 1 end: codemap_close({ summary: "Started feature X" })
4. Day 2: codemap_session_reopen({ sessionId: "..." })
5. Continue work on feature X

Use session close/reopen for long-running work.

Project Switching Pattern

1. Working on Project A
2. codemap_session_start({ rootPath: "/project-b" })
3. Work on Project B
4. codemap_session_start({ rootPath: "/project-a" })
5. Back to Project A

Each call to start initializes tracking for that specific project.

💡Pro Tips

Detects orphaned sessions automatically: If a previous session wasn't properly closed (crash, forced quit), session_start will detect it and show you what was being worked on.
Loads all persistent stores: Calling session_start loads groups, labels, macros, routines, and checklists. This ensures all project context is available.
Returns project stats immediately: No need to call a separate stats tool - the response includes file count, symbol count, and dependency count.
Checklist appears on start: Session-start checklists (added via codemap_checklist_add_item) automatically appear when you start a session, providing workflow reminders.
Idempotent: Calling session_start on an already-active session doesn't create a duplicate - it returns the existing session info with current activity summary.
Initializes transaction log: All file operations (create, update, delete) and group/annotation changes are automatically tracked after session start.

✅Best Practices

Always call session_start at the beginning of a work session to ensure proper tracking
Review the checklist items in the response - they contain project-specific workflow reminders
Check currentActivity if returned - it means a session was already active and shows what was being worked on
Use meaningful session summaries when closing to help future session reopening
For long-running features, use close/reopen pattern instead of leaving sessions open indefinitely

⚠️Common Mistakes

❌ Mistake: Working without starting a session first
✅ Instead: Always call session_start before beginning work to enable tracking

❌ Mistake: Starting a new session when one is already active without checking the response
✅ Instead: Check the response for currentActivity - if present, you're continuing an existing session

❌ Mistake: Forgetting to close sessions when done
✅ Instead: Use codemap_close({ summary: "..." }) to properly end sessions and create summaries

❌ Mistake: Starting sessions without a checklist
✅ Instead: Use codemap_checklist_add_item to create workflow reminders that appear on session start

❌ Mistake: Ignoring orphaned session warnings
✅ Instead: If the response shows an orphaned session, review what was being worked on before starting new work

❌ Mistake: Assuming session state persists across CodeMap instances
✅ Instead: Session tracking is in-memory - always call session_start when launching a new CodeMap instance

Parameters

Usage Examples

MCP Usage (for AI Agents like Claude)

Example Output

JSON Response

Related Tools

codemap_session_orient

codemap_session_close

codemap_session_reopen

codemap_checklist_list