Quaid

<p align="center"> <img src="assets/quaid-banner.jpeg" alt="Quaid — a cartoon developer in a memory-implant chair, surrounded by terminal windows archiving his conversations" width="100%"> </p> # 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 ```bash node --version # Should be v20.10+ npm --version # Should be v9+ ls ~/.claude/projects/ # Should list project directories ``` --- ## Installation **Shortcut — got a release tarball (`quaid-x.y.z.tgz`)?** Skip the build entirely: ```bash 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: ```bash npm install -g --allow-scripts=better-sqlite3 ./quaid-x.y.z.tgz ``` Then jump to [First run](#first-run). To build from source instead: ### Step 1 — Get the code ```bash git clone https://github.com/SEEDO-Media-Ltd/quaid.git cd quaid ``` ### Step 2 — Install dependencies ```bash 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 ```bash npm run build ``` This compiles TypeScript to JavaScript in the `dist/` directory. ### Step 4 — Install globally ```bash npm install -g . ``` This makes the `quaid` command available system-wide. Verify it worked: ```bash 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: ```bash quaid start ``` Or take it step by step: ### Step 5 — Sync your history ```bash 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 ```bash 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 ```bash quaid tui ``` Navigate with `j`/`k`, press `Enter` to drill in, `q` to go back, `/` to search, `?` for help. ### Browse in the browser ```bash quaid web ``` Open http://localhost:4242 in your browser. Dark-themed dashboard with projects, sessions, search, and analytics. ### Search from the command line ```bash # 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) ```bash 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 ```bash # Export a specific session quaid export abc12345-session-id > session.md # Export all sessions quaid export --all > all-sessions.md ``` ### View a specific session ```bash quaid list-sessions quaid show <session-id> ``` ### Analytics (DuckDB/Parquet) ```bash # 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: ```bash quaid pricing --show ``` To override with custom prices: ```bash quaid pricing --edit ``` This opens `~/.quaid/pricing.json` in your editor. After editing, recalculate all session costs: ```bash quaid sync --recalculate-costs ``` --- ## Run at login (optional) ### Linux (systemd) ```bash 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) ```bash 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) Add to your Claude Code MCP configuration: ```json { "mcpServers": { "quaid": { "command": "quaid", "args": ["mcp"] } } } ``` 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: | Variable | Default | Description | |----------|---------|-------------| | `QUAID_HOME` | `~/.quaid` | Data directory (database, config, analytics) | | `QUAID_CLAUDE_HOME` | `~/.claude` | Claude Code home directory | | `QUAID_WEB_PORT` | `4242` | Web UI port | View current config: ```bash 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: ```bash 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: ```bash 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: ```bash # 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: ```bash find ~/.claude/projects -name "*.jsonl" | head -5 ``` **Analytics commands fail** Run `quaid build-cache` first to generate the Parquet files. --- ## License MIT — SEEDO Media Ltd