Quaid

Capture, index, and search your Claude Code conversation history.

Quaid watches Claude Code's session files in real time, stores everything in a local SQLite database with full-text search, tracks token costs, and gives you multiple ways to browse and query your history — CLI, terminal UI, web UI, and an MCP server so Claude Code can search its own past conversations.

Named after the protagonist of Total Recall — because your AI conversations deserve to be remembered.

Requirements

• Node.js 20.10 or later (Node 20/22 LTS run on macOS 11+; note that Node 24+ raised its minimum macOS version, so older Macs should stay on 20/22)

• npm (comes with Node.js)

• Native modules install as prebuilt binaries on Node 20–26 — no compiler needed. (Python 3 + setuptools and a C++ toolchain are only required if npm has to compile from source on an unusual platform.)

• Claude Code installed and used at least once (so ~/.claude/projects/ exists)

Check your setup

node --version    # Should be v20.10+
npm --version     # Should be v9+
ls ~/.claude/projects/   # Should list project directories

Related MCP server: ClaudeHistoryMCP

Installation

Shortcut — got a release tarball (quaid-x.y.z.tgz)? Skip the build entirely:

npm install -g ./quaid-x.y.z.tgz

If npm warns about allow-scripts (newer npm versions restrict install scripts), allow the native module's prebuilt-binary download:

npm install -g --allow-scripts=better-sqlite3 ./quaid-x.y.z.tgz

Then jump to First run. To build from source instead:

Step 1 — Get the code

git clone https://github.com/SEEDO-Media-Ltd/quaid.git
cd quaid

Step 2 — Install dependencies

npm install

This downloads all dependencies. The native SQLite and DuckDB modules ship prebuilt binaries for Node 20–26 on macOS (Apple Silicon and Intel) and Linux, so nothing should compile. If npm does fall back to compiling (unusual Node version or platform), you'll need Xcode Command Line Tools on macOS or build-essential on Linux, plus Python with setuptools.

Step 3 — Build

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Step 4 — Install globally

npm install -g .

This makes the quaid command available system-wide. Verify it worked:

quaid --version

You should see 1.0.0.

First run

The quickest way is the all-in-one command — initial sync, live watcher, and web UI in a single process:

quaid start

Or take it step by step:

Step 5 — Sync your history

quaid sync

This scans ~/.claude/projects/ for all your Claude Code session files and imports them into the database at ~/.quaid/quaid.db. You'll see output like:

Scanned: 42 files
Processed: 42 files
Sessions: 42
Turns: 3847

Step 6 — Check your stats

quaid stats

This shows a summary of everything imported:

Projects:       12
Sessions:       42
Turns:          3,847
Input tokens:   125,430
Output tokens:  892,105
Cache read:     15,234,567
Cache write:    1,234,567
Est. cost:      $127.35
Oldest session: 2026-01-15T08:30:00Z
Newest session: 2026-03-26T14:22:00Z

Usage

Browse in the terminal

quaid tui

Navigate with j/k, press Enter to drill in, q to go back, / to search, ? for help.

Browse in the browser

quaid web

Open http://localhost:4242 in your browser. Dark-themed dashboard with projects, sessions, search, and analytics.

Search from the command line

# Simple text search
quaid search "token refresh"

# Filter by project
quaid search "project:exampleapp authentication"

# Filter by model
quaid search "model:opus"

# Filter by tool used
quaid search "tool:Bash npm test"

# Filter by file touched
quaid search "file:plugin.php"

# Date ranges
quaid search "after:2026-03-01 before:2026-03-15"

# Sessions with errors
quaid search "has:error database migration"

# JSON output for scripting
quaid search "project:myapp" --json

Watch for new sessions (recommended)

quaid watch

This runs in the foreground, syncing new and updated session files as Claude Code writes them. Keep it running in a terminal tab, or set it up as a service (see below).

Export a session to markdown

# Export a specific session
quaid export abc12345-session-id > session.md

# Export all sessions
quaid export --all > all-sessions.md

View a specific session

quaid list-sessions
quaid show <session-id>

Analytics (DuckDB/Parquet)

# Build the analytics cache first
quaid build-cache

# Then analytics are available in the web UI at /analytics
# and via the MCP server's get_analytics tool

Pricing

Quaid estimates token costs using bundled Anthropic pricing. To view:

