GitHub - neilberkman/shannon

7 min read Original article ↗

Shannon

Fast local search for your Claude conversation history.

Claude's web/desktop search is pretty lacking - no boolean operators, no date filtering, no advanced search syntax. Shannon is a local search tool that works with your exported Claude.ai conversations (not API - this is for your regular Claude.ai chats). It supports AND/OR/NOT operators, wildcard search, date ranges, sender filtering, and more.

The TUI mode is particularly useful - you can navigate between conversations, jump back to Claude.ai, and copy/save artifacts directly. The whole process of generating exports and importing them incrementally is designed to be as painless as possible, with auto-discovery of export files and incremental updates.

Note: This is an unofficial tool not affiliated with Anthropic.

Features

  • 🔍 Full-text search with SQLite FTS5 and dual tokenizers (porter + unicode61)
  • 📝 Rich markdown rendering with syntax highlighting and formatting
  • 🌳 Conversation branching support (when available in exports)
  • 💻 Cross-platform - Works on macOS, Linux, and Windows (6 architectures)
  • 🚀 Fast - Single Go binary with embedded database
  • 🎨 Multiple interfaces - CLI for scripting, TUI for interactive use
  • 🔄 Auto-discovery - Automatically finds Claude export files
  • 📤 Export formats - JSON, CSV, and Markdown output
  • 🔗 Pipeline-friendly - Designed for Unix pipeline integration
  • 📊 Statistics - Detailed database and conversation analytics
  • 🖥️ Modern terminal support - Enhanced features in Ghostty, Kitty, and WezTerm

Installation

Package Managers

Homebrew (macOS/Linux)

brew install neilberkman/shannon/shannon

Scoop (Windows)

scoop bucket add shannon https://github.com/neilberkman/scoop-shannon
scoop install shannon

Install Script (macOS/Linux)

curl -sSL https://raw.githubusercontent.com/neilberkman/shannon/main/install.sh | bash

Pre-built Binaries

Download the latest release for your platform from the releases page.

  • macOS: shannon_x.x.x_darwin_amd64.tar.gz (Intel) or shannon_x.x.x_darwin_arm64.tar.gz (Apple Silicon)
  • Linux: shannon_x.x.x_linux_amd64.tar.gz or shannon_x.x.x_linux_arm64.tar.gz
  • Windows: shannon_x.x.x_windows_amd64.zip or shannon_x.x.x_windows_arm64.zip

From Source

go install github.com/neilberkman/shannon@latest

Quick Start

# 1. Export your data from https://claude.ai/settings/data-privacy-controls
# 2. Find and import your conversations
shannon discover
shannon import ~/Downloads/claude-export*/conversations.json

# 3. Start searching!
shannon search "your search term"
shannon tui  # Interactive browser

Getting Started

1. Export Your Claude Conversations

First, you need to export your conversation data from Claude:

  1. Go to Claude Data Privacy Controls{:target="_blank"}
  2. In the Data controls section, click Export data
  3. Claude will send you an email with a download link
  4. Download and extract the ZIP file

2. Import Your Conversations

Once you have your export file:

# Auto-discover export files in common locations
shannon discover

# Import the conversations (usually named conversations.json)
shannon import path/to/conversations.json

Usage

Search

Basic search:

shannon search "machine learning"

Advanced search with filters:

# Boolean operators (case-insensitive)
shannon search "python AND django"
shannon search "react or vue or angular"
shannon search "error NOT timeout"

# Exact phrase search
shannon search '"machine learning model"'

# Wildcard search (prefix only)
shannon search "async*"

# Filter by sender
shannon search "python code" --sender human

# Filter by date range (using short aliases)
shannon search "bug" --after 2024-01-01 --before 2024-12-31

# Search within specific conversation
shannon search "function" --conversation 123

# Show context around search results
shannon search "error" --context --context-lines 3

# Export search results
shannon search "python" --format json --quiet

List Conversations

# List all conversations
shannon list

# List with filtering and sorting
shannon list --search "python" --limit 20 --sort messages

# Output just IDs for piping
shannon list --format json --quiet | jq -r '.conversations[].id'

Recent Conversations

# Show conversations from last 7 days
shannon recent

# Show conversations from last 30 days
shannon recent --days 30

# Get just IDs for piping
shannon recent --format id | xargs -I {} shannon export {}

Export Conversations

# Export single conversation to stdout
shannon export 123

# Export as JSON or CSV
shannon export 123 --format json
shannon export 123 --format csv --output export.csv

# Export multiple conversations
shannon export 123 456 789

# Pipe to other tools
shannon export 123 | less
shannon export 123 --format json | jq '.messages[] | select(.sender == "human")'

Edit Conversations

# Open conversation in default editor
shannon edit 123

# Open with specific editor
shannon edit 123 --editor vim

# Open as JSON
shannon edit 123 --format json

View Conversation

# View full conversation
shannon view 123

# View with branch information
shannon view 123 --branches

