claude-session-kit

Mine your Claude Code sessions for patterns. Back up every session, summarize each one with an LLM, then cross-reference across sessions to surface recurring friction, missing skills, codebase smells, documentation gaps, and test coverage holes — every finding cites the real sessions it came from.

flowchart LR
  jsonl["~/.claude/projects/<br/>*.jsonl<br/><i>deleted after 30d</i>"]

  subgraph csk["claude-session-kit"]
    direction TB
    backup["csk backup"] --> store[("SQLite index<br/>+ blob mirror<br/>+ FTS5 search")]
    store --> analyze["csk analyze<br/>per-session LLM summary<br/><i>intent · friction · corrections</i>"]
    analyze --> patterns["csk patterns<br/>project / global<br/><i>cross-session findings</i>"]
  end

  jsonl --> backup

  findings["Findings<br/>• repetition / skill_gap<br/>• correction_pattern<br/>• codebase_smell / api_friction<br/>• documentation_gap / test_coverage_gap<br/><br/><b>→ CLAUDE.md · new skill · refactor · docs · tests</b>"]
  patterns --> findings

  surfaces["CLI&nbsp;&nbsp;|&nbsp;&nbsp;Web dashboard (csk serve)&nbsp;&nbsp;|&nbsp;&nbsp;MCP server (agents)"]
  store --- surfaces
  findings --- surfaces

Why

Your Claude Code sessions are the highest-signal record of how you actually work with an AI — every correction you made, every time the assistant got stuck on the same thing, every recurring intent. But:

1. They disappear. Claude Code deletes sessions after 30 days by default (cleanupPeriodDays).
2. One session tells you what happened that time. The interesting signal — "I keep redirecting the assistant away from any casts", "the /serve skill keeps getting over-engineered", "we have three sessions failing the same handover bug" — lives across sessions, and nothing in Claude Code compares them for you.
3. Patterns that matter become invisible. If you correct the same mistake 10 times in 10 different sessions, no one is watching and writing a CLAUDE.md rule for you.

claude-session-kit closes the loop:

• Backup — nightly mirror of every JSONL, subagent log, tool result, and meta file before the cleanup timer fires.
• Analyze (csk analyze) — per-session LLM summary extracting intent, what was tried, outcome, friction events, and verbatim user corrections.
• Detect patterns (csk patterns) — feeds N enriched summaries into one cross-session LLM call and returns actionable findings. Project mode scopes to one repo (or a worktree group); global mode requires evidence from ≥2 distinct projects so it only keeps universal habits. Findings span 8 kinds — repetition, correction_pattern, friction, skill_gap, codebase_smell, documentation_gap, test_coverage_gap, api_friction — and each one cites the sessions it came from so the remedy is grounded, not hallucinated.
• Remedies that aren't "just add a CLAUDE.md rule" — the prompt is deliberately built to route evidence about code to refactor/docs/tests suggestions, not behavioral rules. If you keep pasting the same snippet, that's a missing skill. If the same function keeps tripping up the assistant, that's a codebase smell.
• Three surfaces, one core — CLI, local web dashboard (csk serve: project tree, full-text search, runs Analyze/Patterns with cost preview), and an MCP server so agents like Claude Code can query your own history as a tool.

Features

• Zero data loss — mirrors non-JSONL files too (tool results, screenshots, meta). Anything that would disappear with the session gets preserved.
• Incremental backups — size + mtime check, with 2-second tolerance for remote filesystems.
• Multi-host / multi-user — every record carries host_id and user_id, so a team can point multiple machines at one remote store.
• Pluggable storage — SessionStore (SQLite today; Postgres on the roadmap) and BlobStore (local filesystem, rclone; native S3 on the roadmap) interfaces. Swap backends without touching call sites.
• Rclone-powered cloud — one backend gives you Google Drive, OneDrive, Dropbox, S3, B2, and 60+ other providers.
• MCP-first — the CLI, the web dashboard, and the MCP server share a single core, so every capability is available to humans and agents.
• Free-form output language — --lang <label> on csk analyze and csk patterns lets the LLM respond in whatever language you name (auto, en, 한국어, 日本語, …). Identifiers and verbatim quotes stay in their original form.
• Project allow/blocklists — exclude personal or client work from shared stores.

Install

npm install -g claude-session-kit

Or from source:

git clone https://github.com/penspanic/claude-session-kit.git
cd claude-session-kit
npm install
npm run build
npm link

Quick start

# One-shot local backup
csk backup

# Check what was archived
csk status

# Daily backup via cron (3:30 AM by default; HOUR / MINUTE to override)
./scripts/install-cron.sh

Data lives at ~/.claude-session-kit/ by default:

~/.claude-session-kit/
├── config.json      # host/user id, backend choice, project allow/block
├── index.db         # SQLite index
└── mirror/          # per-project jsonl + subagents + tool-results

Cloud storage (rclone)

claude-session-kit delegates cloud uploads to rclone, so any rclone-supported backend works — Google Drive, OneDrive, Dropbox, S3, Backblaze B2, etc.

1. Install rclone and configure a remote

brew install rclone          # macOS
rclone config                # interactive setup for your provider
# ...creates a remote named e.g. "gdrive"

2. Point CSK at the remote

Edit ~/.claude-session-kit/config.json:

{
  "blobType": "rclone",
  "blobRclone": { "remote": "gdrive:claude-sessions" }
}

Or use environment variables:

export CSK_BLOB_TYPE=rclone
export CSK_RCLONE_REMOTE=gdrive:claude-sessions
csk doctor    # verify the remote is reachable
csk backup