quaid pricing --show

To override with custom prices:

quaid pricing --edit

This opens ~/.quaid/pricing.json in your editor. After editing, recalculate all session costs:

quaid sync --recalculate-costs

Run at login (optional)

Linux (systemd)

mkdir -p ~/.config/systemd/user
cp service/quaid.service ~/.config/systemd/user/

# Edit the ExecStart path to match your node/quaid location
# Find it with: which quaid
nano ~/.config/systemd/user/quaid.service

systemctl --user daemon-reload
systemctl --user enable quaid
systemctl --user start quaid

# Verify it's running
systemctl --user status quaid

macOS (launchd)

cp service/com.seedo.quaid.plist ~/Library/LaunchAgents/

# Edit the path to quaid if needed
# Find it with: which quaid
nano ~/Library/LaunchAgents/com.seedo.quaid.plist

launchctl load ~/Library/LaunchAgents/com.seedo.quaid.plist

# Verify it's running
launchctl list | grep quaid

MCP server (let Claude Code search its own history)

Register Quaid with Claude Code — one command, then restart your session:

claude mcp add --scope user quaid quaid mcp

--scope user makes Quaid available in every project on this machine (the entry is stored in ~/.claude.json). To limit it to a single project instead, create a .mcp.json in that project's root:

{
  "mcpServers": {
    "quaid": {
      "command": "quaid",
      "args": ["mcp"]
    }
  }
}

Verify with claude mcp list (quaid should show as connected) or /mcp inside a Claude Code session. Note: registration is per-machine — it does not travel with project folders you copy to another computer.

This gives Claude Code 7 tools to query its own conversation history:

• search_conversations — full-text search with operators

• get_session — retrieve a full transcript

• get_session_summary — quick session overview

• list_sessions — recent sessions

• list_projects — all indexed projects

• get_stats — archive totals

• get_analytics — aggregate analytics

Configuration

Quaid stores its data in ~/.quaid/ by default. Override with environment variables:

View current config:

quaid config --show

All commands

quaid start [--port n] [--no-web]  # All-in-one: sync + watcher + web UI
quaid watch                        # Watch for new sessions (watcher only)
quaid sync [--full]                # One-shot sync
quaid sync --recalculate-costs     # Recalculate all costs
quaid search <query> [--json]      # Search conversations
quaid tui                          # Terminal UI
quaid web [--port 4242]            # Web UI
quaid mcp                          # MCP server (stdio)
quaid stats [--json]               # Archive statistics
quaid list-projects [--json]       # All projects
quaid list-sessions [--project n]  # Sessions list
quaid show <session-id>            # View a session
quaid export <session-id>          # Export to markdown (--all for everything)
quaid build-cache                  # Rebuild analytics cache
quaid pricing --show               # View pricing table
quaid pricing --edit               # Edit pricing overrides
quaid update <file.tgz>            # Update install from a local package
quaid config --show                # View configuration

Upgrading

Update an existing install from a new release tarball:

quaid update ./quaid-x.y.z.tgz

The database migrates automatically. If a release changes how sessions are parsed (the release notes will say), run quaid sync --full once afterwards to rebuild the archive with the new parser.

Troubleshooting

quaid: command not found after install Your npm global bin directory may not be in your PATH. Check with:

npm bin -g

Add that directory to your PATH in ~/.bashrc or ~/.zshrc.

better-sqlite3 tries to compile (gyp errors during install) That means no prebuilt binary matched your Node version — check node --version is 20–26. If you genuinely need to compile, install a C++ toolchain and Python setuptools:

# Ubuntu/Debian
sudo apt install build-essential python3-setuptools

# macOS (Xcode command line tools)
xcode-select --install
pip3 install setuptools

No sessions found after sync Check that Claude Code has been used and ~/.claude/projects/ contains .jsonl files:

find ~/.claude/projects -name "*.jsonl" | head -5

Analytics commands fail Run quaid build-cache first to generate the Parquet files.

Uninstall

npm uninstall -g quaid           # removes the CLI
rm -rf ~/.quaid                  # removes the database and config — this
                                 # deletes your archive, only if you mean it
claude mcp remove --scope user quaid   # if you registered the MCP server

If you installed the login service, unload it first — see service/README.md.

License

MIT — SEEDO Media Ltd