<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)

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

```bash
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:

```json
{
  "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:

| 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.

---

## Uninstall

```bash
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](service/README.md).

---

## License

MIT — SEEDO Media Ltd