MCP integration

Add to your Claude Code .mcp.json:

{
  "mcpServers": {
    "csk": {
      "command": "csk-mcp"
    }
  }
}

Current tools:

| Tool | Description | | --- | --- | | csk_backup_status | Most recent backup run, host/user, and session totals. | | csk_list_sessions | List sessions with parsed metadata. Filter by project, host, kind, date range, pagination. | | csk_get_session | Fetch a single session by source_key, with parsed details. | | csk_recent | Per-project session counts over the last N days. | | csk_search | Full-text search (FTS5) over user-message content. Returns highlighted snippets with session context. | | csk_summarize | Return a session's LLM summary. Generates on demand (if ANTHROPIC_API_KEY is set) or returns cache. | | csk_recap | List summaries over a date range, grouped by project. "What did I do this week?" in one tool call. | | csk_patterns | Cross-session findings from the latest (or specified) csk patterns run. Filter by scope (project/global), project_dir, kind. |

Configuration reference

| Env var | Config key | Default | | --- | --- | --- | | CSK_DATA_DIR | — | ~/.claude-session-kit | | CSK_SOURCE_DIR | — | ~/.claude/projects | | CSK_STORE_TYPE | storeType | sqlite | | CSK_BLOB_TYPE | blobType | fs | | CSK_RCLONE_REMOTE | blobRclone.remote | — | | CSK_RCLONE_BIN | blobRclone.rcloneBin | rclone (on PATH) | | CSK_RCLONE_CONFIG | blobRclone.configPath | rclone default |

Project filters in config.json:

{
  "projects": {
    "allow": ["-Users-me-OpenSource"],   // empty means "all"
    "block": ["-Users-me-ClientXYZ"]
  }
}

Commands

csk backup                        Mirror the source directory into the blob store
csk status [--json]               Summarize the last backup and the index
csk status --host <id>            Filter status by host_id
csk analyze [opts]                LLM-summarize parsed sessions (needs ANTHROPIC_API_KEY)
csk patterns project --dir <X>    Find patterns in one project (repeatable --dir)
csk patterns global               Find cross-project habits (evidence must span ≥2 projects)
csk serve [--port 4567]           Launch the read-only web dashboard
csk doctor                        Verify source, store, and blob backend

csk analyze

Generates structured summaries (one-liner, what-tried, outcome, notable events, friction events, user corrections, intent, tags) using Anthropic's API. Summaries are cached in SQLite keyed by the source file's mtime so re-runs skip anything still current.

export ANTHROPIC_API_KEY=sk-ant-...
csk analyze --limit 10                               # first 10 unanalyzed sessions
csk analyze --project -Users-me-Repo --since 2026-04-01
csk analyze --dry-run --limit 50                     # preview candidates without calling the API
csk analyze --model claude-haiku-4-5-20251001        # override model
csk analyze --lang ko                                # respond in Korean (identifiers stay English)

By default uses Haiku. For 1000 sessions expect ~$3-6 in token costs; the CLI prints per-session usage.

csk patterns

Feeds enriched summaries back to an LLM as one cross-session call, emits structured findings (missing skills, recurring frictions, codebase smells, documentation gaps, test-coverage gaps, API friction) with evidence citing the source sessions. Two modes:

# Project mode — one logical project (possibly many worktrees)
csk patterns project --dir -Users-me-Repo
csk patterns project --dir -Users-me-Repo --dir -Users-me-Repo-worktree-1
csk patterns project --match Repo      # substring-match all project_dirs

# Global mode — habits that show up across projects (≥2 distinct project_dirs required)
csk patterns global --limit 200
csk patterns global --lang 한국어

Findings persist in csk_findings tied to a run_id. View via the web dashboard (/patterns) or csk_patterns MCP tool. Runs without -y show a cost estimate and ask for confirmation first.

csk serve

Localhost web dashboard (read-only by default; Analyze and Patterns pages can trigger LLM runs if ANTHROPIC_API_KEY is set or provided via an in-browser modal).

csk serve                   # http://127.0.0.1:4567
csk serve --port 8080 --host 127.0.0.1

Pages: Home (stats + recent projects), per-project session tree (main sessions with collapsible subagents), session detail, full-text search, Analyze (cost preview + per-session selection), Patterns (project/global scope, project picker, findings + source sessions).

Architecture at a glance

┌──────────┐     ┌───────────┐     ┌─────────────────────┐
│  csk CLI │     │  csk-mcp  │     │  (future dashboards)│
└────┬─────┘     └─────┬─────┘     └──────────┬──────────┘
     │                 │                      │
     └────────────┬────┴──────────┬───────────┘
                  │               │
              ┌───▼───┐       ┌───▼──────┐
              │ core  │──────▶│ BlobStore│  fs  | rclone
              │       │       └──────────┘  (→ GDrive / OneDrive / S3 / ...)
              │       │       ┌────────────┐
              │       │──────▶│SessionStore│  sqlite
              └───────┘       └────────────┘  (→ postgres planned)

Roadmap

• v0.1 — backup, index, MCP backup_status. ✅
• v0.2 — session parsing, FTS5 search, LLM summaries, interactive analyze, web dashboard, cross-session patterns detection. (current) ✅
• v0.3 — native S3 blob store (no rclone), rclone setup docs for GDrive/OneDrive.
• v0.4 — PostgresSessionStore for multi-host team aggregation; deeper code-aware pattern detection (feed cited source files to the LLM).

Contributing

See CONTRIBUTING.md. PRs, backend implementations, and design feedback all welcome.

License

MIT. See LICENSE.