https://github.com/penspanic/claude-session-kit
Back up, index, and analyze Claude Code session logs. Exposes an MCP server so AI agents can query the archive natively.
https://github.com/penspanic/claude-session-kit
Last synced: 2 months ago
JSON representation
Back up, index, and analyze Claude Code session logs. Exposes an MCP server so AI agents can query the archive natively.
- Host: GitHub
- URL: https://github.com/penspanic/claude-session-kit
- Owner: penspanic
- License: mit
- Created: 2026-04-16T15:11:32.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-16T17:06:35.000Z (3 months ago)
- Last Synced: 2026-04-16T17:30:56.366Z (3 months ago)
- Language: TypeScript
- Homepage: https://github.com/penspanic/claude-session-kit
- Size: 180 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
[](https://www.npmjs.com/package/claude-session-kit)
[](https://github.com/penspanic/claude-session-kit/actions/workflows/ci.yml)
[](./LICENSE)
```mermaid
flowchart LR
jsonl["~/.claude/projects/
*.jsonl
deleted after 30d"]
subgraph csk["claude-session-kit"]
direction TB
backup["csk backup"] --> store[("SQLite index
+ blob mirror
+ FTS5 search")]
store --> analyze["csk analyze
per-session LLM summary
intent · friction · corrections"]
analyze --> patterns["csk patterns
project / global
cross-session findings"]
end
jsonl --> backup
findings["Findings
• repetition / skill_gap
• correction_pattern
• codebase_smell / api_friction
• documentation_gap / test_coverage_gap
→ CLAUDE.md · new skill · refactor · docs · tests"]
patterns --> findings
surfaces["CLI | Web dashboard (csk serve) | 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 ` 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
```bash
npm install -g claude-session-kit
```
Or from source:
```bash
git clone https://github.com/penspanic/claude-session-kit.git
cd claude-session-kit
npm install
npm run build
npm link
```
## Quick start
```bash
# 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](https://rclone.org/), so any rclone-supported backend works — Google Drive, OneDrive, Dropbox, S3, Backblaze B2, etc.
**1. Install rclone and configure a remote**
```bash
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`:
```json
{
"blobType": "rclone",
"blobRclone": { "remote": "gdrive:claude-sessions" }
}
```
Or use environment variables:
```bash
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`:
```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`:
```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 Filter status by host_id
csk analyze [opts] LLM-summarize parsed sessions (needs ANTHROPIC_API_KEY)
csk patterns project --dir 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.
```bash
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:
```bash
# 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).
```bash
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](./CONTRIBUTING.md). PRs, backend implementations, and design feedback all welcome.
## License
MIT. See [LICENSE](./LICENSE).