---

Why session-insight?

AI coding sessions accumulate rich context — file changes, user requests, decisions, errors, git history — but that context vanishes when the session ends. Static rule files cannot answer "what did I work on today?" or "what went wrong in that last session?".

session-insight gives your AI assistant a read-only lens into all past sessions:

• Session analytics — extract structured insights from JSONL: file changes, decisions, errors, tool usage, todo progress
• Multi-source collection — read Claude Code JSONL, OpenCode SQLite sessions, and Codex JSONL sessions
• Real work filtering — Codex collection ignores developer/system prompts and environment metadata, keeping only real user work content
• EnrichedSummary — returns structured JSON instead of Markdown templates, letting the calling LLM synthesize concise summaries at zero extra API cost
• Cross-project git logs — collect commit history across all projects with date range, project, and author filters
• Semantic classification — bash commands classified into 9 categories (build/test/deploy/debug/network/run/git/explore/other)
• Session handoff — generate structured context for seamless session continuation

Quick Start

# Install
npm install -g @morningljn/mcp-session-insight

# One-command setup
claude mcp add session-insight -- npx @morningljn/mcp-session-insight

Restart your AI assistant and it can now query all past sessions.

Supported Sources

Source	Default Location	Notes
Claude Code	~/.claude/projects/	Reads project-scoped JSONL sessions
OpenCode	~/.local/share/opencode/opencode.db	Reads SQLite session, message, and part tables
Codex	~/.codex/sessions/	Reads JSONL sessions and filters hidden prompts/context

Manual Setup

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "session-insight": {
      "command": "npx",
      "args": ["@morningljn/mcp-session-insight"]
    }
  }
}

Tools

Tool	Description
collect_project_sessions	Use first for daily reports or source-specific collection; returns source counts and structured sessions
list_sessions	List all sessions with optional project filter and limit
show_session	Show session metadata (supports prefix matching on session ID)
search_sessions	Search sessions by keyword in content or ID
get_session_summary	Returns EnrichedSummary JSON for LLM synthesis
get_session_changes	Get file changes (created / modified / read)
get_session_requests	Get deduplicated user requests
get_session_todos	Get todo progress snapshots
get_session_errors	Get errors and issues with context
get_session_decisions	Get key decisions from thinking blocks
get_session_conversation	Get conversation history with role filter
get_git_logs	Collect git commit logs across projects

Process Lifecycle

The server exits automatically when the MCP stdio input closes, so old Claude Code sessions should not leave orphaned npm exec or node processes behind. For an extra safety net, set SESSION_INSIGHT_IDLE_TIMEOUT_MS to a positive number of milliseconds:

{
  "mcpServers": {
    "session-insight": {
      "command": "npx",
      "args": ["@morningljn/mcp-session-insight"],
      "env": {
        "SESSION_INSIGHT_IDLE_TIMEOUT_MS": "1800000"
      }
    }
  }
}

get_session_summary (EnrichedSummary)

Returns structured JSON instead of formatted text. The calling LLM reads the data and synthesizes a concise summary — zero extra API cost.

{
  "sessionDuration": "116min",
  "messageDensity": "low",
  "classifiedBash": [{ "cmd": "npm test", "category": "test" }],
  "errorsWithContext": [{ "message": "...", "trigger": "Bash", "relatedFile": "src/server.ts" }],
  "fileChangeGroups": [{ "directory": "src", "created": ["git.ts"], "modified": [] }],
  "dedupedRequests": ["refactor summary to structured JSON"],
  "decisions": ["use Jaccard trigram for dedup"],
  "toolStats": { "Bash": 93, "Read": 39, "Edit": 38 },
  "gitActions": ["git commit -m \"feat: ...\"", "git push origin main"]
}

get_git_logs

Collect git commit history across all discovered projects:

[
  {
    "project": "/Users/user/project",
    "projectName": "my-app",
    "commits": [
      { "hash": "a1b2c3d", "message": "feat: add auth", "author": "user", "date": "2026-05-20T10:00:00+08:00", "files": ["src/auth.ts"] }
    ]
  }
]

Architecture

┌───────────────────┐   stdio    ┌──────────────────┐   read     ┌──────────────────────────┐
│   MCP Client      │◄─────────►│ session-insight  │◄──────────►│ ~/.claude/projects/      │
│ Claude/OpenCode/  │   JSON    │     server       │            │ ~/.local/share/opencode/ │
│      Codex        │           │                  │            │ ~/.codex/sessions/       │
└───────────────────┘           └───────┬──────────┘            └──────────────────────────┘
                                        │
                                 ┌──────┴──────┐
                                 │ Provider    │
                                 │ Registry    │
                                 └──────┬──────┘
                                        │
                                 ┌──────┴──────┐
                                 │  Extractor  │   Git Log
                                 │  (summary,  │   Collector
                                 │   classify, │
                                 │   dedup,    │
                                 │   errors)   │
                                 └─────────────┘

Key design decisions:

• Stateless — no app-owned database, no persistence, reads existing session stores on each request
• Fixture-friendly providers — provider roots are configurable so tests do not scan real local history
• LLM-friendly output — structured JSON that the calling LLM synthesizes into natural language

Development

npm install
npm test        # run tests with vitest
npm run build   # compile TypeScript
npm start       # start MCP server

License

MIT