https://github.com/testy-cool/cc-convo-explorer
TUI for browsing, searching, exporting, and analyzing Claude Code conversation history
https://github.com/testy-cool/cc-convo-explorer
Last synced: 1 day ago
JSON representation
TUI for browsing, searching, exporting, and analyzing Claude Code conversation history
- Host: GitHub
- URL: https://github.com/testy-cool/cc-convo-explorer
- Owner: testy-cool
- License: mit
- Created: 2026-04-07T08:24:10.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-02T22:16:08.000Z (28 days ago)
- Last Synced: 2026-05-03T00:30:14.799Z (28 days ago)
- Language: Python
- Size: 164 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# cc-convo-explorer
A terminal UI for browsing, searching, resuming, and analyzing your [Claude Code](https://docs.anthropic.com/en/docs/claude-code) conversation history.
Claude Code stores every session as `.jsonl` files in `~/.claude/projects/`. This tool gives you a searchable, interactive interface to explore them all — across every project you've ever worked on.
## Screenshot
```
cc-convo-explorer
┌─ PROJECTS (12) ────────────────┐┌─ PREVIEW (25 turns) ──────────────────────┐
│ Filter convos... (Enter=search) ││ │
│ ││ ## ticklish-twirling-hejlsberg │
│ ~/Work/my-project (12) ★ ││ Date: 2026-04-06T21:11:48 │
│ ~/Work/web-app (36) ││ CWD: ~/Work/my-project │
│ ~/Work/api-server (116) ★ ││ ────────────────────────────────────────── │
│ ~/Work/cli-tool (6) ││ ## User │
│ ✓ ~/Work/dashboard (24) ││ would like to make this more profesh... │
│ ✓ ~/Work/shared-lib (8) ││ │
│ 2026-04-05 fix-auth ... ││ ## Assistant │
│ 2026-04-03 refactor ... ││ Let me explore the codebase first... │
│ ││ │
├──────────────────────────────────┤│ │
│ 2 selected · ~850K tokens ││ │
│ / search · S select · A analyze ││ │
└──────────────────────────────────┘└────────────────────────────────────────────┘
```
## Features
- **Browse all projects** — auto-discovers every Claude Code project in `~/.claude/projects/`
- **Tree view** — expandable project nodes with conversation children, sorted by date
- **Search/filter** — type to filter instantly, press Enter for deep full-text search
- **Resume sessions** — press `R` to resume any conversation with `claude -r`
- **Preview** — select any conversation to see the full user/assistant exchange
- **Multi-select** — select individual conversations, entire projects, or everything
- **Token estimation** — see estimated token count for selected conversations
- **Export** — export individual conversations or combined multi-conversation markdown
- **Gemini analysis** (optional) — analyze conversations with Google Gemini to extract patterns, preferences, and insights
- **Model picker** — cycle between Gemini models
- **Editable prompts** — customize the analysis prompt before running
- **Analyzed indicators** — projects that have been analyzed show a ★ marker
- **Resizable sidebar** — drag the divider to resize
- **CLI mode** — list, search, export, resume, and analyze without the TUI
## Install
```bash
# Install globally (recommended)
uv tool install "cc-convo-explorer[ai] @ git+https://github.com/testy-cool/cc-convo-explorer.git"
# Or clone and install locally
git clone https://github.com/testy-cool/cc-convo-explorer.git
cd cc-convo-explorer
uv sync --extra ai
```
Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
## Usage
### TUI (interactive)
```bash
cc-convo-explorer
```
**Keyboard shortcuts:**
| Key | Action |
|-----|--------|
| `/` | Focus search/filter |
| `Enter` | Deep search (in filter) / Preview conversation (in tree) |
| `Esc` | Clear filter / Cancel analysis |
| `S` | Toggle select on current item |
| `Ctrl+A` | Select all |
| `Ctrl+D` | Deselect all |
| `R` | Resume conversation in Claude Code |
| `E` | Export selected as individual markdown files |
| `C` | Export selected as one combined markdown file |
| `A` | Analyze with Gemini |
| `M` | Cycle Gemini model |
| `P` | Edit analysis prompt |
| `O` | Open exports/analyses folder |
| `Tab` | Switch focus between sidebar and preview |
| `Q` | Quit |
### CLI (headless)
```bash
# List all projects and conversations
cc-convo-explorer --list
# Search across all conversations
cc-convo-explorer --search "auth middleware"
# Resume a conversation by slug or UUID
cc-convo-explorer --resume reflective-herding-biscuit
# Export by file path, UUID prefix, or slug
cc-convo-explorer --concat path/to/session.jsonl
cc-convo-explorer --concat 315ce500
cc-convo-explorer --concat reflective-herding-biscuit
# Analyze with Gemini
export GEMINI_API_KEY=your-key-here
cc-convo-explorer --analyze 315ce5 reflective-herding --model gemini-3.1-pro-preview
# Custom analysis prompt (inline or from file)
cc-convo-explorer --analyze 315ce5 --prompt "List all tools used.\n\n{content}"
cc-convo-explorer --analyze 315ce5 --prompt my-prompt.txt
# Detail levels: text (default), tools, results, full
cc-convo-explorer --concat 315ce5 --detail tools # +tool call summaries
cc-convo-explorer --concat 315ce5 --detail results # +truncated tool output
cc-convo-explorer --concat 315ce5 --detail full # +everything untruncated
```
#### Detail levels
| Level | What's included | Typical overhead |
|-------|----------------|-----------------|
| `text` | User/assistant text only | baseline |
| `tools` | + tool call summaries (Bash commands, file edits, greps) | +20-30% |
| `results` | + truncated tool output (500 chars each) | +80-100% |
| `full` | + full untruncated tool output | +300-2000% |
Exports include a stats header: model, token count, duration, tool calls, and estimated cost.
## Gemini Analysis
Set your API key:
```bash
# Environment variable
export GEMINI_API_KEY=your-key-here
# Or .env file in project directory
echo GEMINI_API_KEY=your-key-here > .env
```
Get a free key at [aistudio.google.com](https://aistudio.google.com/apikey).
Analysis extracts:
- Key decisions and their rationale
- User preferences and workflow patterns
- Problems encountered and solutions
- Recurring patterns across sessions
- Unfinished work and TODOs
Results saved to `~/.claude/convo-explorer/analyses/`.
For multi-conversation analysis, select multiple items and press `A` — Gemini finds cross-session patterns and preference evolution.
## File locations
| What | Where |
|------|-------|
| Conversation logs | `~/.claude/projects/{project}/*.jsonl` |
| Analyses | `~/.claude/convo-explorer/analyses/` |
| Combined exports | `~/.claude/convo-explorer/exports/` |
## License
MIT