All your AI agent sessions in one place — browse, search, resume. Rust + GPUI.
Rust
docs: MCP guide and reference, README/PRODUCT/DESIGN updates for Connect
Corey Chiub6daa9abe2e0
diff --git a/DESIGN.md b/DESIGN.mdindex 75d5439..69b0568 100644--- a/DESIGN.md+++ b/DESIGN.md@@ -134,7 +134,7 @@ macOS 不设置横跨三栏的自定义 header。主窗口透明标题栏高 44p- 行内容 = 行首元素 + 标题 + 计数;计数一律 Label 档 muted。- 组头 "Agents"/"Projects" 用 Body 档常规字重 + muted 色(与主导航同字号同字重,仅靠颜色和"无行首图标"区分——加粗会让组头压过它统辖的行),带 13px chevron 可折叠。- 底部工具条常驻,总高 44px(含顶部 1px hairline),按钮靠右排列(次要操作区:透明底、hover 才出色,不与导航行选中态抢注意力)——依次为 chart-column "Insights"、齿轮 "Settings"、refresh。Insights 页打开时其图标以 primary 点亮,是工具条里唯一有激活态的按钮。Settings 同时进入 Wake 菜单并绑定 `⌘,`(其他平台 `Ctrl+,`),保持单例窗口。-- Settings 默认 820×600,采用 180px 窄侧栏 + 内容页结构,固定为 General / Locations / Remote hosts / Data / Updates / About 六项;About 与功能设置分离并钉在侧栏底部,Wake 菜单的 About Wake 直达同一页。About 沿用 Kooky/Birth 的信息顺序:产品图标、名称、版本、tagline、GitHub、短分隔线、版权/许可证与作者署名。Updates 是独立功能页,仅在用户点击页面按钮或 macOS Wake 菜单的 Check for Updates 时读取 GitHub 最新正式 Release 元数据,明确呈现检查中/最新版/有新版/失败四种状态;有新版时打开 Release 页供用户下载,不后台检查、不自行覆盖应用包。内部常规文字按钮统一沿用主界面的 24px 高、6px 圆角和主题交互色,普通页面动作使用 muted 填充 + hairline;发现新版后的 View Update 是需要用户继续完成的主操作,使用 32px 高 primary 填充和轻阴影。Appearance 分段选择器也使用同一材质。General 只放真实可用的全局偏好,当前为持久化的 System / Light / Dark 外观选择;不提供默认 “Open In” 终端。Data 只展示 Wake 本地存储位置、会话数与磁盘占用并提供文件管理器入口,不重复放刷新或清库动作;常规 Refresh 的唯一入口仍是主侧栏底部。Locations 页按 AgentId 声明序以 agent 分组,品牌名只在组头出现一次;本机有数据的组优先,未检测到的 agent 默认收进可展开区。每条路径以路径为主信息、会话数/不可用状态为 muted 副信息,最右为逐路径开关;停用时只降低文字层级,开关与菜单保持完整对比度。行本身不承担编辑,`…` 菜单集中 Edit / Show in Finder / 自定义 Remove。顶部操作为低强调的 Add location,Restore defaults 收进页级 `…` 菜单且无偏离时禁用。添加/编辑仍复用 agent 下拉 + 可手输路径 + 目录选择表单;关闭 location 后保留配置、停止扫描/监听并从会话与搜索结果排除,重新开启即增量扫回;纯路径管理不做内容校验。Remote hosts 页沿用 Locations 的版式:标题 + 说明,右侧低强调的 Sync now / Add host;host 列表为单张 popover 底圆角卡,一行一台(名字为主信息、同步状态为 muted 副信息,失败用 danger),`…` 菜单集中 Sync now / Remove,最右为开关;添加走与 location 同材质的单字段表单弹窗,SSH 前提说明放在字段下方。列表与详情页的远程会话以 `@host` 徽章标识:列表行为 primary 淡底填充胶囊(与 muted 项目胶囊区分),详情页与 model/source 同排用 primary 描边。+- Settings 默认 820×600,采用 180px 窄侧栏 + 内容页结构,固定为 General / Locations / Remote hosts / Connect / Data / Updates / About 七项(Connect 为 0.5.0 新增,插在 Remote hosts 与 Data 之间——两页都是"把 Wake 接到外部"的集成面,Data 之后是纯本地信息);About 与功能设置分离并钉在侧栏底部,Wake 菜单的 About Wake 直达同一页。About 沿用 Kooky/Birth 的信息顺序:产品图标、名称、版本、tagline、GitHub、短分隔线、版权/许可证与作者署名。Updates 是独立功能页,仅在用户点击页面按钮或 macOS Wake 菜单的 Check for Updates 时读取 GitHub 最新正式 Release 元数据,明确呈现检查中/最新版/有新版/失败四种状态;有新版时打开 Release 页供用户下载,不后台检查、不自行覆盖应用包。内部常规文字按钮统一沿用主界面的 24px 高、6px 圆角和主题交互色,普通页面动作使用 muted 填充 + hairline;发现新版后的 View Update 是需要用户继续完成的主操作,使用 32px 高 primary 填充和轻阴影。Appearance 分段选择器也使用同一材质。General 只放真实可用的全局偏好,当前为持久化的 System / Light / Dark 外观选择;不提供默认 “Open In” 终端。Data 只展示 Wake 本地存储位置、会话数与磁盘占用并提供文件管理器入口,不重复放刷新或清库动作;常规 Refresh 的唯一入口仍是主侧栏底部。Locations 页按 AgentId 声明序以 agent 分组,品牌名只在组头出现一次;本机有数据的组优先,未检测到的 agent 默认收进可展开区。每条路径以路径为主信息、会话数/不可用状态为 muted 副信息,最右为逐路径开关;停用时只降低文字层级,开关与菜单保持完整对比度。行本身不承担编辑,`…` 菜单集中 Edit / Show in Finder / 自定义 Remove。顶部操作为低强调的 Add location,Restore defaults 收进页级 `…` 菜单且无偏离时禁用。添加/编辑仍复用 agent 下拉 + 可手输路径 + 目录选择表单;关闭 location 后保留配置、停止扫描/监听并从会话与搜索结果排除,重新开启即增量扫回;纯路径管理不做内容校验。Remote hosts 页沿用 Locations 的版式:标题 + 说明,右侧低强调的 Sync now / Add host;host 列表为单张 popover 底圆角卡,一行一台(名字为主信息、同步状态为 muted 副信息,失败用 danger),`…` 菜单集中 Sync now / Remove,最右为开关;添加走与 location 同材质的单字段表单弹窗,SSH 前提说明放在字段下方。列表与详情页的远程会话以 `@host` 徽章标识:列表行为 primary 淡底填充胶囊(与 muted 项目胶囊区分),详情页与 model/source 同排用 primary 描边。Connect 页沿用 Data 页的版式,**只放状态与动作,不放文档**(用户 2026-09-08 三轮定稿:平级双卡带代码块、嵌套同卡、缩进从属卡都试过,根源是设置窗里塞了 README 内容,怎么排都像教程):标题 + 一句说明(不点名 MCP、不写 read-only 声明);「MCP server」卡 84px 一行显示 wake-mcp 名称与 mono 字体的 `~/…` 路径,右侧 Copy path,不放"Ready"状态行,只在找不到二进制时给一行 danger 文案;「Agents」卡三行(Claude Code / Codex / Cursor),17px 品牌图标领行、客户端名为主信息、用法提示为 muted 副信息、右侧是 ghost 的 Show/Hide 切换(chevron 图标 + 文案,muted 前景,用户 2026-09-08 追加)加 Copy command / Copy config;代码块**默认收起**,展开后出现在该行下方、左缘对齐到文字轴(行内边距 16 + 图标 17 + 间距 12),secondary 填充 + 主题圆角的 mono 逐行渲染,Settings 重开即复位;页尾一句 caption 说四个只读工具是什么,后跟 primary 色的 Setup guide 链接直达仓库的 docs/mcp.md(完整参考:参数、输出、key/ref 格式、错误语义、排障),README 的 Connect 段只留概览并链过去。整页一屏放下不滚动。复制成功走 gpui-component 的 success 通知,页面只展示不代写别家配置。- 工具条内的**状态行"常态沉默"**:仅刷新中或监听不可用时出现在按钮行上方;文案须可 truncate,窄侧栏放不下长句(故为 "Live updates off" 而非带操作建议的整句)。- 手动 Refresh 始终后台运行;进度复用侧栏状态行,完成后发通知,不用模态框阻断浏览、搜索或阅读。- 不把项目包装成卡片,不堆叠分支、时间或重复图标。项目行不加彩色标识——同一图标重复十几次不传递信息。diff --git a/PRODUCT.md b/PRODUCT.mdindex ee3b1d8..081a7ca 100644--- a/PRODUCT.md+++ b/PRODUCT.md@@ -28,13 +28,13 @@ Corey 本人(独立开发者,主力工具 Claude Code 与 Codex,中文为主)。## Capabilities and Constraints-已实现:十六家 adapter、FTS5 trigram 搜索(<3 码点 LIKE 降级)、**搜索跳转定位**(2026-08-18:⌘K 命中直达详情页对应消息并高亮,seq 契约保证)、详情页逐消息渲染(气泡/工具折叠簇/thinking/tree-sitter 高亮;2026-08-17 由整篇 markdown 方案升级)、恢复/收藏/置顶/导出/删除(废纸篓+墓碑)、文件监听增量、Insights 统计页(0.3.0:活跃热力图与 streak、时段/星期/月份分布、Agents·Projects·Models 三榜单按 sessions/tokens/prompts 切换;2026-09-03 加 Last 7 days 周对比行与 Over time 近 53 周按 agent/模型堆叠的每周 prompts 趋势图;口径=主线用户消息,规格见 DESIGN.md)、Updates 页与 macOS Wake 菜单手动检查 GitHub 最新正式版并打开 Release 页更新(不后台联网、不自动替换应用包)、测试套件(adapter 契约、DB 往返、scanner 回归 + CI 三平台 + pre-commit,合成 fixture)、三端桌面(macOS 主平台;Linux/Windows experimental,终端恢复/废纸篓·回收站/剪贴板按平台原生实现,发版 CI 自动出六产物)、窗口记忆(0.3.6:记住所在屏幕/屏内位置/最大化/全屏,重启与 Dock 重开都回到原处,Settings 开在主窗所在屏)、完整 macOS 菜单栏(0.3.6:标准 Edit/Window 菜单、⌘W、Window → Main Window,主窗关闭后 About/Settings/Updates 仍可用)、导出 Markdown 与保存图片走系统「另存为」并记住上次目录(0.3.6,issue #25)、远程 host(0.4.0,issue #21:Settings → Remote hosts 配 SSH 目标,rsync 白名单镜像会话数据到本地缓存后与本地会话同列同搜,`@host` 徽章标识;阶段 1 只读——不动远端文件、远程会话禁删,resume 以 Copy SSH command 形态提供;分期计划见 CLAUDE.md「远程 host」节)。+已实现:十六家 adapter、FTS5 trigram 搜索(<3 码点 LIKE 降级)、**搜索跳转定位**(2026-08-18:⌘K 命中直达详情页对应消息并高亮,seq 契约保证)、详情页逐消息渲染(气泡/工具折叠簇/thinking/tree-sitter 高亮;2026-08-17 由整篇 markdown 方案升级)、恢复/收藏/置顶/导出/删除(废纸篓+墓碑)、文件监听增量、Insights 统计页(0.3.0:活跃热力图与 streak、时段/星期/月份分布、Agents·Projects·Models 三榜单按 sessions/tokens/prompts 切换;2026-09-03 加 Last 7 days 周对比行与 Over time 近 53 周按 agent/模型堆叠的每周 prompts 趋势图;口径=主线用户消息,规格见 DESIGN.md)、Updates 页与 macOS Wake 菜单手动检查 GitHub 最新正式版并打开 Release 页更新(不后台联网、不自动替换应用包)、测试套件(adapter 契约、DB 往返、scanner 回归 + CI 三平台 + pre-commit,合成 fixture)、三端桌面(macOS 主平台;Linux/Windows experimental,终端恢复/废纸篓·回收站/剪贴板按平台原生实现,发版 CI 自动出六产物)、窗口记忆(0.3.6:记住所在屏幕/屏内位置/最大化/全屏,重启与 Dock 重开都回到原处,Settings 开在主窗所在屏)、完整 macOS 菜单栏(0.3.6:标准 Edit/Window 菜单、⌘W、Window → Main Window,主窗关闭后 About/Settings/Updates 仍可用)、导出 Markdown 与保存图片走系统「另存为」并记住上次目录(0.3.6,issue #25)、远程 host(0.4.0,issue #21:Settings → Remote hosts 配 SSH 目标,rsync 白名单镜像会话数据到本地缓存后与本地会话同列同搜,`@host` 徽章标识;阶段 1 只读——不动远端文件、远程会话禁删,resume 以 Copy SSH command 形态提供;分期计划见 CLAUDE.md「远程 host」节)、**MCP 接入**(0.5.0:随应用打包的只读 `wake-mcp` stdio server,四个工具 wake_search / wake_list_sessions / wake_get_session / wake_list_projects,Claude Code / Codex / Cursor 等任何 MCP 客户端可搜历史、按项目列会话、分页读转录;Settings → Connect 展示路径与可复制配置片段,只展示不代写别家配置;零 LLM、零网络、不写库;完整参考 docs/mcp.md)。后续边界(2026-09-07 定):摘要层(需 LLM、opt-in、明示会把会话正文发给用户配置的端点)只在 MCP 接入有真实使用之后再做;Timeline / Profile 一类视图建立在摘要之上;不做 ChatGPT / Claude.ai 导出导入主线、不做实体本体与知识图谱、不做 Chrome 扩展注入。约束:对 agent 数据目录只读;绝不写 Codex 的 SQLite;不读凭证;GPUI 无 SF Symbols(图标用 lucide SVG 自备)。已支持十六家 agent:Claude Code、Codex、Qoder CLI(`~/.qoder/projects` JSONL,active-leaf 分支恢复、tool result 回挂、`QODER_CONFIG_DIR`)、Copilot CLI、Cursor(CLI transcripts)、OpenCode(含 OpenCode 2 next,stable 的 `opencode.db` 与 next 的 `opencode-next.db` 同时扫描;逐会话兼容 `message+part`、真实 `session+session_message` 及早期 `session_v2` schema;preview 会话标 opencode2 徽章)、Kiro、Gemini CLI(2026-08-17 P1 五家落地)+ Pi、Oh My Pi、Grok Build、Kimi Code、Antigravity CLI(2026-08-19 对齐 kooky 内置 roster;Antigravity 正文加密仅元数据卡片)+ DeepSeek Harness(dsh,2026-08-20,zstd 事件日志透明解压;格式由源码推断,当天用户跑出真实会话完成首验)。做不了的:Cursor IDE chats 正文加密,Windsurf/Trae 加密,Amp/Factory(Droid)/Warp 云端无本地数据,Reasonix 本机零会话格式未实测。## Brand Commitments-名称 Wake(2026-08-14 由 Vibex 更名;取「船迹」——agent 驶过的痕迹,兼「唤醒」恢复会话之意)。界面语言英文(2026-08-14 由中文切换,用户反馈中文 UI 词汇观感生硬)。视觉基准(用户 2026-08-14 确认):现代 macOS 原生规范,工艺对标 Things / Bear(优雅轻盈的原生感);支持跟随系统或固定浅/深外观。agent 品牌色作为功能性识别色保留(Claude 橙 #D97757、Codex 绿 #12A06B 等,见 models.rs)。Session locations 自 0.2.9 起归入独立 Settings 窗口,主界面只保留齿轮入口;Settings 固定为 General / Locations / Remote hosts / Data / Updates / About(Remote hosts 为 0.4.0 新增),不提供默认 “Open In” 终端选择。+名称 Wake(2026-08-14 由 Vibex 更名;取「船迹」——agent 驶过的痕迹,兼「唤醒」恢复会话之意)。界面语言英文(2026-08-14 由中文切换,用户反馈中文 UI 词汇观感生硬)。视觉基准(用户 2026-08-14 确认):现代 macOS 原生规范,工艺对标 Things / Bear(优雅轻盈的原生感);支持跟随系统或固定浅/深外观。agent 品牌色作为功能性识别色保留(Claude 橙 #D97757、Codex 绿 #12A06B 等,见 models.rs)。Session locations 自 0.2.9 起归入独立 Settings 窗口,主界面只保留齿轮入口;Settings 固定为 General / Locations / Remote hosts / Connect / Data / Updates / About(Remote hosts 为 0.4.0 新增,Connect 为 0.5.0 新增),不提供默认 “Open In” 终端选择。## Evidence on Handdiff --git a/README.md b/README.mdindex 99db7d6..34aac66 100644--- a/README.md+++ b/README.md@@ -22,6 +22,7 @@ Your agent history is scattered across `~/.claude`, `~/.codex`, and a dozen othe- **Manage** — star/pin (stored in Wake's own DB, original files untouched), export to Markdown or save an inline image through the system Save dialog (Wake remembers the last folder), delete (system Trash + tombstone so deleted sessions stay deleted)- **Insights** — a stats page for your whole library: GitHub-style activity heatmap with streaks, hour / weekday / month breakdowns, and Agents / Projects / Models leaderboards switchable between sessions, tokens, and prompts- **Remote hosts** — mirror the sessions on your other machines over SSH (Settings → Remote hosts); they show up next to local ones with an `@host` badge, searchable like everything else, and resume through a copied `ssh -t` command+- **Connect your agents (MCP)** — a bundled read-only MCP server, `wake-mcp`, lets Claude Code, Codex, Cursor or any MCP client search your whole history, list recent sessions per project and read transcripts page by page, so a new agent can pick up where another one left off; Settings → Connect has copy-paste setup snippets@@ -66,6 +67,39 @@ How it works, and what it doesn't do yet:- Remote sessions are read-only in Wake: they can't be moved to the Trash, and the mirror simply follows whatever is on the remote- The remote is assumed to use each agent's default paths under the login user's home (`CODEX_HOME`-style overrides on the remote aren't detected), and remote Windows machines aren't supported+## Connect your agents (MCP)++Wake ships `wake-mcp`, a small read-only [MCP](https://modelcontextprotocol.io) server over stdio that sits next to the app binary (`Wake.app/Contents/MacOS/wake-mcp` on macOS, beside `wake` on Linux and Windows). Point an MCP client at it and the agent gets four tools:++| Tool | What it does |+|---|---|+| `wake_search` | Full-text search across every agent's transcripts (CJK and code substrings work); each snippet carries a `wake://session/<key>#<seq>` reference |+| `wake_list_sessions` | Most recently updated sessions, scoped by project (pass the agent's working directory), agent, time window or starred |+| `wake_get_session` | One transcript as compact Markdown — user and assistant messages with `[seq N]` markers, tool calls folded to a line, injected context omitted — paginated by `from_seq` |+| `wake_list_projects` | Projects with indexed sessions, most recently active first |++Setup is a copy-paste from Settings → Connect, or run `wake-mcp setup` in a terminal. For example, Claude Code:++```bash+claude mcp add --scope user wake -- "/Applications/Wake.app/Contents/MacOS/wake-mcp"+```++Codex reads the same server from `~/.codex/config.toml`:++```toml+[mcp_servers.wake]+command = "/Applications/Wake.app/Contents/MacOS/wake-mcp"+```++A few things worth knowing:++- Everything is read-only: the server opens Wake's index without write access and never scans or modifies anything; there are no delete or star tools+- Search and lists come from Wake's index, so keep Wake running for fresh results — every reply says how recent the index is. Reading a transcript parses the agent's files live, so it is always current+- Agents see the same session files Wake indexes, on this machine only (remote-host mirrors included); nothing leaves the machine+- `wake-mcp call wake_search '{"query":"useEffect("}'` runs a single tool from the terminal, handy for checking what an agent would see++The full reference — every parameter, output formats, key and reference formats, error semantics, troubleshooting — is in [docs/mcp.md](docs/mcp.md).+## Privacy stance- Agent data directories are opened **read-only**; Wake never writes to another tool's files or databases@@ -126,6 +160,8 @@ scripts/test.sh --smoke # adds a real-data scan baseline (reads ycargo test -p wake-core # data-layer tests only (adapter contracts, FTS, scanner)cargo run -p wake-core --bin scan # data-layer smoke test: scan and print statscargo run -p wake-core --bin scan -- --search "useEffect(" # search smoke test+cargo run -p wake-core --bin wake-mcp -- setup # print MCP setup snippets for the dev build+cargo run -p wake-core --bin wake-mcp -- call wake_search '{"query":"useEffect("}' # run one MCP tool against your indexWAKE_THEME=dark cargo run -p wake # force dark/light (defaults to system)WAKE_HOME=/path cargo run -p wake # point all agent adapters at a different home dir (portable installs, testing)WAKE_LIVE_REMOTE_HOST=<host> cargo test -p wake-core --test remote_sync live -- --ignored # run the remote-host pipeline against a real SSH host@@ -148,7 +184,8 @@ crates/│ ├── scanner.rs # single-pass scan: meta + FTS in one go, mtime incremental│ ├── watcher.rs # notify-based file watching → per-file incremental updates│ ├── db.rs # rusqlite (WAL): sessions / messages / messages_fts / user_data / tombstones (+ location, remote_hosts & schema meta tables)-│ └── services/ # terminal resume (per-platform: AppleScript / argv / Win32) / export / trash+│ ├── mcp/ # wake-mcp: read-only MCP server over stdio (hand-written JSON-RPC, four tools)+│ └── services/ # terminal resume (per-platform: AppleScript / argv / Win32) / export / trash / agent context helpers└── wake # GPUI app (three-pane workbench + ⌘K / Ctrl+K palette)```diff --git a/docs/mcp.md b/docs/mcp.mdnew file mode 100644index 0000000..6ab1020--- /dev/null+++ b/docs/mcp.md@@ -0,0 +1,258 @@+# Wake MCP server (`wake-mcp`)++`wake-mcp` is a small, read-only [Model Context Protocol](https://modelcontextprotocol.io) server that ships with Wake. It exposes Wake's session index to any MCP client — Claude Code, Codex, Cursor, or anything else that speaks MCP over stdio — so an agent can search your history, list what you worked on recently, and read a past transcript page by page.++It covers everything Wake indexes: sessions from every supported agent on this machine, plus the local mirrors of any remote hosts you configured. Nothing here can modify a session. The server opens Wake's index without write access, never scans or rebuilds it, and never touches the agents' own files except to read a transcript.++## Where it lives++| Platform | Path |+|---|---|+| macOS | `/Applications/Wake.app/Contents/MacOS/wake-mcp` |+| Linux | next to `wake`: `~/.local/bin/wake-mcp` (tar.gz install) or `/usr/bin/wake-mcp` (deb) |+| Windows | next to `Wake.exe` in the unpacked zip |++Settings → Connect in Wake shows the exact path for your install with a *Copy path* button, and one *Copy command* / *Copy config* button per client (*Show* reveals the snippet before you copy it). `wake-mcp setup` prints the same snippets from a terminal. Updating Wake keeps the path, so there is nothing to redo after an update.++## Setup++### Claude Code++```bash+claude mcp add --scope user wake -- "/Applications/Wake.app/Contents/MacOS/wake-mcp"+```++### Codex++Add to `~/.codex/config.toml`:++```toml+[mcp_servers.wake]+command = "/Applications/Wake.app/Contents/MacOS/wake-mcp"+```++### Cursor++Merge into `~/.cursor/mcp.json`:++```json+{+ "mcpServers": {+ "wake": { "command": "/Applications/Wake.app/Contents/MacOS/wake-mcp" }+ }+}+```++### Any other client++Run the binary as a stdio MCP server with no arguments. It reads Wake's index from the default location (`~/Library/Application Support/wake/wake.db` on macOS, `~/.local/share/wake/wake.db` on Linux, `%LOCALAPPDATA%\wake\wake.db` on Windows); pass `--db PATH` to point it elsewhere.++If the index does not exist yet, the server exits with status 2 and a message on stderr asking you to launch Wake once — Wake builds the index on first run.++### Removing it++`claude mcp remove wake` for Claude Code; for Codex and Cursor delete the `wake` block from the config file. Nothing else was installed.++## Using it++### Check that it is connected++- **Claude Code**: `claude mcp list` shows `wake` as connected; inside a session, `/mcp` lists the server and its four tools.+- **Codex**: restart Codex after editing `config.toml`; the `wake_*` tools show up in its tool list.+- **Cursor**: Settings → MCP shows `wake` with a green status dot.+- **No client at hand**: `wake-mcp call wake_list_projects` in a terminal prints exactly what an agent would see.++### Just ask++You do not need new commands. Ask in plain language and the agent picks the tool:++| You say | What the agent does |+|---|---|+| "What did I work on in this repo last week?" | `wake_list_sessions` with its working directory and `since: "7d"` |+| "Have I hit this inotify overflow error before?" | `wake_search` across every agent's transcripts |+| "Pick up where yesterday's Cursor session left off on the watcher" | `wake_list_sessions` (`agents: ["cursor"]`), then `wake_get_session` to read it, then it starts working |+| "Why did we choose rsync over a custom sync protocol?" | `wake_search` for the discussion, `wake_get_session` at the cited `seq` to read the reasoning |+| "Which projects have I touched this month?" | `wake_list_projects` with `since: "30d"` |++Answers can cite `wake://session/<key>#<seq>` references; the `seq` numbers are the same ones Wake shows in its transcript view and search results.++### Make the agent reach for it++Agents rarely call a tool nobody told them about. One line in the project's `CLAUDE.md`, `AGENTS.md` or Cursor rules turns it into a habit:++```+Before asking me for context about this repository, check earlier sessions with the wake MCP tools:+wake_list_sessions with the current directory, then wake_get_session for the relevant one.+```++### A worked example++```+You: What was I doing in this repo yesterday with Codex? I want to continue.++Agent: [wake_list_sessions {"project": "/Users/me/Github/app", "agents": ["codex"], "since": "2d"}]+ [wake_get_session {"key": "codex:0195c2a1-…", "max_messages": 40}]++ Yesterday's Codex session (14:10–15:32) reworked the retry loop in sync.rs:+ it moved the backoff into `Retry::next_delay`, added the jitter test, and+ stopped at a failing assertion in `tests/sync.rs:88` (seq 61 in that session).+ Want me to start from that failing test?+```++Everything above happens locally; Wake itself does not change and the other agent's files are only read.++### What it does not do++- No write tools: nothing can delete, star, rename or resume a session. Resuming stays in Wake.+- Subagent transcripts that live inside a session (Claude Code sidechains, Cursor subagents) are not included in `wake_get_session`; their count is reported so the agent knows they exist. Subagent sessions that Wake tracks as separate sessions (Grok) are folded under their parent in `wake_list_sessions` but can be read by key.+- Antigravity sessions are metadata only — their transcripts are encrypted on disk, so an agent gets the same preview card Wake shows.+- Archived Codex sessions appear in search results but not in `wake_list_sessions` or `wake_list_projects`.++## Keeping results fresh++Search and lists come from Wake's index. Wake keeps the index current while it is running (file watching for JSONL-based agents; SQLite-based agents such as Copilot and OpenCode refresh on launch and on manual refresh). Every reply ends with a line like++```+Index covers activity up to 2026-09-08 09:41:37 (local time); Wake keeps it fresh while it is running.+```++so an agent can tell how recent the data is. Reading a transcript with `wake_get_session` parses the agent's own files live, so it is always current regardless of the index.++## Tools++All four tools are read-only and return Markdown text (`content[0].text`). Parameters are JSON; every parameter except the ones marked required is optional.++### Shared parameters++| Parameter | Type | Meaning |+|---|---|---|+| `project` | string | Scope to one project. Pass an absolute path — the agent's working directory is ideal — or a project name. Path matching is three-tier: an exact match of an indexed project path; otherwise the longest indexed project that contains the path (you are in a subdirectory); otherwise every indexed project below the path (a monorepo root or a parent folder). A bare name matches the project name case-insensitively. When nothing matches, the reply lists the known projects instead of erroring. |+| `agents` | string[] | Only these agents. Ids: `claude-code`, `codex`, `grok`, `dsh`, `cursor`, `opencode`, `pi`, `omp`, `kiro`, `kimi`, `gemini`, `copilot`, `antigravity`, `qoder`, `hermes`, `openclaw`. Display names (`"Claude Code"`, `"Gemini CLI"`) and a few aliases (`claude`, `deepseek`, `opencode2`) are accepted too. |+| `since` | string | Only sessions updated at or after this time. Relative: `30m`, `24h`, `7d`, `2w`. Absolute: `2026-09-01`, `2026-09-01 09:30`, `2026-09-01T09:30:00Z`. Naive date-times are read in local time. |+| `limit` | integer | Maximum items to return; values outside the allowed range are clamped. |++### `wake_search`++Full-text search across every indexed transcript: user prompts, assistant replies, tool names and tool inputs (tool outputs are not indexed). Terms are ANDed. CJK text and code substrings such as `useEffect(` both work; terms shorter than three characters fall back to a slower substring scan.++| Parameter | Type | Default | Notes |+|---|---|---|---|+| `query` | string | required | search terms |+| `project`, `agents`, `since` | | | see above |+| `limit` | integer 1–30 | 10 | maximum sessions returned |++Results are grouped by session, best matches first, with up to three snippets per session. Each snippet carries a reference of the form `wake://session/<key>#<seq>` that `wake_get_session` accepts directly. Archived sessions are included.++```+26 sessions match `二维码` (project /Users/me/Github/app) — showing 3, best matches first.++1. `claude-code:28ffac16-…` · Claude Code · "Session manager for coding agents"+ /Users/me/Github/app · updated 2026-08-14 19:45:47 · 524 messages · claude-opus-5+ - seq 209 (assistant, 2026-08-14 14:45:03): …search "**二维码**" 2>&1 |…+ ref: wake://session/claude-code:28ffac16-…#209+```++### `wake_list_sessions`++Most recently updated sessions, newest first. Subagent sessions are folded into their parents and archived sessions are excluded. Pinned sessions are not moved to the top here (they are in Wake's own list), so `limit: 1` really is the newest session.++| Parameter | Type | Default | Notes |+|---|---|---|---|+| `project`, `agents`, `since` | | | see above |+| `starred` | boolean | false | only sessions starred in Wake |+| `limit` | integer 1–100 | 20 | |++Each line shows the session key, agent, title, project, last update, message count, model, and badges such as `@host` (remote host), `via vscode` (source) or `★ starred`.++### `wake_get_session`++One transcript as compact Markdown, parsed live from the agent's files.++| Parameter | Type | Default | Notes |+|---|---|---|---|+| `key` | string | required | a session key such as `claude-code:1b2c…`, or a `wake://session/<key>#<seq>` reference (the seq becomes the starting point) |+| `from_seq` | integer ≥ 0 | 0 | start at this message |+| `max_messages` | integer 1–200 | 60 | messages per page |+| `max_chars` | integer 200–100000 | 20000 | character budget per page |+| `max_message_chars` | integer 100–50000 | 4000 | budget per message, shared by its text, thinking and tool calls; longer content is truncated and marked |+| `include_tools` | boolean | false | include tool inputs and outputs (verbose) |+| `include_thinking` | boolean | false | include the assistant's recorded thinking |++The reply starts with a header (title, key, agent, host, project and branch, model, time range, message count), then one block per message:++```+### [seq 12] User · 2026-09-05 11:02:14+Why does the watcher drop events on Linux?++### [seq 13] Assistant · 2026-09-05 11:02:40+inotify queues overflow when …+- 🔧 Read: crates/wake-core/src/watcher.rs+- 🔧 Grep: need_rescan+```++Tool calls are folded to one line each (name plus input preview) unless `include_tools` is set; at most 40 tool calls are listed per message, the rest are counted. Injected context (system reminders, IDE context) is skipped and counted. Compaction summaries are kept as quotes. Images are noted, not included. Subagent transcripts are not included; their count is reported.++The footer says which seqs were shown and either `End of transcript.` or a `from_seq=<n>` hint for the next page. Seq numbers are the same ones Wake's own search results and transcript view use.++If the key is unknown the tool returns an error result (`isError: true`) explaining what keys look like; if only a bare native id is given, the server looks it up and, when several hosts share that id, lists the candidates.++### `wake_list_projects`++Projects (working directories) that have indexed sessions, most recently active first, with session counts and last-activity time. Archived-only projects are not listed.++| Parameter | Type | Default |+|---|---|---|+| `since` | string | |+| `limit` | integer 1–200 | 50 |++## Session keys and references++- Local sessions: `<agent>:<native id>`, for example `codex:0195c2a1-…`.+- Sessions mirrored from a remote host: `<agent>:<host>:<native id>`.+- References: `wake://session/<key>#<seq>` point at one message; `wake_get_session` accepts them as `key` and starts the page there.++The native id is the one the agent's own `--resume` flag expects.++## Errors++| Situation | Response |+|---|---|+| Unknown tool, wrong parameter type, unparsable `since` | JSON-RPC error `-32602` |+| Unknown method (for example `resources/list`) | JSON-RPC error `-32601` |+| Invalid JSON on the wire | JSON-RPC error `-32700` |+| Session key not found, transcript unreadable | normal result with `isError: true` and an explanation |+| No project matches, no search hits | normal result whose text says so |++## Command line++```bash+wake-mcp # serve MCP over stdio (what clients run)+wake-mcp --db PATH # use another index database+wake-mcp setup # print the setup snippets for Claude Code / Codex / Cursor+wake-mcp call wake_search '{"query":"useEffect(","limit":3}' # run one tool and print its text+wake-mcp --version+```++`call` is handy for checking what an agent would see. It exits non-zero when the tool reports an error.++## Protocol details++- Transport: stdio, one JSON-RPC 2.0 message per line; logs go to stderr only.+- Methods: `initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`. No resources, prompts or sampling.+- Protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` (the client's requested version is echoed when it is one of these).+- Capabilities: `tools` only; every tool is annotated `readOnlyHint: true`.+- Several clients can each run their own `wake-mcp` at the same time; they are independent read-only processes over the same index.++## Privacy and scope++- Everything runs on this machine. The server makes no network requests.+- Agents see the same session files Wake indexes — local agents' data directories plus the local mirrors of any remote hosts you configured in Wake. Nothing leaves the machine.+- Wake's read-only rules apply: other agents' directories and databases are opened read-only and credential files are never read.+- Because an agent's own session is also indexed by Wake, a `wake_search` call it makes today (the tool name and query) will show up in tomorrow's search results for the same term. Tool outputs are not indexed, so the results themselves do not.++## Troubleshooting++- **The client reports the server failed to start.** Run the binary in a terminal: `no Wake index at … — launch Wake once to build it` means Wake has never run on this machine (or `--db` points to the wrong place). `… is empty or from an older version` means the index predates this Wake version; launching Wake once upgrades it.+- **Results look stale.** Keep Wake running; the freshness line at the end of every reply tells you what the index covers. Copilot / OpenCode / Antigravity / Hermes / OpenClaw databases refresh when Wake launches or when you click Refresh.+- **A project path is not matched.** Pass the absolute path of the repository, or its name. `wake_list_projects` shows the paths Wake knows.+- **macOS refuses to run it ("cannot be opened because the developer cannot be verified").** Wake is signed but not notarized, and a client launching `wake-mcp` hits the same first-run gate as opening Wake itself. Clear the quarantine flag for the whole bundle once: `xattr -dr com.apple.quarantine /Applications/Wake.app`, then restart the client.