Docs

Docs

How it works, how it connects, and where data and config files live.

How it works

Using Claude Code as the example; Codex / Kimi / Gemini CLI use their own CLI hook mechanisms (OpenCode uses a bridge plugin instead), and the data all lands in the same local database.

 Claude Code session
   │  fires hooks (SessionStart / UserPromptSubmit / PostToolUse / Stop …)
   │  renders the statusline (for an accurate Context %)
   ▼
 meowo-reporter (CLI, reads event JSON from stdin)
   │  parses events, title, project, todos, Context usage
   ▼
 ~/.meowo/board.db (SQLite, WAL)
   ▲
   │  file watch + debounced refresh
 meowo-app (Tauri sticker, React front end)
  • meowo-reporter is a one-shot process with no state. It starts on each hook, reads the event, writes the DB, and exits — never blocking the session.
  • meowo-app watches ~/.meowo/ on startup and refreshes the UI whenever the DB changes. It also runs two background tasks: marking idle sessions, and importing history on first launch.
  • The two sides talk only through this SQLite file and don't depend on each other at runtime.

Auto-connect AI coding CLIs

Meowo receives session events through each AI coding CLI's hooks. On startup it detects the tools on your machine and idempotently wires meowo-reporter into their config.

With the installer you usually don't need to do anything manually. Meowo backs up config before writing, keeps your existing hooks, and won't re-edit when things are already correct. For Claude Code it fills in the required hook events in ~/.claude/settings.json and wraps the statusLine into ~/.meowo/statusline.sh for an accurate Context %. Writes are atomic; the CLI must have run or logged in once to create its config directory.

Once connected, new sessions show up in the window automatically. For Claude Code itself, see the official docs.

Manual Claude Code setup (optional)

If you don't want to launch the app first, or need to write to a custom settings path, you can hook it up by hand:

# 1. Build meowo-reporter (the Rust workspace root is app/src-tauri)
cd app/src-tauri && cargo build --release -p meowo-reporter
# output: app/src-tauri/target/release/meowo-reporter(.exe)

# 2. Wire into ~/.claude/settings.json hooks (use an absolute path)
bun scripts/install-hooks.mjs "<repo-abs-path>/app/src-tauri/target/release/meowo-reporter.exe"

The script attaches the reporter to the hook events it needs (SessionStart / UserPromptSubmit / PostToolUse / Stop / SessionEnd / PermissionRequest, plus PreToolUse's AskUserQuestion / ExitPlanMode; normal hooks get a 5s timeout, PermissionRequest 310s so it can wait for your approval). Running it again with the same path won't duplicate entries or break your existing hooks.

This script only handles Claude Code. codex, kimi, and gemini connect through their own native hook config (the hook command carries --provider codex|kimi|gemini); opencode has no hook mechanism, so Meowo generates a bridge plugin under ~/.config/opencode/plugin/ instead. None of them go through this script.

Data & config

  • Database: ~/.meowo/board.db (SQLite, WAL). Override the path with MEOWO_DB.
  • App settings: ~/.meowo/settings.json — notification toggle, theme, opacity, UI density, archive auto-hide days, and which terminal resumes sessions all live here.
  • Usage cache: ~/.meowo/usage-cache.json.
  • statusLine wrapper: ~/.meowo/statusline.sh. Generated and maintained by the app; no need to edit.
  • First-import marker: ~/.meowo/imported.json. Delete it to re-import recent history on the next launch.