文档 · Meowo

工作原理

以 Claude Code 为例；Codex / Kimi / Gemini CLI 走各自 CLI 的 hook 机制（OpenCode 走桥接插件），数据最终都落到同一份本地数据库。

 Claude Code 会话
   │  触发 hooks（SessionStart / UserPromptSubmit / PostToolUse / Stop …）
   │  渲染 statusline（取得准确的 Context 百分比）
   ▼
 meowo-reporter（命令行，读 stdin 的事件 JSON）
   │  解析事件、标题、项目、todo、Context 用量
   ▼
 ~/.meowo/board.db（SQLite，WAL）
   ▲
   │  文件监听 + 去抖刷新
 meowo-app（Tauri 贴纸，React 前端）

meowo-reporter 是一次性进程，不保存状态。每次触发 hook 时启动，读取事件、写库，然后退出，不会阻塞会话。
meowo-app 启动时监听 ~/.meowo/ 目录的变化，库一变就刷新界面。它还跑两个后台任务：标记空闲会话，以及首次启动时导入历史会话。
两端只通过这个 SQLite 文件通信，运行时不互相依赖。

自动接入 AI 编程 CLI

Meowo 通过各个 AI 编程 CLI 的 hooks 接收会话事件。应用启动时会检测本机已有的工具，并将 meowo-reporter 幂等接入对应配置。

用安装包时一般不需要手动操作。 Meowo 写入前会备份配置，保留已有 hooks，配置已经正确时不会重复修改。以 Claude Code 为例，它会补齐 ~/.claude/settings.json 中所需的 hook 事件，并把 statusLine 包装成 ~/.meowo/statusline.sh，以便拿到准确的 Context 百分比。写入是原子的；前提是相应 CLI 已完成首次运行或登录并生成配置目录。

接入后，新会话会自动出现在窗口里。Claude Code 本身见官方文档。

手动接入 Claude Code（可选）

不想先启动 app，或者要写入自定义的 settings 路径时，可以手动挂：

# 1. 编译 meowo-reporter（Rust workspace 根在 app/src-tauri）
cd app/src-tauri && cargo build --release -p meowo-reporter
# 产物：app/src-tauri/target/release/meowo-reporter(.exe)

# 2. 接入 ~/.claude/settings.json 的 hooks（用绝对路径）
bun scripts/install-hooks.mjs "<仓库绝对路径>/app/src-tauri/target/release/meowo-reporter.exe"

脚本会把 reporter 挂到需要的 hook 事件上（SessionStart / UserPromptSubmit / PostToolUse / Stop / SessionEnd / PermissionRequest，以及 PreToolUse 的 AskUserQuestion / ExitPlanMode；普通 hook 带 5s 超时，PermissionRequest 为 310s——要等你审批）。用同一个路径重复运行不会重复追加，也不会破坏已有的 hooks。

这个脚本只管 Claude Code。codex、kimi、gemini 的接入走各自 CLI 的原生 hook 配置（hook 命令带 --provider codex|kimi|gemini）；opencode 没有 hook 机制，Meowo 改为在 ~/.config/opencode/plugin/ 下生成桥接插件。它们都不经过这个脚本。

数据与配置

数据库：~/.meowo/board.db（SQLite，WAL）。可用 MEOWO_DB 覆盖路径。
应用设置：~/.meowo/settings.json。通知开关、主题、不透明度、界面密度、归档自动隐藏天数、用哪个终端恢复会话，都在这里。
用量缓存：~/.meowo/usage-cache.json。
statusLine 包装脚本：~/.meowo/statusline.sh。由 app 生成和维护，不用手改。
首次导入标记：~/.meowo/imported.json。删掉它，下次启动会重新导入最近的历史会话。