memhook 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to memhook are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0](https://github.com/utilia-ai-wox/memhook/compare/v0.2.2...v0.3.0) (2026-06-02)
+
+
+### Features
+
+* add init/uninstall setup + tail live monitor ([#29](https://github.com/utilia-ai-wox/memhook/issues/29)) ([e895c9a](https://github.com/utilia-ai-wox/memhook/commit/e895c9a44fb46a141a20f1716999be3a0208bb89))
+
+
+### Bug Fixes
+
+* harden hook path against file-system races and stdin errors ([#30](https://github.com/utilia-ai-wox/memhook/issues/30)) ([8a0f10e](https://github.com/utilia-ai-wox/memhook/commit/8a0f10e1d7a7184b7cc5fdcb4eb20ae4be516b0d))
+
+
+### Documentation
+
+* refresh all docs for v0.2.2 and revamp the README ([#27](https://github.com/utilia-ai-wox/memhook/issues/27)) ([ad1106a](https://github.com/utilia-ai-wox/memhook/commit/ad1106a3a0cea47ce75201a781fdf5eda80324b2))
+
 ## [0.2.2](https://github.com/utilia-ai-wox/memhook/compare/v0.2.1...v0.2.2) (2026-06-02)
 
 
@@ -45,75 +62,9 @@ and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.
 
 * graduate release line to clean 0.2.0 ([f0a07e5](https://github.com/utilia-ai-wox/memhook/commit/f0a07e51fe5792df4efd7af9d59452d97603b675))
 
-## [Unreleased]
-
-### Added
-
-- **OpenAI provider** (`MEMHOOK_PROVIDER=openai`) — Chat Completions API,
-  `Authorization: Bearer`, catalog as the leading system message so OpenAI's
-  automatic prompt caching can engage. Default model `gpt-4o-mini`.
-- **Ollama local provider** (`MEMHOOK_PROVIDER=ollama`) — native `/api/chat`
-  endpoint, no API key, `stream:false` + `format:"json"`. Default model
-  `llama3.1`, with a 30s default timeout to absorb cold model loads.
-- **YAML config file** (`config.yaml`) — optional, opt-in, read from
-  `$MEMHOOK_CONFIG` or `~/.config/memhook/config.yaml`. Precedence is
-  env var > YAML > default. A missing or malformed file is ignored
-  (fail-soft to defaults). See `config.example.yaml`.
-- `src/providers/factory.ts` — `createProvider()` selects the adapter from
-  `config.provider.type` with compile-time exhaustiveness.
-- `src/providers/http.ts` — single shared `postJsonWithRetry` transport
-  (timeout + single retry) used by all providers.
-- `MEMHOOK_PROVIDER` and `MEMHOOK_CONFIG` env vars; per-provider defaults for
-  model / API-key env var / timeout.
-- Hardening pre-publish (CI, CHANGELOG, CONTRIBUTING, `.env.example`)
-
-### Changed
-
-- The provider interface is now provider-agnostic: Anthropic-specific
-  `betaHeaders` and `cacheControlTtl` moved off the shared `SelectionRequest`
-  into `AnthropicProviderOptions`. `ProviderConfig.apiKey` is now optional
-  (local providers need none).
-- Cache key now includes the provider identity (`type:model`) so switching
-  provider or model never serves a selection made by a different model.
-- The two hardcoded version strings (`config.ts`, `bin/memhook.ts`) are
-  centralised in `src/version.ts`.
-
-### Note
-
-- Adding `openai` / `ollama` introduces opt-in outbound calls to
-  `api.openai.com` / `localhost:11434`. The default remains Anthropic-only;
-  `api.anthropic.com` is still the sole endpoint for an unconfigured user. No
-  telemetry, no phone-home.
-- First runtime dependency: `yaml` (zero sub-dependencies).
-
-## [0.1.0-preview.0] — 2026-05-28
-
-Initial public preview.
-
-### Added
-
-- `src/router.ts` — UserPromptSubmit hook entry point with cap-A1 projection
-  fix (skip a file pre-injection if its content would push the cumulated
-  injection past `maxAdditionalChars`, while always allowing at least one).
-- `src/catalog.ts` — catalog builder with Q4 title-only reduction for
-  non-CWD zones (~50% size cut on a typical 3-repo layout).
-- `src/cache.ts` — local LRU cache keyed on
-  `sha256(prompt + catalog_mtime + cwd + script_version)`. Stored as
-  per-key JSON files. 60-min TTL by default, 7-day eviction floor.
-- `src/preFilter.ts` — trivial-prompt pre-filter loaded from
-  `~/.config/memhook/trivial-words.txt` with a sensible default list.
-- `src/providers/anthropic.ts` — provider implementation for Anthropic
-  Messages API. Uses `ephemeral` `1h` cache control on the system prompt
-  (GA in 2026, no beta header) so the catalog sits in cache (10× cheaper
-  writes amortised across the hour).
-- `src/config.ts` — env-driven config loader. No YAML in v0.1; deferred to
-  v0.2.
-- `bin/memhook.ts` — CLI with `run`, `build-catalog`, `version`, `help`.
-- JSONL observability log at `~/.claude/logs/memhook.log` including
-  `additional_size_chars` + `additional_size_tokens_est` so users can audit
-  the actual size of the injected `additionalContext` over time.
-- 18 unit tests covering the router pipeline, pre-filter normalisation, and
-  cache key derivation / TTL / eviction.
-
-[Unreleased]: https://github.com/utilia-ai-wox/memhook/compare/v0.1.0-preview.0...HEAD
-[0.1.0-preview.0]: https://github.com/utilia-ai-wox/memhook/releases/tag/v0.1.0-preview.0
+## [0.1.0-preview.0](https://github.com/utilia-ai-wox/memhook/releases/tag/v0.1.0-preview.0) (2026-05-28)
+
+Initial public preview: Anthropic Haiku provider, fail-soft pipeline, cap-A1
+projection fix, JSONL observability log, catalog builder, local LRU cache,
+trivial-prompt pre-filter, and the `memhook run | build-catalog | version`
+CLI.

package/README.md

@@ -1,91 +1,128 @@
+<div align="center">
+
 # memhook
 
-> Semantic memory router for Claude Code — picks the relevant feedbacks &
-> rules for each prompt via Haiku, injects them as `additionalContext`.
+**Stop loading every memory file on every prompt. memhook routes only the relevant ones.**
 
-**Status**: `v0.1.0-preview` — extracted from a private hook used daily across
-3 large repos. API surface and naming may shift before `v1.0.0`.
+<p align="center">
+  <a href="https://www.npmjs.com/package/memhook"><img src="https://img.shields.io/npm/v/memhook?color=cb3837&logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/memhook"><img src="https://img.shields.io/npm/dm/memhook?color=cb3837" alt="npm downloads"></a>
+  <a href="https://github.com/utilia-ai-wox/memhook/actions/workflows/ci.yml"><img src="https://github.com/utilia-ai-wox/memhook/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/utilia-ai-wox/memhook/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/memhook?color=blue" alt="License: MIT"></a>
+  <img src="https://img.shields.io/node/v/memhook" alt="Node version">
+  <a href="https://github.com/utilia-ai-wox/memhook/stargazers"><img src="https://img.shields.io/github/stars/utilia-ai-wox/memhook?style=social" alt="GitHub stars"></a>
+</p>
 
-## Why
+A semantic memory router for [Claude Code](https://claude.com/claude-code) — a
+`UserPromptSubmit` hook that picks the relevant `feedback_*.md` & `rule_*.md`
+files for each prompt and injects them as `additionalContext`.
 
-Claude Code's `~/.claude/` directory accumulates a growing set of
-`feedback_*.md` (behavioural corrections) and `rule_*.md` (project doctrine)
-files. Loading all of them on every prompt is wasteful (10–14k tokens of
-catalog overhead, most of it irrelevant to the current question).
+</div>
 
-memhook uses **Haiku 4.5** as a cheap router: each user prompt is matched
-against a one-line catalog of all available memory files, and only the 0–5
-most relevant ones are read and injected into `additionalContext`. The rest
-sit on disk, invisible to Claude until they matter.
+<!-- TODO(demo): record an asciinema of `tail -f ~/.claude/logs/memhook.log`
+     while prompting Claude Code — it shows the router picking files live.
+     Embed: [![asciicast](https://asciinema.org/a/XXXXX.svg)](https://asciinema.org/a/XXXXX) -->
 
-## How it works
+## ✨ Features
 
-```
-UserPromptSubmit hook
-    │
-    ▼
-┌────────────────────────────────────────┐
-│ 1. Pre-filter trivial prompts          │ ── "ok" / "merci" → skip LLM
-│ 2. Check local LRU cache               │ ── identical prompt < 60min → hit
-│ 3. Call Haiku with catalog as system   │ ── ephemeral 1h cache control
-│ 4. Parse JSON array of basenames       │ ── ["feedback_X.md", "rule_Y.md"]
-│ 5. Read files, cap by token budget     │ ── max 9.5k chars or 5 files
-│ 6. Emit additionalContext              │
-└────────────────────────────────────────┘
-```
+- 🎯 **Relevant-only injection** — a cheap model picks the 0–5 memory files that matter for _this_ prompt.
+- 💸 **Token-frugal** — skips the 10–14k-token catalog dump; injects ~2k tokens of signal.
+- 🛡️ **Fail-soft** — never blocks Claude Code; every error path falls back to empty context.
+- 🔌 **Multi-provider** — Anthropic (default), OpenAI, or local Ollama. Your key, your endpoint.
+- 🤫 **Zero telemetry** — the only outbound call is the LLM endpoint _you_ chose.
+- 🪶 **One dependency** — `yaml`, with zero sub-deps.
+- ⚡ **Cached & pre-filtered** — an LRU cache + a trivial-prompt skip keep latency near zero.
+- 🧰 **One-command setup** — `memhook init` wires the hooks (with backup); `memhook tail` shows routing live.
 
-## Install
+## 🤔 Why
 
-```bash
-npm install -g memhook      # not yet published — see "From source" below
-```
+Claude Code's `~/.claude/` directory accumulates a growing set of
+`feedback_*.md` (behavioural corrections) and `rule_*.md` (project doctrine)
+files. Loading all of them on every prompt is wasteful — most of it is
+irrelevant to the question at hand.
+
+memhook uses a cheap router model (**Haiku 4.5** by default) to match each
+prompt against a one-line catalog of all your memory files, and injects only
+the most relevant ones. The rest sit on disk, invisible until they matter.
 
-### From source (preview)
+| Approach              | Tokens / prompt | Relevance         |
+| --------------------- | --------------- | ----------------- |
+| Load all memory files | 10–14k          | mostly irrelevant |
+| **memhook**           | ~2k             | only what matches |
+
+## 🚀 Quick start
 
 ```bash
-git clone https://github.com/utilia-ai-wox/memhook.git
-cd memhook
-bun install
-bun run build
-npm link
+npm install -g memhook
+export ANTHROPIC_API_KEY=sk-ant-…   # or see Providers for OpenAI / Ollama
+memhook init
 ```
 
-## Setup
+`memhook init` detects your Claude Code config, wires the two hooks into
+`~/.claude/settings.json` (backing it up first, never clobbering existing
+hooks), and builds the initial catalog. It is idempotent and supports
+`--dry-run`. Restart Claude Code and you're done — then watch it work live
+with [`memhook tail`](#-observability).
 
-1. **Set your API key**
-
-   ```bash
-   export ANTHROPIC_API_KEY=sk-ant-…
-   ```
+<details>
+<summary>Manual setup (what <code>init</code> automates)</summary>
 
-2. **Build the initial catalog**
+1. **Build the initial catalog**
 
    ```bash
    memhook build-catalog
    # → ~/.claude/cache/memory-catalog.txt
    ```
 
-3. **Wire the hooks** in `~/.claude/settings.json`:
+2. **Wire the hooks** in `~/.claude/settings.json`:
 
    ```json
    {
      "hooks": {
        "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "memhook run" }] }],
-       "SessionStart": [
-         {
-           "hooks": [{ "type": "command", "command": "memhook build-catalog" }]
-         }
-       ]
+       "SessionStart": [{ "hooks": [{ "type": "command", "command": "memhook build-catalog" }] }]
      }
    }
    ```
 
-## Configuration
+Remove it all later with `memhook uninstall` (also backs up first).
+
+</details>
 
-Every knob is an env var, and (since `v0.2`) optionally a YAML file.
-Precedence per key is **env var > YAML file > built-in default**, so an
-env-var-only setup behaves exactly as before. Sensible defaults work for most
-users.
+<details>
+<summary>From source (for contributors)</summary>
+
+```bash
+git clone https://github.com/utilia-ai-wox/memhook.git
+cd memhook
+bun install
+bun run build
+npm link
+```
+
+</details>
+
+## 🔍 How it works
+
+```
+UserPromptSubmit hook
+    │
+    ▼
+┌────────────────────────────────────────┐
+│ 1. Pre-filter trivial prompts          │ ── "ok" / "merci" → skip LLM
+│ 2. Check local LRU cache               │ ── identical prompt < 60min → hit
+│ 3. Call the router with catalog        │ ── ephemeral 1h cache control
+│ 4. Parse JSON array of basenames       │ ── ["feedback_X.md", "rule_Y.md"]
+│ 5. Read files, cap by token budget     │ ── max 9.5k chars or 5 files
+│ 6. Emit additionalContext              │
+└────────────────────────────────────────┘
+```
+
+## ⚙️ Configuration
+
+Every knob is an env var, and optionally a YAML file. Precedence per key is
+**env var > YAML file > built-in default**, so an env-var-only setup behaves
+exactly as before. Sensible defaults work for most users.
 
 | Variable                         | Default                         | Purpose                                |
 | -------------------------------- | ------------------------------- | -------------------------------------- |
@@ -119,7 +156,7 @@ selection:
   maxFiles: 5
 ```
 
-## Providers
+## 🔌 Providers
 
 The default provider is **Anthropic** — with no `MEMHOOK_PROVIDER` set, the
 only outbound call memhook ever makes is to `api.anthropic.com`, using your own
@@ -141,7 +178,7 @@ LLM endpoint _you_ choose to route through.
   the native `/api/chat` endpoint with `stream:false`; the timeout defaults to
   30s to absorb cold model loads.
 
-## Observability
+## 📊 Observability
 
 Every invocation appends one JSON line to `~/.claude/logs/memhook.log`:
 
@@ -157,18 +194,34 @@ Every invocation appends one JSON line to `~/.claude/logs/memhook.log`:
   "cache_read": 13398,
   "additional_size_chars": 20225,
   "additional_size_tokens_est": 5056,
-  "status": "ok"
+  "status": "ok",
+  "model": "claude-haiku-4-5"
 }
 ```
 
-Useful one-liner to inspect the last 7 days:
+### Live view — `memhook tail`
+
+Watch routing decisions as they happen, in colour:
+
+```bash
+memhook tail                          # follow live (Ctrl-C to quit)
+memhook tail --no-follow              # print recent log + summary, then exit
+memhook tail --status ok,cache_hit    # filter by status
+memhook tail -n 50                    # show more history first
+```
+
+Each row shows the time, status, prompt preview, latency, and model, plus the
+memories that were injected; a summary line reports the cache-hit rate and
+p50/p95 latency. Colour degrades to plain text when piped or under `NO_COLOR`.
+`tail` only reads the log, so it can never affect the hook. For raw analysis,
+the log is plain JSONL — e.g. the last 7 days by status:
 
 ```bash
 jq -c 'select((.ts | fromdateiso8601) > (now - 7*86400)) | .status' \
   ~/.claude/logs/memhook.log | sort | uniq -c
 ```
 
-## Status values
+### Status values
 
 | `status`               | Meaning                                               |
 | ---------------------- | ----------------------------------------------------- |
@@ -184,20 +237,29 @@ jq -c 'select((.ts | fromdateiso8601) > (now - 7*86400)) | .status' \
 | `api_no_content`       | API returned 200 but no text                          |
 | `parse_invalid`        | Response wasn't a valid JSON array                    |
 
-## Fail-soft
+## 🛡️ Fail-soft
 
 memhook never blocks Claude Code. On any error — missing key, network
 timeout, malformed JSON, broken filesystem — it emits an empty
-`additionalContext` and logs the status. Your prompt always reaches the
-model, just without injected memories for that turn.
+`additionalContext` and logs the status. **Your prompt always reaches the
+model**, just without injected memories for that turn.
 
-## Roadmap
+## 🗺️ Roadmap
 
-- `v0.2` ✅ — YAML config file, OpenAI provider, Ollama local provider
-- `v0.3` — TUI live monitor (`memhook tail`)
+- `v0.2` ✅ — YAML config file, OpenAI provider, Ollama local provider (published on npm)
+- `v0.3` — `memhook init` / `memhook uninstall` setup wizard + zero-dep live monitor (`memhook tail`)
 - `v0.4` — Companion skills (`/wrap`, `/curate`, `/relay`)
-- `v0.5` — Auto-bootstrap (`memhook init` detects empty memory dirs)
-- `v1.0` — Cross-platform validated, published to npm
+- `v1.0` — API frozen, cross-platform validated, listed on awesome-lists
+
+## 🤝 Contributing
+
+Contributions welcome — please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+The hook contract (fail-soft, no telemetry, strict TypeScript) is
+non-negotiable; the [`failsoft-auditor`](.claude/agents/failsoft-auditor.md)
+agent guards it on every PR.
+
+> [!TIP]
+> ⭐ If memhook saves you tokens, **star the repo** — it helps other Claude Code users find it.
 
 ## License
 

package/dist/bin/memhook.d.ts

@@ -1,16 +1,21 @@
 #!/usr/bin/env node
 /**
- * memhook CLI — three commands shipped in v0.1 preview:
+ * memhook CLI.
  *
  *   memhook run            Read stdin (Claude Code hook JSON), write hook output
  *   memhook build-catalog  Rebuild ~/.claude/cache/memory-catalog.txt
+ *   memhook init           Wire memhook into ~/.claude/settings.json (interactive)
+ *   memhook uninstall      Remove memhook's hooks from ~/.claude/settings.json
+ *   memhook tail           Pretty live view of the JSONL routing log
  *   memhook version        Print package version
  *
- * Designed to be wired into ~/.claude/settings.json hooks:
- *   "UserPromptSubmit": [{ "hooks": [{ "type": "command",
- *                                      "command": "memhook run" }] }]
- *   "SessionStart":     [{ "hooks": [{ "type": "command",
- *                                      "command": "memhook build-catalog" }] }]
+ * Only `run` obeys the fail-soft hook contract (never throws, never exits
+ * non-zero). The interactive commands (`init`/`uninstall`/`tail`) may exit
+ * non-zero on user error and are free to use the TTY — docs/SPECIFICATION.md §9.
+ *
+ * Wired into ~/.claude/settings.json hooks (see `memhook init`):
+ *   "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "memhook run" }] }]
+ *   "SessionStart":     [{ "hooks": [{ "type": "command", "command": "memhook build-catalog" }] }]
  */
 export {};
 //# sourceMappingURL=memhook.d.ts.map

package/dist/bin/memhook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memhook.d.ts","sourceRoot":"","sources":["../../bin/memhook.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;GAYG"}
+{"version":3,"file":"memhook.d.ts","sourceRoot":"","sources":["../../bin/memhook.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/bin/memhook.js

@@ -1,23 +1,32 @@
 #!/usr/bin/env node
 /**
- * memhook CLI — three commands shipped in v0.1 preview:
+ * memhook CLI.
  *
  *   memhook run            Read stdin (Claude Code hook JSON), write hook output
  *   memhook build-catalog  Rebuild ~/.claude/cache/memory-catalog.txt
+ *   memhook init           Wire memhook into ~/.claude/settings.json (interactive)
+ *   memhook uninstall      Remove memhook's hooks from ~/.claude/settings.json
+ *   memhook tail           Pretty live view of the JSONL routing log
  *   memhook version        Print package version
  *
- * Designed to be wired into ~/.claude/settings.json hooks:
- *   "UserPromptSubmit": [{ "hooks": [{ "type": "command",
- *                                      "command": "memhook run" }] }]
- *   "SessionStart":     [{ "hooks": [{ "type": "command",
- *                                      "command": "memhook build-catalog" }] }]
+ * Only `run` obeys the fail-soft hook contract (never throws, never exits
+ * non-zero). The interactive commands (`init`/`uninstall`/`tail`) may exit
+ * non-zero on user error and are free to use the TTY — docs/SPECIFICATION.md §9.
+ *
+ * Wired into ~/.claude/settings.json hooks (see `memhook init`):
+ *   "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "memhook run" }] }]
+ *   "SessionStart":     [{ "hooks": [{ "type": "command", "command": "memhook build-catalog" }] }]
  */
 import { route } from "../src/router.js";
 import { buildCatalog } from "../src/catalog.js";
 import { loadConfig } from "../src/config.js";
+import { runInit, runUninstall } from "../src/init.js";
+import { runTail } from "../src/tail.js";
 import { MEMHOOK_VERSION as VERSION } from "../src/version.js";
+const PROVIDERS = ["anthropic", "openai", "ollama"];
 async function main() {
     const cmd = process.argv[2] ?? "help";
+    const args = process.argv.slice(3);
     switch (cmd) {
         case "run":
             await cmdRun();
@@ -25,6 +34,15 @@ async function main() {
         case "build-catalog":
             cmdBuildCatalog();
             break;
+        case "init":
+            process.exitCode = await cmdInit(args);
+            break;
+        case "uninstall":
+            process.exitCode = await cmdUninstall(args);
+            break;
+        case "tail":
+            process.exitCode = await cmdTail(args);
+            break;
         case "version":
         case "--version":
         case "-v":
@@ -42,19 +60,20 @@ async function main() {
     }
 }
 async function cmdRun() {
-    const stdin = await readStdin();
-    let output;
+    // Fail-soft: read stdin AND route inside one try, so ANY error — a stdin
+    // read error (stdin 'error' event) just as much as a routing error — falls
+    // back to empty additionalContext and exit 0, never a non-zero exit that
+    // would block the user prompt.
+    let output = {
+        hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: "",
+        },
+    };
     try {
-        output = await route(stdin);
+        output = await route(await readStdin());
     }
     catch (err) {
-        // Fail-soft: emit empty additionalContext, never block the user prompt
-        output = {
-            hookSpecificOutput: {
-                hookEventName: "UserPromptSubmit",
-                additionalContext: "",
-            },
-        };
         if (process.env["MEMHOOK_DEBUG"] === "true") {
             process.stderr.write(`memhook run error: ${String(err)}\n`);
         }
@@ -69,6 +88,100 @@ function cmdBuildCatalog() {
     });
     process.stderr.write(`[memhook build-catalog] ${config.catalog.path} — ${result.lines}L, ${result.bytes}B\n`);
 }
+async function cmdInit(args) {
+    const { flags } = parseArgs(args, BOOL_INIT);
+    let provider;
+    if (typeof flags["provider"] === "string") {
+        if (!PROVIDERS.includes(flags["provider"])) {
+            process.stderr.write(`memhook init: unknown provider "${flags["provider"]}"\n`);
+            return 1;
+        }
+        provider = flags["provider"];
+    }
+    return runInit({
+        yes: flags["yes"] === true,
+        dryRun: flags["dry-run"] === true,
+        provider,
+        apiKeyEnv: strFlag(flags["api-key-env"]),
+        model: strFlag(flags["model"]),
+        bin: strFlag(flags["bin"]) ?? "memhook",
+        settingsPath: strFlag(flags["settings"]),
+        noCatalog: flags["no-catalog"] === true,
+    });
+}
+async function cmdUninstall(args) {
+    const { flags } = parseArgs(args, BOOL_UNINSTALL);
+    return runUninstall({
+        yes: flags["yes"] === true,
+        dryRun: flags["dry-run"] === true,
+        settingsPath: strFlag(flags["settings"]),
+        purge: flags["purge"] === true,
+    });
+}
+async function cmdTail(args) {
+    const { flags } = parseArgs(args, BOOL_TAIL);
+    const linesRaw = strFlag(flags["lines"]);
+    const lines = linesRaw !== undefined && /^\d+$/.test(linesRaw) ? Number(linesRaw) : 10;
+    const statusRaw = strFlag(flags["status"]);
+    const status = statusRaw
+        ? statusRaw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : undefined;
+    return runTail({
+        file: strFlag(flags["file"]),
+        lines,
+        noFollow: flags["no-follow"] === true,
+        status,
+    });
+}
+// ── tiny flag parser ─────────────────────────────────────────────────────────
+const BOOL_INIT = new Set(["yes", "dry-run", "no-catalog"]);
+const BOOL_UNINSTALL = new Set(["yes", "dry-run", "purge"]);
+const BOOL_TAIL = new Set(["no-follow"]);
+const SHORT = { "-y": "--yes", "-n": "--lines" };
+function strFlag(v) {
+    return typeof v === "string" ? v : undefined;
+}
+/**
+ * Parse `--key value`, `--key=value`, and boolean flags (those listed in
+ * `bools`, plus any `--key` not followed by a value). Unknown long flags that
+ * take a value consume the next non-dash token.
+ */
+function parseArgs(args, bools) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < args.length; i++) {
+        const raw = args[i];
+        if (raw === undefined)
+            continue;
+        const a = SHORT[raw] ?? raw;
+        if (!a.startsWith("--")) {
+            positionals.push(a);
+            continue;
+        }
+        const key = a.slice(2);
+        const eq = key.indexOf("=");
+        if (eq >= 0) {
+            flags[key.slice(0, eq)] = key.slice(eq + 1);
+            continue;
+        }
+        if (bools.has(key)) {
+            flags[key] = true;
+            continue;
+        }
+        const next = args[i + 1];
+        if (next !== undefined && !next.startsWith("-")) {
+            flags[key] = next;
+            i++;
+        }
+        else {
+            flags[key] = true;
+        }
+    }
+    return { flags, positionals };
+}
 function readStdin() {
     return new Promise((resolve, reject) => {
         let data = "";
@@ -82,30 +195,53 @@ function printHelp() {
     console.log(`memhook ${VERSION}
 
 USAGE
-  memhook <command>
+  memhook <command> [options]
 
 COMMANDS
   run                Read Claude Code hook JSON from stdin, emit additionalContext
   build-catalog      Rebuild the memory catalog at $MEMHOOK_CATALOG_PATH
+  init               Wire memhook into ~/.claude/settings.json (with backup)
+  uninstall          Remove memhook's hooks from ~/.claude/settings.json
+  tail               Pretty live view of the routing log (status, latency, memories)
   version            Print version
   help               Show this message
 
+init OPTIONS
+  --provider <p>     anthropic | openai | ollama (else prompted; default anthropic)
+  --api-key-env <n>  env var holding the API key (default per provider)
+  --model <m>        override the model id
+  --bin <name>       command written into settings.json (default: memhook)
+  --settings <path>  settings file to patch (default: ~/.claude/settings.json)
+  --no-catalog       skip the initial catalog build
+  --dry-run          print the plan, write nothing
+  -y, --yes          non-interactive (accept defaults / flags)
+
+uninstall OPTIONS
+  --settings <path>  settings file to patch (default: ~/.claude/settings.json)
+  --dry-run          print the plan, write nothing
+  -y, --yes          non-interactive
+  --purge            also report cache + log locations to clean up
+
+tail OPTIONS
+  -n, --lines <N>    history lines to show before following (default: 10)
+  --no-follow        print the recent log + summary, then exit (no live follow)
+  --status <a,b>     only show these statuses (e.g. ok,cache_hit)
+  --file <path>      log file to read (default: $MEMHOOK_LOG_PATH)
+
 ENV VARS
   MEMHOOK_ENABLED                 toggle (default: true)
   MEMHOOK_PROVIDER                anthropic | openai | ollama (default: anthropic)
   MEMHOOK_MODEL                   model id (per-provider default if unset)
   MEMHOOK_API_KEY_ENV             env var name holding the API key
-                                  (anthropic: ANTHROPIC_API_KEY, openai: OPENAI_API_KEY,
-                                   ollama: none required)
   MEMHOOK_BASE_URL                override the provider API endpoint
   MEMHOOK_CONFIG                  path to a YAML config file
-                                  (default: ~/.config/memhook/config.yaml)
+  MEMHOOK_LOG_PATH                JSONL log path (read by 'memhook tail')
   MEMHOOK_MAX_FILES               file-count cap (default: 5)
   MEMHOOK_MAX_ADDITIONAL_CHARS    injection size cap (default: 9500)
-  MEMHOOK_MAX_OUTPUT_TOKENS       model output cap (default: 200)
   MEMHOOK_TIMEOUT_MS              request timeout (default: 8000; ollama: 30000)
   MEMHOOK_DISABLE_CACHE=true      skip local LRU cache
   MEMHOOK_DISABLE_PREFILTER=true  skip trivial-prompt skip
+  NO_COLOR / MEMHOOK_NO_COLOR     disable colour in init/tail output
   MEMHOOK_DEBUG=true              print errors to stderr (default: silent fail-soft)
 
 PROVIDERS