Session Manager - Project Integration

[djdarcy]

Summary

Evolve claude-session-logger into a full session manager with project-centric session organization, one-click resume, and viewer integration.

Vision

Currently, to resume a session users must type claude -r {guid}. This feature creates a session management folder in each project with:

• Resume scripts - One-click session resume
• Sesslog links - Quick access to session logs
• Viewer launchers - Launch Claude Code History Viewer
• Session index - Metadata for all project sessions

Proposed Structure

{project}/private/claude-sessions/       # Or .claude-sessions/ as fallback
├── sesslogs/                            # Links to sesslog folders
│   ├── 2026-01-29__session-name -> ~/.claude/sesslogs/{full}/
│   └── 2026-01-31__another -> ~/.claude/sesslogs/{full}/
├── resume/                              # Session resume scripts
│   ├── resume-session-name.bat          # Windows: claude -r {guid}
│   ├── resume-session-name.sh           # Unix: claude -r {guid}
│   └── resume-latest.bat                # Resume most recent
├── transcripts/                         # Links to .jsonl files
│   └── session-name.jsonl -> ~/.claude/projects/.../guid.jsonl
├── exports/                             # Session exports (Issue #3)
│   └── 2026-01-29__session-name__export.md
├── viewer/                              # History Viewer launchers
│   ├── view-session-name.bat
│   └── view-all.bat
└── .session-index.json                  # Metadata index

Smart Path Detection

Not all users have private/claude/ structure. Detection logic:

1. Check for {cwd}/private/claude-sessions/ → Use if exists
2. Check for {cwd}/private/ → Create claude-sessions/ there
3. Fallback: Create {cwd}/.claude-sessions/ (hidden)

Override via:

• CLAUDE_SESSION_PATH environment variable
• .claude-session-config.json in project root

Resume Scripts

Auto-generated on SessionStart:

Windows (resume-session-name.bat):

@echo off
claude -r 833a100e-d959-47aa-9db2-d22fdb6d7659

Unix (resume-session-name.sh):

#!/bin/bash
claude -r 833a100e-d959-47aa-9db2-d22fdb6d7659

Session Index

JSON file for quick lookup and tooling:

{
  "project_path": "C:\code\my-project",
  "sessions": [
    {
      "id": "833a100e-...",
      "name": "feature-implementation",
      "created": "2026-01-29T10:00:00Z",
      "last_active": "2026-01-31T18:00:00Z",
      "transcript": "~/.claude/projects/.../guid.jsonl",
      "sesslog": "~/.claude/sesslogs/feature__833a.../"
    }
  ]
}

Claude Code History Viewer Integration

Create launcher scripts for installed viewer:

@echo off
claude-history-viewer "C:\Users\...\.claude\projects\...\guid.jsonl"

Related Issues

• Bidirectional Project-Sesslog Linking #2 (Bidirectional Linking) - Sesslogs links extend this
• Export Auto-Detection and Organization #3 (Export Auto-Detection) - Exports go in exports/ folder
• Dazzlelink Test ToolSearch logging with MCP-heavy environment #11 - Use for symlink creation

Benefits

Benefit	Description
One-click resume	Double-click script to resume any session
Project history	See all sessions for a project in one place
Viewer access	Launch history viewer for any session
Export organization	Exports organized per-session

Configuration

For users without private/ folder:

• Falls back to .claude-sessions/ in project root
• Auto-added to .gitignore
• Configurable via environment or config file

Analysis

See 2026-01-31__18-53-45__session-manager-project-integration.md for detailed analysis.

[djdarcy]

Clarification: Compound Path Structure

The path needs three configurable components, not just {project}:

{project-base} / {internal-folder} / {claude-sessions-name}

Examples

Layout	project-base	internal-folder	sessions-name	Result
Standard	C:\code\proj	private	claude-sessions	.../private/claude-sessions
Multi-branch	C:\code\proj	local\private	claude-sessions	.../local/private/claude-sessions
Simple	C:\code\proj	``	.claude-sessions	.../.claude-sessions

Proposed Configuration

{
  "session_manager": {
    "project_base": "auto",
    "internal_folder": "private",
    "sessions_folder": "claude-sessions",
    "fallback_internal": "",
    "fallback_sessions": ".claude-sessions"
  }
}

This handles:

• Standard private/ layouts
• Multi-branch setups with local/private/
• Simple projects with hidden .claude-sessions/
• Custom user preferences

[djdarcy]

Addendum: Worktree/Multi-Branch Awareness

With git-repokit style multi-branch setups (worktrees), we need to avoid duplicating session data per branch.

Structure

C:\code\PROJECTNAME\
├── local\                    # Private branch
│   └── private\claude-sessions\  # PRIMARY (real data)
├── github\                   # Public branch
│   └── private\claude-sessions   # SYMLINK → local's
└── other-branch\
    └── private\claude-sessions   # SYMLINK → local's

Rationale

Sessions belong to the project, not the branch. When switching between local/ and github/ worktrees, users should see the same session history.

Proposed Configuration

{
  "session_manager": {
    "worktree_mode": "shared",      // "shared" | "per-branch"
    "primary_branch": "local",
    "link_other_branches": true
  }
}

Behavior

1. Detect worktree setup (multiple branch folders at project level)
2. Use local/ as primary (or configurable)
3. Create symlinks in other branches pointing to primary
4. Option for per-branch sessions if user prefers isolation

[djdarcy]

Addendum: Flexible Path Template System

The path structure needs four components with flexible ordering. Different users have different layouts:

Option A: {project}/{internal}/{branch}/{sessions} → .../private/local/claude-sessions
Option B: {project}/{branch}/{internal}/{sessions} → .../local/private/claude-sessions

Proposed: Template-based Configuration

{
  "session_manager": {
    "path_template": "{project}/{branch}/{internal}/{sessions}",
    "variables": {
      "project": "auto",
      "branch": "auto",
      "internal": "private",
      "sessions": "claude-sessions"
    }
  }
}

Template Examples

Style	Template	Result
git-repokit	{project}/{branch}/{internal}/{sessions}	.../local/private/claude-sessions
Branch inside	{project}/{internal}/{branch}/{sessions}	.../private/local/claude-sessions
No branches	{project}/{internal}/{sessions}	.../private/claude-sessions
Hidden	{project}/{sessions}	.../.claude-sessions

Branch Variable Modes

• "auto" - Detect worktree name dynamically
• "static:local" - Always use "local"
• "omit" - Exclude branch from path

This gives maximum flexibility for any project layout.