Statistics

# Show database statistics
shannon stats

Terminal Features

# Check what terminal features are supported
shannon terminal

Shannon provides enhanced features in modern terminals:

Ghostty, Kitty, WezTerm

  • Clickable conversation IDs - Click to view conversations directly
  • Clickable URLs - Auto-detected links become clickable
  • Rich hyperlinks - Email addresses, GitHub repos, and file paths

All Terminals

  • Progressive enhancement - Features gracefully degrade in basic terminals
  • Rich markdown rendering - Syntax highlighting and formatting
  • Adaptive themes - Automatically matches terminal light/dark mode

Interactive TUI Mode

# Launch TUI with search
shannon tui "machine learning"

# Launch TUI in browse mode
shannon tui

TUI Keyboard Shortcuts:

  • Browse Mode:

    • ↑/↓: Navigate conversations
    • Enter: View conversation
    • /: Search
    • q: Quit application

  • Search Results:

    • ↑/↓: Navigate conversations
    • Enter: View full conversation
    • Esc: Back to browse mode
    • q: Quit application

  • Conversation View:

    • ↑/↓: Scroll messages
    • g/G: Go to top/bottom
    • /: Find text within conversation
    • a: Enter artifact focus mode (if artifacts present)
    • o: Open conversation in claude.ai
    • Esc: Back to search results (or clear find if active)
    • q: Quit application

  • Find Mode (within conversation):

    • n/N: Next/previous match
    • Esc: Clear find and return to conversation
    • q: Quit application

  • Artifact Mode (within conversation):

    • n/N: Navigate between artifacts
    • Tab: Expand/collapse artifact (toggle between preview and full view)
    • s: Save current artifact to file
    • c: Copy current artifact to clipboard
    • Esc: Exit artifact mode
    • q: Quit application

TUI Features:

  • 🔍 In-conversation search - Find and highlight text within conversations
  • 🔙 Browser-like navigation - ESC acts as back button, q quits completely
  • 💬 Conversation-centric results - Search shows conversations, not individual messages
  • 📍 Smart positioning - Conversations start at the first message when opened
  • ⌨️ Consistent shortcuts - Standard vim-like navigation (g/G for top/bottom)
  • 📄 Artifact focus mode - Navigate, view, save, and copy Claude artifacts with dedicated controls

Search Syntax

  • Phrase search: "exact phrase"
  • Wildcard: test*
  • Boolean: machine AND learning
  • Exclusion: python -javascript

Unix Pipeline Integration

Shannon is designed to work well with Unix pipelines:

# Export search results as JSON and process with jq
shannon search "error" --format json | jq '.results[] | .conversation_name'

# Export as CSV for analysis
shannon search "python" --format csv | cut -d, -f1,4 | sort | uniq

# List conversations as JSON and filter
shannon list --format json | jq '.conversations[] | select(.message_count > 100)'

# Quiet mode for cleaner output
shannon search "bug" --quiet

# Export conversation and process
shannon export 123 | grep "TODO"

# Pipeline from search to export
shannon search "python" --format json --quiet | \
  jq -r '.results[].conversation_id' | \
  sort -u | \
  head -5 | \
  xargs -I {} shannon export {}

# Recent conversations pipeline
shannon recent --format id | \
  while read id; do
    echo "=== Conversation $id ==="
    shannon export $id | head -20
  done

Configuration

Configuration file is stored in platform-specific locations:

  • Linux: ~/.config/shannon/config.yaml
  • macOS: ~/Library/Application Support/shannon/config.yaml
  • Windows: %APPDATA%\shannon\config.yaml

Database is stored in:

  • Linux: ~/.local/share/shannon/claude-search.db
  • macOS: ~/Library/Application Support/shannon/claude-search.db
  • Windows: %LOCALAPPDATA%\shannon\claude-search.db

Limitations

  • Screenshots: Screenshot attachments in conversations are not included in exports or searches. Only text content is indexed and exported.
  • File Attachments: Other file attachments (PDFs, documents, etc.) are not currently supported.
  • Conversation Branches: While branch information is preserved, navigation between branches is not yet implemented in the TUI.

Terminal Compatibility

Shannon works in any terminal but provides enhanced features in modern emulators:

Terminal Hyperlinks Graphics Advanced Input
Ghostty ✅ ✅* ✅
Kitty ✅ ✅* ✅
WezTerm ✅ ✅* ✅
iTerm2 ✅ ✅* ❌
VS Code ✅ ❌ ❌
Standard terminals ❌ ❌ ❌

*Graphics support planned for future versions

Run shannon terminal to see what features are available in your current terminal.

Development

Requirements

  • Go 1.21+
  • SQLite3 (embedded, no external dependency needed)
  • golangci-lint (for development)

Building

Testing

Linting

go fmt ./...
go vet ./...
golangci-lint run ./...

Contributing

Contributions are welcome! Please check our ROADMAP.md for planned features and ideas.

License

MIT