Session Management & Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Session Management & Tracking in Everything Claude Code (ECC) is a robust system designed to capture, persist, and resume the state of development work. Its primary purpose is to ensure continuity across different work sessions by documenting what was built, what succeeded, what failed, and what remains to be addressed. This allows the AI agent to pick up exactly where it left off with full context.
The system utilizes a dedicated global storage directory and standardized file formats to manage session data. It integrates automated hooks that trigger at the end of every interaction to update session summaries, alongside manual commands for comprehensive state saving. Sources: commands/save-session.md, scripts/hooks/session-end.js
Architecture and Storage
Session data is stored in a canonical directory within the user's home directory. The system supports both a legacy format and a modern format that includes unique short IDs to prevent collisions.
Session Storage Locations
| Type | Path | Description |
|---|---|---|
| Canonical | ~/.claude/session-data/ | The primary location for modern session files. |
| Legacy | ~/.claude/sessions/ | Backward-compatible location for older session files. |
Sources: commands/save-session.md:21-23, tests/lib/session-manager.test.js:255-257
File Naming Convention
The system uses a strict regex-based naming convention:
- Modern Format:
YYYY-MM-DD-<short-id>-session.tmp - Legacy Format:
YYYY-MM-DD-session.tmp - Short ID Rules: Compatible characters include
a-z,A-Z,0-9, hyphens-, and underscores_.
Sources: commands/save-session.md:27-38, tests/lib/session-manager.test.js:41-55
Core Components and Data Flow
The session management logic is split between manual capture and automated background tracking.
Workflow: Session State Persistence
The following diagram illustrates the flow of data when a session is updated, either through the automated session-end.js hook or the manual save-session command.
This diagram shows the logic used to maintain session continuity between interactions. Sources: scripts/hooks/session-end.js:154-219, commands/save-session.md:15-46
Automation: The Session-End Hook
The session-end.js script runs automatically after each AI response. It parses the JSONL session transcript to extract key metadata without user intervention.
- Transcript Parsing: Extracts user messages, tools used (e.g.,
Edit,Write), and files modified. - Idempotent Updates: It identifies specific markers (
<!-- ECC:SUMMARY:START -->) to update only the auto-generated portion of a session file, preserving manual notes added by the user.
Sources: scripts/hooks/session-end.js:43-100, scripts/hooks/session-end.js:203-210
Session File Structure
Session files are Markdown documents containing specific sections required for context restoration.
| Section | Purpose |
|---|---|
| Metadata Header | Tracks Date, Started, Last Updated, Project, and Branch. |
| What We Are Building | High-level description of the current task. |
| What WORKED | Evidence-based list of successful implementations. |
| What Did NOT Work | Critical log of failed approaches to prevent retries. |
| Current State of Files | A table mapping file paths to status (PASS, FAIL, In Progress). |
| Exact Next Step | Precise instruction for resuming work. |
Sources: commands/save-session.md:55-155, tests/lib/session-manager.test.js:69-100
Metadata Extraction Logic
The session-manager.js (and its test suite) defines how these fields are parsed from the Markdown content:
// Example of metadata parsing logic derived from test cases
const meta = {
title: content.match(/^#\s+(.+)$/m)?.[1],
date: extractHeaderField(content, 'Date'),
project: extractHeaderField(content, 'Project'),
context: content.match(/### Context to Load\s*\n```\n([\s\S]*?)```/)?.[1]
};
Sources: tests/lib/session-manager.test.js:69-100, scripts/hooks/session-end.js:139-152
Session Management Operations
The session-manager utility (implemented in both JavaScript and Rust components) provides the following capabilities:
Discovery and Filtering
- List Sessions: Retrieves sessions sorted by
newest first. - Filtering: Supports filtering by specific date (
YYYY-MM-DD) or searching byshortId. - Pagination: Supports
limitandoffsetfor managing large numbers of session files. - Deduplication: When the same session exists in both canonical and legacy directories, the canonical version (
session-data) is preferred.
Sources: tests/lib/session-manager.test.js:275-340, tests/lib/session-manager.test.js:370-380
Sequence: Resuming a Session
The process for restoring context from a saved session file.
This diagram outlines the logic for context restoration. Sources: tests/lib/session-manager.test.js:365-410, commands/save-session.md:162
Summary of Feature Status Markers
When tracking files within a session, the following statuses are used:
- PASS: Complete: Feature is built and verified with evidence.
- In Progress: Work has started but is not yet finished.
- FAIL: Broken: Implementation attempted but currently failing.
- Not Started: Planned work that hasn't been touched.
Sources: commands/save-session.md:104-109, commands/save-session.md:144-150
Session Management & Tracking is a critical subsystem that bridges the gap between discrete AI interactions. By combining automated transcript analysis with structured manual state saving, it creates a "durable memory" for the development process, minimizing context loss and preventing the repetition of failed strategies.