@mauribadnights/clooks 0.5.0 → 0.5.2

package/README.md

@@ -5,6 +5,8 @@ Persistent hook runtime for Claude Code. Eliminate cold starts. Get observabilit
 [![npm](https://img.shields.io/npm/v/@mauribadnights/clooks)](https://www.npmjs.com/package/@mauribadnights/clooks)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+**[Documentation](https://mauribadnights.github.io/clooks/)**
+
 ## Performance
 
 | Metric | Without clooks | With clooks | Improvement |

package/dist/cli.js

@@ -22,7 +22,7 @@ const program = new commander_1.Command();
 program
     .name('clooks')
     .description('Persistent hook runtime for Claude Code')
-    .version('0.5.0');
+    .version('0.5.1');
 // --- start ---
 program
     .command('start')
@@ -32,11 +32,13 @@ program
     .action(async (opts) => {
     const noWatch = opts.watch === false;
     if (!opts.foreground) {
-        // Background mode: check if already running and healthy
+        // Fix 6: Idempotent start — check if daemon is already healthy first
+        // This covers both normal PID file case AND orphaned daemon (no PID file)
         if ((0, server_js_1.isDaemonRunning)()) {
             const healthy = await (0, server_js_1.isDaemonHealthy)();
             if (healthy) {
-                console.log('Daemon is already running.');
+                const pid = (0, fs_1.existsSync)(constants_js_1.PID_FILE) ? (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim() : '?';
+                console.log(`Daemon is already running (pid ${pid}).`);
                 process.exit(0);
             }
             // PID alive but daemon unhealthy — stale process after sleep/lid-close
@@ -45,6 +47,16 @@ program
                 console.log(`Cleaned up stale daemon (pid ${stalePid}), starting fresh`);
             }
         }
+        else {
+            // No PID file or dead PID — check if an orphaned daemon is on the port
+            const health = await (0, server_js_1.probeHealth)();
+            if (health && health.pid) {
+                // Orphaned daemon found — re-adopt it
+                (0, server_js_1.writePidFile)(health.pid);
+                console.log(`Adopted existing daemon (pid ${health.pid}).`);
+                process.exit(0);
+            }
+        }
         // Ensure config dir exists
         if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
             (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
@@ -63,7 +75,15 @@ program
             console.log(`Daemon started (pid ${pid}), listening on 127.0.0.1:${constants_js_1.DEFAULT_PORT}`);
         }
         else {
-            console.log('Daemon started. Check ~/.clooks/daemon.log if issues arise.');
+            // Fix 1: After spawn, if PID file missing, check if port responded (orphan recovery)
+            const health = await (0, server_js_1.probeHealth)();
+            if (health && health.pid) {
+                (0, server_js_1.writePidFile)(health.pid);
+                console.log(`Adopted existing daemon (pid ${health.pid}).`);
+            }
+            else {
+                console.log('Daemon started. Check ~/.clooks/daemon.log if issues arise.');
+            }
         }
         process.exit(0);
     }
@@ -86,12 +106,24 @@ program
 program
     .command('stop')
     .description('Stop the clooks daemon')
-    .action(() => {
+    .action(async () => {
+    // Try sync stop first (fast path with PID file)
     if ((0, server_js_1.stopDaemon)()) {
         console.log('Daemon stopped.');
+        return;
+    }
+    // Fix 4: No PID file — try async recovery via /health
+    const result = await (0, server_js_1.stopDaemonAsync)();
+    if (result.stopped) {
+        if (result.recovered) {
+            console.log(`Daemon stopped (recovered orphan, pid ${result.pid}).`);
+        }
+        else {
+            console.log('Daemon stopped.');
+        }
     }
     else {
-        console.log('Daemon is not running (no PID file or process not found).');
+        console.log('Daemon is not running.');
     }
 });
 // --- status ---
@@ -100,18 +132,28 @@ program
     .description('Show daemon status')
     .action(async () => {
     const running = (0, server_js_1.isDaemonRunning)();
+    const serviceStatus = (0, service_js_1.getServiceStatus)();
     if (!running) {
+        // Fix 2: No PID file or dead PID — check if orphaned daemon is on the port
+        const health = await (0, server_js_1.probeHealth)();
+        if (health && health.pid) {
+            // Orphaned daemon found — recover PID file
+            (0, server_js_1.writePidFile)(health.pid);
+            console.log(`Status: running (recovered, pid ${health.pid})`);
+            console.log(`Port: ${constants_js_1.DEFAULT_PORT}`);
+            console.log(`Service: ${serviceStatus}`);
+            console.log('Note: PID file was missing. Re-adopted orphaned daemon.');
+            return;
+        }
         console.log('Status: stopped');
         return;
     }
     const pid = (0, fs_1.existsSync)(constants_js_1.PID_FILE) ? (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim() : '?';
-    // Try to hit health endpoint
-    // Service status
-    const serviceStatus = (0, service_js_1.getServiceStatus)();
+    // Try to hit health endpoint for detailed info
     try {
         const { get } = await import('http');
         const data = await new Promise((resolve, reject) => {
-            const req = get(`http://127.0.0.1:${constants_js_1.DEFAULT_PORT}/health`, (res) => {
+            const req = get(`http://127.0.0.1:${constants_js_1.DEFAULT_PORT}/health/detail`, (res) => {
                 let body = '';
                 res.on('data', (chunk) => { body += chunk.toString(); });
                 res.on('end', () => resolve(body));
@@ -333,6 +375,15 @@ program
             }
         }
     }
+    else {
+        // No PID file — check for orphaned daemon on the port
+        const health = await (0, server_js_1.probeHealth)();
+        if (health && health.pid) {
+            (0, server_js_1.writePidFile)(health.pid);
+            (0, sync_js_1.syncSettings)();
+            process.exit(0);
+        }
+    }
     // Ensure config dir exists
     if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
         (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });

package/dist/handlers.d.ts

@@ -1,4 +1,6 @@
 import type { HandlerConfig, HandlerResult, HandlerState, HookEvent, HookInput, PrefetchContext } from './types.js';
+/** Reset cached shell env (for testing) */
+export declare function resetShellEnv(): void;
 /** Match handler agent field against current session agent (case-insensitive, comma-separated) */
 declare function matchAgent(pattern: string, currentAgent: string): boolean;
 /** Match handler project field against cwd path */

package/dist/handlers.js

@@ -1,6 +1,7 @@
 "use strict";
 // clooks hook handlers — execution engine
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetShellEnv = resetShellEnv;
 exports.matchAgent = matchAgent;
 exports.matchProject = matchProject;
 exports.resetHandlerStates = resetHandlerStates;
@@ -17,6 +18,47 @@ const constants_js_1 = require("./constants.js");
 const filter_js_1 = require("./filter.js");
 const llm_js_1 = require("./llm.js");
 const deps_js_1 = require("./deps.js");
+/**
+ * Resolve the user's login shell PATH once at startup.
+ * When the daemon runs under launchd/systemd, it inherits a minimal PATH
+ * that may not include /opt/homebrew/bin, pyenv shims, nvm dirs, etc.
+ * This ensures script handlers see the same PATH as the user's terminal.
+ */
+let _shellEnv = null;
+function getShellEnv() {
+    if (_shellEnv)
+        return _shellEnv;
+    try {
+        const shell = process.env.SHELL || '/bin/sh';
+        const output = (0, child_process_1.execSync)(`${shell} -ilc 'env'`, {
+            timeout: 5000,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const env = {};
+        for (const line of output.split('\n')) {
+            const idx = line.indexOf('=');
+            if (idx > 0) {
+                env[line.slice(0, idx)] = line.slice(idx + 1);
+            }
+        }
+        // Merge: shell env as base, but keep daemon-specific vars (like ANTHROPIC_API_KEY)
+        _shellEnv = { ...env, ...process.env };
+        // PATH specifically: prefer the shell's PATH (has homebrew, pyenv, nvm, etc.)
+        if (env.PATH) {
+            _shellEnv.PATH = env.PATH;
+        }
+    }
+    catch {
+        // Fallback: just use process.env as-is
+        _shellEnv = process.env;
+    }
+    return _shellEnv;
+}
+/** Reset cached shell env (for testing) */
+function resetShellEnv() {
+    _shellEnv = null;
+}
 /** Match handler agent field against current session agent (case-insensitive, comma-separated) */
 function matchAgent(pattern, currentAgent) {
     const agents = pattern.split(',').map(a => a.trim().toLowerCase());
@@ -313,6 +355,7 @@ function executeScriptHandler(handler, input) {
         const child = (0, child_process_1.spawn)('sh', ['-c', h.command], {
             stdio: ['pipe', 'pipe', 'pipe'],
             timeout,
+            env: getShellEnv(),
         });
         let stdout = '';
         let stderr = '';

package/dist/server.d.ts

@@ -33,8 +33,18 @@ export declare function startDaemon(manifest: Manifest, metrics: MetricsCollecto
 }): Promise<ServerContext>;
 /**
  * Stop a running daemon by reading PID file and sending SIGTERM.
+ * If no PID file exists, tries to recover PID from the health endpoint.
  */
 export declare function stopDaemon(): boolean;
+/**
+ * Async version of stopDaemon that can recover orphaned daemons via /health.
+ * Returns { stopped: boolean, pid?: number, recovered?: boolean }.
+ */
+export declare function stopDaemonAsync(): Promise<{
+    stopped: boolean;
+    pid?: number;
+    recovered?: boolean;
+}>;
 /**
  * Check if daemon is currently running (PID check only).
  * Use for stop/status where a quick check is fine.
@@ -46,6 +56,18 @@ export declare function isDaemonRunning(): boolean;
  * Use for ensure-running and start where correctness matters.
  */
 export declare function isDaemonHealthy(): Promise<boolean>;
+/**
+ * Probe the health endpoint on the daemon port.
+ * Returns the parsed health response (including pid) or null if unreachable.
+ */
+export declare function probeHealth(port?: number): Promise<{
+    status: string;
+    pid: number;
+} | null>;
+/**
+ * Write a PID to the daemon PID file, creating the config dir if needed.
+ */
+export declare function writePidFile(pid: number): void;
 /**
  * Clean up a stale daemon: remove PID file and attempt to kill the process.
  * Returns the stale PID for logging purposes.

package/dist/server.js

@@ -5,8 +5,11 @@ exports.sessionAgents = void 0;
 exports.createServer = createServer;
 exports.startDaemon = startDaemon;
 exports.stopDaemon = stopDaemon;
+exports.stopDaemonAsync = stopDaemonAsync;
 exports.isDaemonRunning = isDaemonRunning;
 exports.isDaemonHealthy = isDaemonHealthy;
+exports.probeHealth = probeHealth;
+exports.writePidFile = writePidFile;
 exports.cleanupStaleDaemon = cleanupStaleDaemon;
 exports.startDaemonBackground = startDaemonBackground;
 const http_1 = require("http");
@@ -123,9 +126,9 @@ function createServer(manifest, metrics) {
     const server = (0, http_1.createServer)(async (req, res) => {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
-        // Public health endpoint — minimal, no auth
+        // Public health endpoint — includes PID for orphan recovery
         if (method === 'GET' && url === '/health') {
-            sendJson(res, 200, { status: 'ok' });
+            sendJson(res, 200, { status: 'ok', pid: process.pid });
             return;
         }
         // Detailed health endpoint — authenticated if authToken configured
@@ -310,10 +313,23 @@ function startDaemon(manifest, metrics, options) {
     return new Promise((resolve, reject) => {
         const ctx = createServer(manifest, metrics);
         const port = manifest.settings?.port ?? constants_js_1.DEFAULT_PORT;
-        ctx.server.on('error', (err) => {
+        ctx.server.on('error', async (err) => {
             if (err.code === 'EADDRINUSE') {
-                log(`Port ${port} already in use`);
-                reject(new Error(`Port ${port} is already in use. Is another clooks instance running?`));
+                log(`Port ${port} already in use — attempting orphan recovery`);
+                // Try to recover: if a clooks daemon is already on this port, re-adopt it
+                try {
+                    const health = await probeHealth(port);
+                    if (health && health.pid) {
+                        writePidFile(health.pid);
+                        log(`Re-adopted orphaned daemon (pid ${health.pid})`);
+                        resolve(ctx);
+                        return;
+                    }
+                }
+                catch {
+                    // Probe failed — port is in use by something else
+                }
+                reject(new Error(`Port ${port} is already in use. Run 'clooks stop' to stop the existing daemon, or 'clooks status' to check.`));
             }
             else {
                 log(`Server error: ${err.message}`);
@@ -425,15 +441,21 @@ function startDaemon(manifest, metrics, options) {
 }
 /**
  * Stop a running daemon by reading PID file and sending SIGTERM.
+ * If no PID file exists, tries to recover PID from the health endpoint.
  */
 function stopDaemon() {
-    if (!(0, fs_1.existsSync)(constants_js_1.PID_FILE)) {
-        return false;
+    let pid = null;
+    if ((0, fs_1.existsSync)(constants_js_1.PID_FILE)) {
+        const pidStr = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+        pid = parseInt(pidStr, 10);
+        if (isNaN(pid)) {
+            (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+            pid = null;
+        }
     }
-    const pidStr = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
-    const pid = parseInt(pidStr, 10);
-    if (isNaN(pid)) {
-        (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+    // If no PID from file, try synchronous recovery via health endpoint
+    // We can't await here (sync function), so use stopDaemonAsync for full recovery
+    if (pid === null) {
         return false;
     }
     try {
@@ -462,6 +484,57 @@ function stopDaemon() {
     }, 2000);
     return true;
 }
+/**
+ * Async version of stopDaemon that can recover orphaned daemons via /health.
+ * Returns { stopped: boolean, pid?: number, recovered?: boolean }.
+ */
+async function stopDaemonAsync() {
+    let pid = null;
+    if ((0, fs_1.existsSync)(constants_js_1.PID_FILE)) {
+        const pidStr = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
+        pid = parseInt(pidStr, 10);
+        if (isNaN(pid)) {
+            (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+            pid = null;
+        }
+    }
+    // No PID file — try health endpoint recovery
+    if (pid === null) {
+        const health = await probeHealth();
+        if (health && health.pid) {
+            pid = health.pid;
+            log(`Recovered orphaned daemon PID ${pid} from /health for stop`);
+        }
+    }
+    if (pid === null) {
+        return { stopped: false };
+    }
+    const recovered = !(0, fs_1.existsSync)(constants_js_1.PID_FILE);
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        try {
+            if ((0, fs_1.existsSync)(constants_js_1.PID_FILE))
+                (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+        }
+        catch {
+            // ignore
+        }
+        return { stopped: false };
+    }
+    // Clean up PID file after a moment
+    setTimeout(() => {
+        try {
+            if ((0, fs_1.existsSync)(constants_js_1.PID_FILE))
+                (0, fs_1.unlinkSync)(constants_js_1.PID_FILE);
+        }
+        catch {
+            // ignore
+        }
+    }, 2000);
+    return { stopped: true, pid, recovered };
+}
 /**
  * Check if daemon is currently running (PID check only).
  * Use for stop/status where a quick check is fine.
@@ -521,6 +594,42 @@ async function isDaemonHealthy() {
         return false;
     }
 }
+/**
+ * Probe the health endpoint on the daemon port.
+ * Returns the parsed health response (including pid) or null if unreachable.
+ */
+async function probeHealth(port) {
+    const p = port ?? constants_js_1.DEFAULT_PORT;
+    try {
+        const { get } = await import('http');
+        const data = await new Promise((resolve, reject) => {
+            const req = get(`http://127.0.0.1:${p}/health`, (res) => {
+                let body = '';
+                res.on('data', (chunk) => { body += chunk.toString(); });
+                res.on('end', () => resolve(body));
+            });
+            req.on('error', reject);
+            req.setTimeout(2000, () => { req.destroy(); reject(new Error('timeout')); });
+        });
+        const health = JSON.parse(data);
+        if (health.status === 'ok' && typeof health.pid === 'number') {
+            return health;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a PID to the daemon PID file, creating the config dir if needed.
+ */
+function writePidFile(pid) {
+    if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
+        (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(constants_js_1.PID_FILE, String(pid), 'utf-8');
+}
 /**
  * Clean up a stale daemon: remove PID file and attempt to kill the process.
  * Returns the stale PID for logging purposes.

package/docs/_sidebar.md

@@ -0,0 +1,32 @@
+- **Getting Started**
+  - [Installation](getting-started/installation.md)
+  - [Quickstart](getting-started/quickstart.md)
+  - [Migration](getting-started/migration.md)
+
+- **Guides**
+  - [Manifest](guides/manifest.md)
+  - [Handlers](guides/handlers.md)
+  - [LLM Handlers](guides/llm-handlers.md)
+  - [Filtering](guides/filtering.md)
+  - [Dependencies](guides/dependencies.md)
+  - [Async Handlers](guides/async-handlers.md)
+  - [Short-Circuit](guides/short-circuit.md)
+  - [System Service](guides/system-service.md)
+
+- **Plugins**
+  - [Using Plugins](plugins/using-plugins.md)
+  - [Creating Plugins](plugins/creating-plugins.md)
+  - [CC Plugin Import](plugins/cc-plugin-import.md)
+
+- **Reference**
+  - [CLI](reference/cli.md)
+  - [Hook Events](reference/hook-events.md)
+  - [HTTP API](reference/http-api.md)
+  - [Config Files](reference/config-files.md)
+  - [Types](reference/types.md)
+
+- **Operations**
+  - [Monitoring](operations/monitoring.md)
+  - [Security](operations/security.md)
+  - [Troubleshooting](operations/troubleshooting.md)
+  - [Architecture](operations/architecture.md)

package/docs/getting-started/installation.md

@@ -0,0 +1,52 @@
+# Installation
+
+## Prerequisites
+
+- **Node.js 18+** -- check with `node --version`
+- **Claude Code** -- installed and working (`claude --version`)
+
+## Install
+
+```bash
+npm install -g @mauribadnights/clooks
+```
+
+## Initialize
+
+```bash
+clooks init
+```
+
+This creates your configuration directory and everything clooks needs to run. No existing hooks are modified -- use `clooks migrate` for that (see [Migration](migration.md)).
+
+## Verify
+
+```bash
+clooks doctor
+```
+
+Doctor runs health checks on the daemon, port, manifest, settings, and handler state. A passing report means clooks is ready.
+
+## What `clooks init` creates
+
+| Item | Path | Description |
+|------|------|-------------|
+| Manifest | `~/.clooks/manifest.yaml` | Handler definitions, settings, and prefetch config |
+| Hooks directory | `~/.clooks/hooks/` | Built-in hook scripts |
+| Auth token | Stored in manifest | Generated once and shown at init. Used to authenticate requests to the daemon. |
+| System service | launchd (macOS) / systemd (Linux) | Auto-starts the daemon on login, restarts on crash |
+| Expert agent | `~/.claude/agents/clooks.md` | Invoke with `claude --agent clooks` for clooks-specific help |
+
+> **Note:** The auth token is displayed once during init. It is stored in your manifest under `settings.authToken`. If you lose it, run `clooks rotate-token` to generate a new one.
+
+## Next steps
+
+Start the daemon and add your first handler:
+
+```bash
+clooks start
+```
+
+---
+
+[Home](../index.md) | Next: [Quickstart](quickstart.md)

package/docs/getting-started/migration.md

@@ -0,0 +1,68 @@
+# Migration
+
+Migrate existing Claude Code command hooks to clooks in one command.
+
+## What migration does
+
+`clooks migrate` converts your `settings.json` command hooks into clooks HTTP hooks backed by the daemon, with equivalent handlers defined in the manifest. Your original command hooks continue to work -- they just route through clooks instead of spawning processes directly.
+
+## Run the migration
+
+```bash
+clooks migrate
+```
+
+## Step-by-step breakdown
+
+When you run `clooks migrate`, the following happens in order:
+
+1. **Reads settings** -- Loads `~/.claude/settings.json` (or `settings.local.json` if present).
+2. **Backs up original** -- Saves a copy to `~/.clooks/settings.backup.json`.
+3. **Extracts command hooks** -- Parses all command hooks from the settings file and creates corresponding handlers in `~/.clooks/manifest.yaml`.
+4. **Rewrites settings** -- Replaces command hooks with HTTP hooks pointing to `http://localhost:7890`.
+5. **Adds ensure-running** -- Injects a `clooks ensure-running` command into `SessionStart` so the daemon auto-starts when Claude Code launches.
+6. **Imports plugin hooks** -- Detects and imports any Claude Code plugin hooks into the manifest.
+7. **Installs system service** -- Sets up launchd (macOS) or systemd (Linux) for auto-start on login and crash recovery.
+
+## Verify
+
+```bash
+clooks doctor
+```
+
+A passing report confirms that the daemon is running, the manifest is valid, and `settings.json` points to clooks.
+
+## Rollback
+
+If anything goes wrong, restore your original settings:
+
+```bash
+clooks restore
+```
+
+This replaces `settings.json` with the backup created during migration. Your command hooks return to their original state.
+
+## Keeping settings in sync
+
+After migration, if you add new handlers to the manifest, run:
+
+```bash
+clooks sync
+```
+
+This updates `settings.json` to include HTTP hook entries for any new events in your manifest. You do not need to edit `settings.json` manually.
+
+> **Note:** `clooks sync` only adds missing entries. It never removes or modifies existing hooks in `settings.json`.
+
+## Summary
+
+| Command | What it does |
+|---------|-------------|
+| `clooks migrate` | Full migration: backup, convert, rewrite, install service |
+| `clooks restore` | Rollback to pre-migration settings.json |
+| `clooks sync` | Add missing HTTP hook entries for new manifest events |
+| `clooks doctor` | Verify everything is wired up correctly |
+
+---
+
+[Home](../index.md) | Prev: [Quickstart](quickstart.md) | Next: [Manifest Guide](../guides/manifest.md)

package/docs/getting-started/quickstart.md

@@ -0,0 +1,76 @@
+# Quickstart
+
+Get your first clooks handler running in 5 minutes.
+
+## 1. Install
+
+```bash
+npm install -g @mauribadnights/clooks
+```
+
+## 2. Initialize
+
+```bash
+clooks init
+```
+
+## 3. Start the daemon
+
+```bash
+clooks start
+```
+
+## 4. Check status
+
+```bash
+clooks status
+```
+
+You should see the daemon running on port 7890 with zero handlers loaded.
+
+## 5. Add a handler
+
+Open `~/.clooks/manifest.yaml` in your editor and add a handler under `PreToolUse`:
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: bash-logger
+      type: script
+      command: "echo '{\"additionalContext\": \"Reviewed by clooks\"}'"
+      filter: "Bash"
+```
+
+This handler fires before every Bash tool call and injects a note into Claude's context.
+
+## 6. Hot-reload
+
+Save the file. The daemon watches `manifest.yaml` and hot-reloads on change -- no restart needed.
+
+You can confirm the reload in the daemon log:
+
+```bash
+tail -1 ~/.clooks/daemon.log
+```
+
+## 7. Try it
+
+Open Claude Code and run any Bash command. The handler fires automatically. You will see "Reviewed by clooks" appear in the context.
+
+## 8. Check metrics
+
+```bash
+clooks stats
+```
+
+This launches an interactive TUI showing execution counts, latency, and errors per event. Use `-t` for plain text output.
+
+## What to try next
+
+- Add a `filter` to scope handlers to specific tools
+- Try an `llm` handler for AI-powered review
+- Run `clooks migrate` to convert existing command hooks
+
+---
+
+[Home](../index.md) | Prev: [Installation](installation.md) | Next: [Migration](migration.md)