内容
<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
**捕获、索引和搜索您的 Claude Code 对话历史。**
Quaid 实时监视 Claude Code 的会话文件，将所有内容存储在本地 SQLite 数据库中，并支持全文搜索、跟踪令牌成本，并提供多种方式浏览和查询您的历史记录 — 命令行界面、终端 UI、网页 UI 和 MCP 服务器，允许 Claude Code 搜索其自身的历史对话。
以《Total Recall》的主角命名 — 因为您的 AI 对话理应被铭记。
---
## 需求
- **Node.js** 20.10 或更高版本（Node 20/22 LTS 在 macOS 11+ 上运行；请注意，Node 24+ 提高了其最低 macOS 版本，因此较旧的 Mac 应该停留在 20/22）
- **npm**（随 Node.js 附带）
- 原生模块作为预编译二进制文件安装在 Node 20–26 上 — 无需编译器。（如果 npm 必须在不寻常的平台上从源代码编译，则需要 Python 3 + setuptools 和 C++ 工具链。）
- **Claude Code** 已安装并至少使用过一次（因此 `~/.claude/projects/` 存在）
### 检查您的设置
```bash
node --version # 应该为 v20.10+
npm --version # 应该为 v9+
ls ~/.claude/projects/ # 应该列出项目目录
```
---
## 安装
**快捷方式 — 有发布 tarball（`quaid-x.y.z.tgz`）？** 直接跳过构建：
```bash
npm install -g ./quaid-x.y.z.tgz
```
如果 npm 警告关于 `allow-scripts`（较新的 npm 版本限制安装脚本），请允许原生模块的预编译二进制下载：
```bash
npm install -g --allow-scripts=better-sqlite3 ./quaid-x.y.z.tgz
```
然后跳转到 [首次运行](#首次运行)。如果要从源代码构建：
### 步骤 1 — 获取代码
```bash
git clone https://github.com/SEEDO-Media-Ltd/quaid.git
cd quaid
```
### 步骤 2 — 安装依赖项
```bash
npm install
```
这下载了所有依赖项。原生 SQLite 和 DuckDB 模块为 Node 20–26 上的 macOS（Apple Silicon 和 Intel）和 Linux 提供了预编译二进制文件，因此无需编译。如果 npm 确实需要编译（不寻常的 Node 版本或平台），您将需要 macOS 上的 Xcode 命令行工具或 Linux 上的 `build-essential`，以及带有 setuptools 的 Python。
### 步骤 3 — 构建
```bash
npm run build
```
这将 TypeScript 编译为 `dist/` 目录中的 JavaScript。
### 步骤 4 — 全局安装
```bash
npm install -g .
```
这使得 `quaid` 命令在系统范围内可用。验证它是否有效：
```bash
quaid --version
```
您应该看到 `1.0.0`。
---
## 首次运行
最快捷的方式是使用一次性命令 — 初始同步、实时监视器和网页 UI 在单个进程中：
```bash
quaid start
```
或者一步一步来：
### 步骤 5 — 同步您的历史记录
```bash
quaid sync
```
这会扫描 `~/.claude/projects/` 中的所有 Claude Code 会话文件，并将它们导入到 `~/.quaid/quaid.db` 数据库中。您将看到类似的输出：
```
Scanned: 42 files
Processed: 42 files
Sessions: 42
Turns: 3847
```
### 步骤 6 — 检查您的统计信息
```bash
quaid stats
```
这显示了导入的所有内容的摘要：
```
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
```
---
## 用法
### 在终端中浏览
```bash
quaid tui
```
使用 `j`/`k` 导航，按 `Enter` 进入，`q` 返回， `/` 搜索，`?` 获取帮助。
### 在浏览器中浏览
```bash
quaid web
```
在浏览器中打开 http://localhost:4242。带有项目、会话、搜索和分析的深色主题仪表板。
### 从命令行搜索
```bash
# 简单文本搜索
quaid search "token refresh"
# 按项目筛选
quaid search "project:exampleapp authentication"
# 按模型筛选
quaid search "model:opus"
# 按使用的工具筛选
quaid search "tool:Bash npm test"
# 按触摸的文件筛选
quaid search "file:plugin.php"
# 日期范围
quaid search "after:2026-03-01 before:2026-03-15"
# 带有错误的会话
quaid search "has:error database migration"
# 用于脚本的 JSON 输出
quaid search "project:myapp" --json
```
### 监视新会话（推荐）
```bash
quaid watch
```
这在前台运行，同步新的和更新的会话文件，就像 Claude Code 编写它们一样。将它保留在终端标签页中运行，或将其设置为服务（见下文）。
### 将会话导出为 Markdown
```bash
# 导出特定会话
quaid export abc12345-session-id > session.md
# 导出所有会话
quaid export --all > all-sessions.md
```
### 查看特定会话
```bash
quaid list-sessions
quaid show <session-id>
```
### 分析（DuckDB/Parquet）
```bash
# 首先构建分析缓存
quaid build-cache
# 然后在网页 UI 中 /analytics 处以及通过 MCP 服务器的 get_analytics 工具提供分析
```
### 定价
Quaid 使用捆绑的 Anthropic 定价来估计令牌成本。要查看：
```bash
quaid pricing --show
```
要覆盖自定义价格：
```bash
quaid pricing --edit
```
这会在编辑器中打开 `~/.quaid/pricing.json`。编辑后，重新计算所有会话成本：
```bash
quaid sync --recalculate-costs
```
---
## 在登录时运行（可选）
### Linux（systemd）
```bash
mkdir -p ~/.config/systemd/user
cp service/quaid.service ~/.config/systemd/user/
# 编辑 ExecStart 路径以匹配您的 node/quaid 位置
# 使用以下命令查找：which quaid
nano ~/.config/systemd/user/quaid.service
systemctl --user daemon-reload
systemctl --user enable quaid
systemctl --user start quaid
# 验证它是否正在运行
systemctl --user status quaid
```
### macOS（launchd）
```bash
cp service/com.seedo.quaid.plist ~/Library/LaunchAgents/
# 编辑 quaid 路径（如果需要）
# 使用以下命令查找：which quaid
nano ~/Library/LaunchAgents/com.seedo.quaid.plist
launchctl load ~/Library/LaunchAgents/com.seedo.quaid.plist
# 验证它是否正在运行
launchctl list | grep quaid
```
---
## MCP 服务器（让 Claude Code 搜索其自身的历史记录）
将以下内容添加到您的 Claude Code MCP 配置中：
```json
{
"mcpServers": {
"quaid": {
"command": "quaid",
"args": ["mcp"]
}
}
}
```
这为 Claude Code 提供了 7 种工具来查询其自身的对话历史：
- `search_conversations` — 带有运算符的全文搜索
- `get_session` — 检索完整记录
- `get_session_summary` — 快速会话概述
- `list_sessions` — 最近会话
- `list_projects` — 所有索引项目
- `get_stats` — 存档总数
- `get_analytics` — 聚合分析
---
## 配置
Quaid 默认情况下将其数据存储在 `~/.quaid/` 中。使用环境变量覆盖：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `QUAID_HOME` | `~/.quaid` | 数据目录（数据库、配置、分析） |
| `QUAID_CLAUDE_HOME` | `~/.claude` | Claude Code 主目录 |
| `QUAID_WEB_PORT` | `4242` | 网页 UI 端口 |
查看当前配置：
```bash
quaid config --show
```
---
## 所有命令
```
quaid start [--port n] [--no-web] # 一体化：同步 + 监视器 + 网页 UI
quaid watch # 监视新会话（仅监视器）
quaid sync [--full] # 一次性同步
quaid sync --recalculate-costs # 重新计算所有成本
quaid search <query> [--json] # 搜索对话
quaid tui # 终端 UI
quaid web [--port 4242] # 网页 UI
quaid mcp # MCP 服务器（stdio）
quaid stats [--json] # 存档统计信息
quaid list-projects [--json] # 所有项目
quaid list-sessions [--project n] # 会话列表
quaid show <session-id> # 查看会话
quaid export <session-id> # 导出为 Markdown（--all 表示全部）
quaid build-cache # 重建分析缓存
quaid pricing --show # 查看定价表
quaid pricing --edit # 编辑定价覆盖
quaid update <file.tgz> # 从本地包更新安装
quaid config --show # 查看配置
```
---
## 升级
从新的发布 tarball 更新现有安装：
```bash
quaid update ./quaid-x.y.z.tgz
```
数据库会自动迁移。如果发布更改了会话的解析方式（发布说明会说明），请在之后运行 `quaid sync --full` 一次，以使用新的解析器重建存档。
---
## 故障排除
**安装后 `quaid: command not found`**
您的 npm 全局二进制目录可能不在您的 PATH 中。请检查：
```bash
npm bin -g
```
将该目录添加到 `~/.bashrc` 或 `~/.zshrc` 中的 PATH。
**`better-sqlite3` 尝试编译（安装期间 gyp 错误）**
这意味着没有预编译的二进制文件与您的 Node 版本匹配 — 请检查 `node --version` 是否为 20–26。如果您确实需要编译，请安装 C++ 工具链和 Python setuptools：
```bash
# Ubuntu/Debian
sudo apt install build-essential python3-setuptools
# macOS（Xcode 命令行工具）
xcode-select --install
pip3 install setuptools
```
**同步后未找到会话**
检查 Claude Code 是否已使用并且 `~/.claude/projects/` 包含 `.jsonl` 文件：
```bash
find ~/.claude/projects -name "*.jsonl" | head -5
```
**分析命令失败**
首先运行 `quaid build-cache` 以生成 Parquet 文件。
---
## License
MIT — SEEDO Media Ltd
