{"id":49208017,"url":"https://github.com/penspanic/claude-session-kit","last_synced_at":"2026-04-23T19:30:52.127Z","repository":{"id":351820609,"uuid":"1212629069","full_name":"penspanic/claude-session-kit","owner":"penspanic","description":"Back up, index, and analyze Claude Code session logs. Exposes an MCP server so AI agents can query the archive natively.","archived":false,"fork":false,"pushed_at":"2026-04-16T17:06:35.000Z","size":184,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-16T17:30:56.366Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/penspanic/claude-session-kit","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/penspanic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T15:11:32.000Z","updated_at":"2026-04-16T16:31:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/penspanic/claude-session-kit","commit_stats":null,"previous_names":["penspanic/claude-session-kit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/penspanic/claude-session-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penspanic%2Fclaude-session-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penspanic%2Fclaude-session-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penspanic%2Fclaude-session-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penspanic%2Fclaude-session-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/penspanic","download_url":"https://codeload.github.com/penspanic/claude-session-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penspanic%2Fclaude-session-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32195606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-23T15:28:30.493Z","status":"ssl_error","status_checked_at":"2026-04-23T15:28:29.972Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-23T19:30:49.728Z","updated_at":"2026-04-23T19:30:52.103Z","avatar_url":"https://github.com/penspanic.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-session-kit\n\n\u003e 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.\n\n[![npm](https://img.shields.io/npm/v/claude-session-kit.svg)](https://www.npmjs.com/package/claude-session-kit)\n[![CI](https://github.com/penspanic/claude-session-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/penspanic/claude-session-kit/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\n```mermaid\nflowchart LR\n  jsonl[\"~/.claude/projects/\u003cbr/\u003e*.jsonl\u003cbr/\u003e\u003ci\u003edeleted after 30d\u003c/i\u003e\"]\n\n  subgraph csk[\"claude-session-kit\"]\n    direction TB\n    backup[\"csk backup\"] --\u003e store[(\"SQLite index\u003cbr/\u003e+ blob mirror\u003cbr/\u003e+ FTS5 search\")]\n    store --\u003e analyze[\"csk analyze\u003cbr/\u003eper-session LLM summary\u003cbr/\u003e\u003ci\u003eintent · friction · corrections\u003c/i\u003e\"]\n    analyze --\u003e patterns[\"csk patterns\u003cbr/\u003eproject / global\u003cbr/\u003e\u003ci\u003ecross-session findings\u003c/i\u003e\"]\n  end\n\n  jsonl --\u003e backup\n\n  findings[\"Findings\u003cbr/\u003e• repetition / skill_gap\u003cbr/\u003e• correction_pattern\u003cbr/\u003e• codebase_smell / api_friction\u003cbr/\u003e• documentation_gap / test_coverage_gap\u003cbr/\u003e\u003cbr/\u003e\u003cb\u003e→ CLAUDE.md · new skill · refactor · docs · tests\u003c/b\u003e\"]\n  patterns --\u003e findings\n\n  surfaces[\"CLI\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;Web dashboard (csk serve)\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;MCP server (agents)\"]\n  store --- surfaces\n  findings --- surfaces\n```\n\n## Why\n\nYour 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:\n\n1. **They disappear.** Claude Code deletes sessions after 30 days by default (`cleanupPeriodDays`).\n2. **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.\n3. **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.\n\n`claude-session-kit` closes the loop:\n\n- **Backup** — nightly mirror of every JSONL, subagent log, tool result, and meta file before the cleanup timer fires.\n- **Analyze** (`csk analyze`) — per-session LLM summary extracting intent, what was tried, outcome, friction events, and verbatim user corrections.\n- **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.\n- **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.\n- **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.\n\n## Features\n\n- **Zero data loss** — mirrors non-JSONL files too (tool results, screenshots, meta). Anything that would disappear with the session gets preserved.\n- **Incremental backups** — size + mtime check, with 2-second tolerance for remote filesystems.\n- **Multi-host / multi-user** — every record carries `host_id` and `user_id`, so a team can point multiple machines at one remote store.\n- **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.\n- **Rclone-powered cloud** — one backend gives you Google Drive, OneDrive, Dropbox, S3, B2, and 60+ other providers.\n- **MCP-first** — the CLI, the web dashboard, and the MCP server share a single core, so every capability is available to humans and agents.\n- **Free-form output language** — `--lang \u003clabel\u003e` 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.\n- **Project allow/blocklists** — exclude personal or client work from shared stores.\n\n## Install\n\n```bash\nnpm install -g claude-session-kit\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/penspanic/claude-session-kit.git\ncd claude-session-kit\nnpm install\nnpm run build\nnpm link\n```\n\n## Quick start\n\n```bash\n# One-shot local backup\ncsk backup\n\n# Check what was archived\ncsk status\n\n# Daily backup via cron (3:30 AM by default; HOUR / MINUTE to override)\n./scripts/install-cron.sh\n```\n\nData lives at `~/.claude-session-kit/` by default:\n\n```\n~/.claude-session-kit/\n├── config.json      # host/user id, backend choice, project allow/block\n├── index.db         # SQLite index\n└── mirror/          # per-project jsonl + subagents + tool-results\n```\n\n## Cloud storage (rclone)\n\n`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.\n\n**1. Install rclone and configure a remote**\n\n```bash\nbrew install rclone          # macOS\nrclone config                # interactive setup for your provider\n# ...creates a remote named e.g. \"gdrive\"\n```\n\n**2. Point CSK at the remote**\n\nEdit `~/.claude-session-kit/config.json`:\n\n```json\n{\n  \"blobType\": \"rclone\",\n  \"blobRclone\": { \"remote\": \"gdrive:claude-sessions\" }\n}\n```\n\nOr use environment variables:\n\n```bash\nexport CSK_BLOB_TYPE=rclone\nexport CSK_RCLONE_REMOTE=gdrive:claude-sessions\ncsk doctor    # verify the remote is reachable\ncsk backup\n```\n\n## MCP integration\n\nAdd to your Claude Code `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"csk\": {\n      \"command\": \"csk-mcp\"\n    }\n  }\n}\n```\n\nCurrent tools:\n\n| Tool | Description |\n| --- | --- |\n| `csk_backup_status` | Most recent backup run, host/user, and session totals. |\n| `csk_list_sessions` | List sessions with parsed metadata. Filter by project, host, kind, date range, pagination. |\n| `csk_get_session` | Fetch a single session by `source_key`, with parsed details. |\n| `csk_recent` | Per-project session counts over the last N days. |\n| `csk_search` | Full-text search (FTS5) over user-message content. Returns highlighted snippets with session context. |\n| `csk_summarize` | Return a session's LLM summary. Generates on demand (if `ANTHROPIC_API_KEY` is set) or returns cache. |\n| `csk_recap` | List summaries over a date range, grouped by project. \"What did I do this week?\" in one tool call. |\n| `csk_patterns` | Cross-session findings from the latest (or specified) `csk patterns` run. Filter by scope (`project`/`global`), project_dir, kind. |\n\n## Configuration reference\n\n| Env var | Config key | Default |\n| --- | --- | --- |\n| `CSK_DATA_DIR` | — | `~/.claude-session-kit` |\n| `CSK_SOURCE_DIR` | — | `~/.claude/projects` |\n| `CSK_STORE_TYPE` | `storeType` | `sqlite` |\n| `CSK_BLOB_TYPE` | `blobType` | `fs` |\n| `CSK_RCLONE_REMOTE` | `blobRclone.remote` | — |\n| `CSK_RCLONE_BIN` | `blobRclone.rcloneBin` | `rclone` (on `PATH`) |\n| `CSK_RCLONE_CONFIG` | `blobRclone.configPath` | rclone default |\n\nProject filters in `config.json`:\n\n```json\n{\n  \"projects\": {\n    \"allow\": [\"-Users-me-OpenSource\"],   // empty means \"all\"\n    \"block\": [\"-Users-me-ClientXYZ\"]\n  }\n}\n```\n\n## Commands\n\n```\ncsk backup                        Mirror the source directory into the blob store\ncsk status [--json]               Summarize the last backup and the index\ncsk status --host \u003cid\u003e            Filter status by host_id\ncsk analyze [opts]                LLM-summarize parsed sessions (needs ANTHROPIC_API_KEY)\ncsk patterns project --dir \u003cX\u003e    Find patterns in one project (repeatable --dir)\ncsk patterns global               Find cross-project habits (evidence must span ≥2 projects)\ncsk serve [--port 4567]           Launch the read-only web dashboard\ncsk doctor                        Verify source, store, and blob backend\n```\n\n### `csk analyze`\n\nGenerates 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.\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\ncsk analyze --limit 10                               # first 10 unanalyzed sessions\ncsk analyze --project -Users-me-Repo --since 2026-04-01\ncsk analyze --dry-run --limit 50                     # preview candidates without calling the API\ncsk analyze --model claude-haiku-4-5-20251001        # override model\ncsk analyze --lang ko                                # respond in Korean (identifiers stay English)\n```\n\nBy default uses Haiku. For 1000 sessions expect ~$3-6 in token costs; the CLI prints per-session usage.\n\n### `csk patterns`\n\nFeeds 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:\n\n```bash\n# Project mode — one logical project (possibly many worktrees)\ncsk patterns project --dir -Users-me-Repo\ncsk patterns project --dir -Users-me-Repo --dir -Users-me-Repo-worktree-1\ncsk patterns project --match Repo      # substring-match all project_dirs\n\n# Global mode — habits that show up across projects (≥2 distinct project_dirs required)\ncsk patterns global --limit 200\ncsk patterns global --lang 한국어\n```\n\nFindings 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.\n\n### `csk serve`\n\nLocalhost 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).\n\n```bash\ncsk serve                   # http://127.0.0.1:4567\ncsk serve --port 8080 --host 127.0.0.1\n```\n\nPages: 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).\n\n## Architecture at a glance\n\n```\n┌──────────┐     ┌───────────┐     ┌─────────────────────┐\n│  csk CLI │     │  csk-mcp  │     │  (future dashboards)│\n└────┬─────┘     └─────┬─────┘     └──────────┬──────────┘\n     │                 │                      │\n     └────────────┬────┴──────────┬───────────┘\n                  │               │\n              ┌───▼───┐       ┌───▼──────┐\n              │ core  │──────▶│ BlobStore│  fs  | rclone\n              │       │       └──────────┘  (→ GDrive / OneDrive / S3 / ...)\n              │       │       ┌────────────┐\n              │       │──────▶│SessionStore│  sqlite\n              └───────┘       └────────────┘  (→ postgres planned)\n```\n\n## Roadmap\n\n- **v0.1** — backup, index, MCP backup_status. ✅\n- **v0.2** — session parsing, FTS5 search, LLM summaries, interactive analyze, web dashboard, cross-session patterns detection. **(current)** ✅\n- **v0.3** — native S3 blob store (no rclone), rclone setup docs for GDrive/OneDrive.\n- **v0.4** — PostgresSessionStore for multi-host team aggregation; deeper code-aware pattern detection (feed cited source files to the LLM).\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md). PRs, backend implementations, and design feedback all welcome.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpenspanic%2Fclaude-session-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpenspanic%2Fclaude-session-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpenspanic%2Fclaude-session-kit/lists"}