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

Manual Setup

Add to ~/.claude/mcp.json:

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

Tools

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