{"id":49283566,"url":"https://github.com/buildingopen/session-recall","last_synced_at":"2026-04-25T20:03:24.467Z","repository":{"id":345725353,"uuid":"1187092663","full_name":"buildingopen/session-recall","owner":"buildingopen","description":"Search and analyze Claude Code session transcripts to recover context after compaction","archived":false,"fork":false,"pushed_at":"2026-04-09T22:59:23.000Z","size":209,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T00:32:33.755Z","etag":null,"topics":["ai-tools","claude","claude-code","cli","context-recovery","developer-tools","session-analysis"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/session-recall","language":"Python","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/buildingopen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-03-20T10:32:14.000Z","updated_at":"2026-04-09T22:59:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/buildingopen/session-recall","commit_stats":null,"previous_names":["buildingopen/session-recall"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/buildingopen/session-recall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildingopen%2Fsession-recall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildingopen%2Fsession-recall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildingopen%2Fsession-recall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildingopen%2Fsession-recall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buildingopen","download_url":"https://codeload.github.com/buildingopen/session-recall/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buildingopen%2Fsession-recall/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32274987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"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":["ai-tools","claude","claude-code","cli","context-recovery","developer-tools","session-analysis"],"created_at":"2026-04-25T20:03:23.720Z","updated_at":"2026-04-25T20:03:24.454Z","avatar_url":"https://github.com/buildingopen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# session-recall\n\n[![npm version](https://img.shields.io/npm/v/session-recall)](https://www.npmjs.com/package/session-recall)\n[![license](https://img.shields.io/npm/l/session-recall)](https://github.com/buildingopen/session-recall/blob/main/LICENSE)\n[![npm downloads](https://img.shields.io/npm/dm/session-recall)](https://www.npmjs.com/package/session-recall)\n\nTotal recall for Claude Code. Get back everything compaction took.\n\n```bash\nnpx session-recall \"the thing you lost\"\n```\n\n## The problem\n\nWhen Claude Code compacts context, you get a vague summary. Details vanish: decisions, error solutions, specific commands that worked, corrections you gave.\n\nBut the raw transcripts are never deleted. Every session is saved as JSONL in `~/.claude/projects/`, permanently. Compaction only affects the live context window. The data is always there, just buried in JSON soup.\n\nsession-recall parses those JSONL transcripts properly. It extracts human-readable messages, tool calls, errors, and patterns, so you find what you need in seconds.\n\n## Search any past session\n\nFind exactly what was lost after compaction:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo-search.svg\" alt=\"session-recall search demo\" width=\"780\"\u003e\n\u003c/p\u003e\n\n## Analyze your sessions\n\n`--report` finds retry loops, errors, user corrections, inflated self-scores, and generates CLAUDE.md rules to prevent the same mistakes:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo-report.svg\" alt=\"session-recall report demo\" width=\"780\"\u003e\n\u003c/p\u003e\n\n## Cross-session patterns\n\n`--all` analyzes your last N sessions to find recurring problems:\n\n```\n$ session-recall --all 10\n\nCROSS-SESSION SUMMARY (10 sessions)\n  Total tool calls: 4351 | Total errors: 165\n\nRECURRING RETRY PATTERNS\n  Bash: retried in 7/10 sessions (avg 4.2x when it happens)\n\nSELF-SCORING ACCURACY\n  185 scores across 10 sessions (avg 7.7/10)\n  20/185 (11%) had user issues after\n\nRECURRING ERROR TYPES\n  COMMAND_FAILED: in 8/10 sessions\n  FILE_NOT_FOUND: in 6/10 sessions\n```\n\n## Deep analysis via Gemini\n\n`--deep` sends structured session data to Gemini for project-specific insights instead of generic advice:\n\n```\n$ session-recall --report --deep\n\nDEEP ANALYSIS (via Gemini)\n\n1. PROJECT CONTEXT: Building a video generation pipeline with Remotion.\n\n2. CLAUDE.MD RULES:\n   - When ElevenLabs returns 429, wait 30s before retry. Agent wasted 20 calls.\n   - Always check ffmpeg output file exists before proceeding to next step.\n   - User wants narration synced with visual transitions, not just content.\n\n3. BIGGEST TIME WASTER: 47 minutes retrying a Bash command blocked by a\n   pre-commit hook. Switch approach after first hook rejection.\n```\n\n## All commands\n\n```bash\n# Search\nsession-recall \"keyword\"              # Find keyword in current session\nsession-recall \"error\" \"deploy\"       # AND search (both must match)\nsession-recall --recent 10            # Last 10 messages (no tool noise)\nsession-recall --decisions            # Find decision points\nsession-recall --tools \"Edit\"         # Search tool calls only\nsession-recall --list                 # List all sessions\n\n# Pin a session (auto-namespaced per Claude process)\nsession-recall --pin-by \"project-x\"   # Pin session containing keyword\nsession-recall --unpin                # Remove pin\n\n# Analyze\nsession-recall --report               # Errors, retries, corrections, rules\nsession-recall --report --deep        # + Gemini project-specific insights\nsession-recall --all                  # Cross-session patterns (last 10)\nsession-recall --all 20 --deep        # Cross-session + Gemini\nsession-recall --check-compaction     # Exit 0 if session was compacted, 1 otherwise\n\n# Apply rules (interactive review, then append to CLAUDE.md / MEMORY.md)\nsession-recall --apply                # Template-based rules\nsession-recall --apply --deep         # + Gemini project-specific rules\n```\n\n## Apply rules to CLAUDE.md\n\n`--apply` generates rules, shows each one for review, and appends approved rules to your project's CLAUDE.md:\n\n```\n$ session-recall --apply --deep\n\nRunning Gemini deep analysis...\nProject: Building session-recall CLI tool for Claude Code transcript recovery.\n\n==================================================\nREVIEW CLAUDE.MD RULES (5 items)\n==================================================\n  [y] approve  [n] skip  [e] edit  [a] approve all  [q] quit\n\n  (1/5) After 2 failures with Bash, switch approach. Do not retry a third time.\n  \u003e y\n\n  (2/5) When Gemini returns malformed JSON, strip markdown fences before parsing.\n  \u003e e\n  new text\u003e Strip ```json fences from Gemini responses before JSON.parse().\n  ...\n\nAppended 4 rules to /root/my-project/CLAUDE.md\nAppended 2 entries to ~/.claude/projects/-root-my-project/memory/MEMORY.md\n```\n\n## MCP server\n\nGive Claude Code direct access to past session context. Add to `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"session-recall\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"session-recall\", \"--mcp\"]\n    }\n  }\n}\n```\n\nClaude Code gets 6 tools:\n\n| Tool | What it does |\n|------|-------------|\n| `recall_search` | Search past sessions by keyword |\n| `recall_recent` | Get last N messages (no tool noise) |\n| `recall_report` | Analyze session patterns and suggest rules |\n| `recall_apply` | Append approved rule to CLAUDE.md or MEMORY.md |\n| `recall_decisions` | Find decision points |\n| `recall_list` | List available sessions |\n\nAfter compaction, Claude can call `recall_search` to recover lost context, then `recall_report` to suggest rules, and `recall_apply` (with your approval) to persist the lessons.\n\n## Auto-trigger after compaction\n\nAdd a PreToolUse hook to `~/.claude/settings.json` so Claude gets notified after context compaction. The hook checks once per session and reminds Claude that MCP recovery tools are available.\n\n**1. Create the hook script** at `~/.claude/hooks/post-compaction-recall.sh`:\n\n```bash\n#!/usr/bin/env bash\n# Must ALWAYS output {\"decision\": \"approve\"} on stdout.\ntrap 'echo \"{\\\"decision\\\": \\\"approve\\\"}\"' EXIT\n\n# Walk process tree to find Claude's PID (session-stable flag key)\nCLAUDE_PID=\"\" PID=$$\nfor _ in 1 2 3 4 5 6 7 8 9 10; do\n    PARENT=$(ps -o ppid= -p \"$PID\" 2\u003e/dev/null | tr -d ' ') || break\n    [ -z \"$PARENT\" ] || [ \"$PARENT\" = \"1\" ] || [ \"$PARENT\" = \"0\" ] \u0026\u0026 break\n    PID=\"$PARENT\"\n    PNAME=$(ps -o comm= -p \"$PID\" 2\u003e/dev/null | tr -d ' ') || continue\n    case \"$PNAME\" in claude|claude-code|node) CLAUDE_PID=\"$PID\"; break ;; esac\ndone\n\nFLAG=\"/tmp/session-recall-post-compact-${CLAUDE_PID:-$$}\"\n[ -f \"$FLAG\" ] \u0026\u0026 exit 0\ntouch \"$FLAG\" 2\u003e/dev/null || true\n\n# Try PATH, then common install paths, then npx\nRECALL=\"\"\nif command -v session-recall \u003e/dev/null 2\u003e\u00261; then\n    RECALL=\"session-recall\"\nelif [ -x /usr/local/bin/session-recall ]; then\n    RECALL=\"/usr/local/bin/session-recall\"\nelif command -v npx \u003e/dev/null 2\u003e\u00261; then\n    RECALL=\"npx -y session-recall\"\nfi\n\nif [ -n \"$RECALL\" ]; then\n    $RECALL --check-compaction 2\u003e/dev/null \u0026\u0026 \\\n        echo \"Context was compacted. MCP tools: recall_search, recall_report, recall_recent\" \u003e\u00262\nfi\nexit 0\n```\n\n```bash\nchmod +x ~/.claude/hooks/post-compaction-recall.sh\n```\n\n**2. Register the hook** in `~/.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash|Read|Edit|Write|Glob|Grep\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"~/.claude/hooks/post-compaction-recall.sh\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n`--check-compaction` exits 0 if the current session was compacted, 1 otherwise. The flag file in `/tmp` ensures the check runs only once per Claude process (cleaned on reboot).\n\n## Setup\n\n```bash\nnpx session-recall --help\n```\n\nFor deep analysis and MCP `--deep` mode, add a Gemini key:\n\n```bash\nmkdir -p ~/.config/session-recall\necho \"your-gemini-key\" \u003e ~/.config/session-recall/gemini-key\nchmod 600 ~/.config/session-recall/gemini-key\n```\n\nOr set `GEMINI_API_KEY` as an env var.\n\n## Part of Building Open\n\nOpen-source tools for Claude Code power users:\n\n- [**session-recall**](https://github.com/buildingopen/session-recall) - Recover context after compaction\n- [**claude-wrapped**](https://github.com/buildingopen/claude-wrapped) - Your Claude Code year in review\n- [**bouncer**](https://github.com/buildingopen/bouncer) - AI quality audit for any work\n- [**blast-radius**](https://github.com/buildingopen/blast-radius) - Impact analysis before code changes\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildingopen%2Fsession-recall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuildingopen%2Fsession-recall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuildingopen%2Fsession-recall/lists"}