chrisguillory/claude-session-mcp

claude-session-mcp

Archive and restore Claude Code sessions across machines with full conversation history.

⚠️ Critical: Prevent Automatic Session Deletion

Claude Code deletes session .jsonl files after 30 days by default. Add this to ~/.claude/settings.json before using this tool:

{
  "cleanupPeriodDays": 99999
}

Installation

# Run without installation
uvx --from git+https://github.com/chrisguillory/claude-session-mcp claude-session --help

# Or install locally
git clone https://github.com/chrisguillory/claude-session-mcp
cd claude-session-mcp
uv sync

Quick Start

# Clone a session directly and launch Claude
claude-session clone <session-id> --launch

# Or archive to local file
claude-session archive <session-id> output.json

# Archive to GitHub Gist (requires GITHUB_TOKEN)
export GITHUB_TOKEN=$(gh auth token)
claude-session archive <session-id> gist://

# Restore from file (with optional auto-launch)
claude-session restore archive.json --launch

# Restore from Gist
claude-session restore gist://<gist-id> --launch

Features

• Local storage: Save sessions as JSON or compressed (zstd)
• GitHub Gist: Private/public Gist storage (100MB limit)
• Path translation: Automatically translates file paths when restoring to different directories
• Agent sessions: Captures main session + all agent sub-sessions
• UUIDv7 session IDs: Restored sessions use time-ordered UUIDv7 (vs Claude's random UUIDv4)

Clone vs Native Fork

Claude Code 2.0.73+ supports --fork-session. Here's how it compares to our clone command:

Key difference: Native fork is /compact under the hood - it copies a summary + recent messages, not actual conversation history. Our clone preserves everything: all tool calls, thinking blocks, agent sub-sessions, and intermediate steps.

Why compaction loses context: Auto-compaction triggers at ~75% context utilization (not 90%+). Claude Code reserves 25% headroom for reasoning quality. When forking, you get the summary blob, not the rich history that led to decisions.

Commands

Clone

Direct session-to-session cloning without intermediate archive file:

claude-session clone <session-id>

# Arguments:
#   session-id     Session ID to clone (full UUID or prefix)

# Options:
#   --project, -p      Target project directory (default: current)
#   --no-translate     Don't translate file paths
#   --launch, -l       Launch Claude Code after clone
#   --verbose, -v      Verbose output

Archive

claude-session archive <session-id> <output>

# Arguments:
#   session-id    Session ID to archive (find in ~/.claude/projects/)
#   output        File path or gist:// or gist://<gist-id>

# Options:
#   --format, -f           json or zst (auto-detected from extension)
#   --gist-token           GitHub token (or use GITHUB_TOKEN env)
#   --gist-visibility      public or secret (default: secret)
#   --gist-description     Gist description
#   --verbose, -v          Verbose output

Restore

claude-session restore <archive>

# Arguments:
#   archive        File path or gist://<gist-id>

# Options:
#   --project, -p      Target project directory (default: current)
#   --no-translate     Don't translate file paths
#   --launch, -l       Launch Claude Code after restore
#   --gist-token       GitHub token for private gists
#   --verbose, -v      Verbose output

MCP Server

The MCP server exposes archive/restore as Claude Code tools:

{
  "mcpServers": {
    "claude-session": {
      "command": "uv",
      "args": [
        "run",
        "mcp-server.py"
      ],
      "cwd": "/path/to/claude-session-mcp"
    }
  }
}

Tools:

• clone_session - Clone a session directly (no archive file needed)
• save_current_session - Archive current session (local storage only)
• restore_session - Restore archived session (local files only)

Technical Details

Session Storage

Sessions are stored as JSONL files at ~/.claude/projects/<encoded-path>/<session-id>.jsonl.

Path Encoding: Claude Code encodes working directory paths for filesystem safety:

• / → -
• . → -
• (space) → -
• ~ (tilde) → -

Example: /Users/chris/My Project.app → -Users-chris-My-Project-app

Session IDs: Claude Code uses UUIDv4 (random). This tool generates UUIDv7 (time-ordered) for cloned/restored sessions:

The version digit (4 or 7) is at position 15 (first digit of third group).

Pydantic Models

914 lines, 56 classes covering 10 record types (user, assistant, system, local commands, compact boundaries, API errors, summaries, file history snapshots, queue operations). Validated on 78K+ records (100% valid).

Compatibility

Claude Code 2.0.35 - 2.0.64

Claude Code Architecture Reference

Understanding what gets captured in session files.

Built-in Agents:

Agent invocations create separate agent-{agentId}.jsonl files, referenced via isSidechain: true in the main session. Our clone/archive captures all sidechains; native fork does not.

Pre-flight Requests (not stored in session files):

Extended Thinking:

• Stored in thinking content blocks with signature field
• NOT counted in context window (output tokens only)
• Configure cap via MAX_THINKING_TOKENS env var
• See for deeper research on ThinkingMetadata structure

Prompt Cache (explains cache_read_input_tokens field):

Cache invalidates when: user edits/rewinds message, TTL expires, or content prefix changes. Minimum cacheable: ~1,024 tokens.

Token Economics (December 2025):

API-only Features (not in Claude Code):

Session Startup Overhead:

First response latency depends heavily on MCP configuration. With many MCPs:

• ~100 /count_tokens calls (one per tool)
• MCP OAuth handshakes (Linear, Sentry, Notion, etc.)
• Agent warmup requests (Plan/Explore)

Observed: ~5 minutes first response with 108 tools loaded. Reduce MCPs for faster startup.

Claude Code Version Sources

Authoritative sources for checking Claude Code versions:

Note: The deprecated claude-ai NPM package has been superseded by @anthropic-ai/claude-code.

Updating for New Claude Code Versions

When a new Claude Code version is released:

1. Detect - Run uv run scripts/validate_models.py to find schema gaps
2. Analyze - Run uv run scripts/analyze_model_quality.py to study new fields
3. Update - Add new Pydantic models/fields in src/models.py with version annotations
4. Bump - Update SCHEMA_VERSION and CLAUDE_CODE_MAX_VERSION in src/models.py
5. Validate - Re-run validation for 100% success rate
6. Export - Run uv run scripts/export_schema.py to regenerate session-schema.json
7. Commit - Format: Update models for Claude Code X.X.X compatibility (schema vX.X.X)

License

MIT