# 🗂️ claude-sesh ### Your Claude Code sessions, organized.
**Claude Code buries your sessions in `~/.claude/projects/`.** **Good luck finding that conversation from last week.**
[![npm version](https://img.shields.io/npm/v/claude-sesh.svg?style=for-the-badge&color=D4A574)](https://www.npmjs.com/package/claude-sesh) [![npm downloads](https://img.shields.io/npm/dm/claude-sesh.svg?style=for-the-badge&color=8B7355)](https://www.npmjs.com/package/claude-sesh) [![License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](LICENSE) [![MCP](https://img.shields.io/badge/MCP-enabled-D4A574.svg?style=for-the-badge)](https://modelcontextprotocol.io)
```bash npx claude-sesh web ``` **One command. Zero config. Your entire Claude Code history.**
[Features](#features) · [Quick Start](#quick-start) · [Dashboard](#-web-dashboard) · [CLI](#-cli-commands) · [MCP](#-mcp-integration)
claude-sesh dashboard

---
## Features

### 🔍 Session Explorer Find any conversation instantly. Browse your complete Claude Code history with powerful filtering by project, date, model, and more. Never lose track of that perfect solution again.	### 🔎 Full-Text Search Search across everything. Find sessions by code snippets, error messages, or any text. Search spans all your conversations, tool calls, and outputs.
### 📊 Usage Analytics Know where your tokens go. Track costs, token usage, and coding time across all sessions. See breakdowns by project, model, and time period.	### 🔄 Easy Resume Pick up where you left off. Get rich context summaries to continue any session. Copy resume prompts or use Claude's native resume feature.
### 🏷️ AI Enrichment Auto-generated insights. Let AI summarize sessions, extract key decisions, and add searchable tags. Powered by your Anthropic API key.	### 🧠 MCP Integration Give Claude memory. Let Claude search your past sessions directly. Ask "How did I solve this before?" and get real answers.

---
## Quick Start

### ⚡ Try instantly ```bash npx claude-sesh web ``` Opens `http://localhost:3847` with your full Claude Code history. **No install. No config. No API keys.**

### 📦 Install globally ```bash npm install -g claude-sesh ``` Then use the CLI anywhere: ```bash sesh list # List sessions sesh search "bug" # Search conversations sesh stats # View analytics sesh web # Launch dashboard ```

---
## 🖥️ Web Dashboard ```bash sesh web ```

📈 Stats at a Glance _{Total tokens, cost, hours coded}	📅 Activity Heatmap _{GitHub-style contribution graph}	⏱️ Session Timeline _{Visual history of all your work}
🏆 Leaderboards _{Top projects, tools, models}	🔍 Deep Search _{Find by content, project, date}	📋 Session Details _{Full context for any session}

---
## 💻 CLI Commands

Browse Sessions ```bash sesh list # Recent sessions sesh ls -n 50 # Last 50 sessions sesh show # Session details sesh projects # List all projects ```	Search & Find ```bash sesh search "auth" # Full-text search sesh continue # Find resumable sessions sesh stats # Overall statistics ```
Resume Work ```bash sesh resume # Get resume context sesh resume --copy # Copy to clipboard sesh resume --native # Use Claude's resume ```	AI Features ```bash sesh enrich # Generate AI summaries sesh enrich --limit 20 # Enrich 20 sessions sesh enrich --stats # Check progress ```

---
## 🧠 MCP Integration **Give Claude access to your session history.** ```bash claude mcp add claude-sesh --scope user -- npx claude-sesh mcp ``` Restart Claude Code. Now ask things like: > *"What was I working on in this project?"* > *"How did I solve the caching issue before?"* > *"What files have changed recently?"*

Available MCP Tools

| Tool | Description | |------|-------------| | `search_sessions` | Full-text search across all sessions | | `get_session` | Get detailed info about a specific session | | `get_project_context` | Recent sessions, decisions, todos for a project | | `get_pending_todos` | Find incomplete tasks across sessions | | `search_decisions` | Find past architectural decisions | | `search_knowledge` | Search learnings and solutions | | `get_file_history` | Track changes to specific files | | `get_recent_activity` | Summary of recent coding activity |

---
## 🏷️ AI Enrichment **Auto-generate summaries and tags for better search.** ```bash export ANTHROPIC_API_KEY=your-key sesh enrich ```

📝 Summary
_{What was accomplished}

🎯 Decisions
_{Key choices made}

🐛 Problems
_{Issues & solutions}

🏷️ Tags
_{Auto-categorization}

---
## How It Works ``` ┌────────────────────────────────────────────────────────────────┐ │ Claude Code writes sessions to ~/.claude/projects/ │ │ ↓ │ │ claude-sesh parses & aggregates session data │ │ • Token counts, costs, duration │ │ • Tool usage breakdown │ │ • File changes tracked │ │ ↓ │ │ AI Enrichment (optional) │ │ • Auto-generate summaries │ │ • Extract key decisions │ │ • Add searchable tags │ │ ↓ │ │ Web Dashboard & CLI │ │ • Search all sessions │ │ • View analytics & trends │ │ • Resume past work │ └────────────────────────────────────────────────────────────────┘ ``` **Your data stays local.** claude-sesh reads Claude's existing session files. Nothing is uploaded anywhere.
---
## 🔒 Privacy & Security

💾
100% Local
_{All data stays on your machine}

👀
Read-Only
_{Never modifies Claude's files}

📡
No Telemetry
_{Zero data collection}

---
## Configuration

Change Dashboard Port

```bash sesh web --port 8080 ```

Data Locations

Claude Code sessions: ``` ~/.claude/projects/[project-path]/[session-id].jsonl ``` Enriched data (optional): ``` ~/.claude-sesh/enriched/[session-id].json ```

Troubleshooting

**Dashboard not loading?** ```bash lsof -i :3847 # Check if port in use sesh web --port 8080 # Try different port ``` **Search returning nothing?** - Try broader search terms - Run `sesh enrich` to improve searchability **MCP not working?** - Restart Claude Code after adding MCP server - Verify with `claude mcp list`

---
## Contributing We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and our roadmap.
---

**Built for the Claude Code community** ❤️ [Report Bug](https://github.com/abracadabra50/claude-sesh/issues) · [Request Feature](https://github.com/abracadabra50/claude-sesh/issues) · [Discussions](https://github.com/abracadabra50/claude-sesh/discussions)
MIT License · [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · [Model Context Protocol](https://modelcontextprotocol.io)

### 🔍 Session Explorer Find any conversation instantly. Browse your complete Claude Code history with powerful filtering by project, date, model, and more. Never lose track of that perfect solution again.	### 🔎 Full-Text Search Search across everything. Find sessions by code snippets, error messages, or any text. Search spans all your conversations, tool calls, and outputs.
### 📊 Usage Analytics Know where your tokens go. Track costs, token usage, and coding time across all sessions. See breakdowns by project, model, and time period.	### 🔄 Easy Resume Pick up where you left off. Get rich context summaries to continue any session. Copy resume prompts or use Claude's native resume feature.
### 🏷️ AI Enrichment Auto-generated insights. Let AI summarize sessions, extract key decisions, and add searchable tags. Powered by your Anthropic API key.	### 🧠 MCP Integration Give Claude memory. Let Claude search your past sessions directly. Ask "How did I solve this before?" and get real answers.

Browse Sessions ```bash sesh list # Recent sessions sesh ls -n 50 # Last 50 sessions sesh show # Session details sesh projects # List all projects ```	Search & Find ```bash sesh search "auth" # Full-text search sesh continue # Find resumable sessions sesh stats # Overall statistics ```
Resume Work ```bash sesh resume # Get resume context sesh resume --copy # Copy to clipboard sesh resume --native # Use Claude's resume ```	AI Features ```bash sesh enrich # Generate AI summaries sesh enrich --limit 20 # Enrich 20 sessions sesh enrich --stats # Check progress ```

📈

📅

⏱️

🏆

🔍

📋