@mauribadnights/clooks 0.5.1 → 0.5.3

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/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/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)

package/docs/guides/async-handlers.md

@@ -0,0 +1,42 @@
+# Async Handlers
+
+## Overview
+
+Set `async: true` on any handler to execute it without blocking Claude Code's response. The handler runs in the background; its output is NOT included in the hook response.
+
+## Use Cases
+
+- Logging and analytics
+- Session tracking
+- Background notifications
+- Non-critical metric collection
+
+## Configuration
+
+```yaml
+handlers:
+  UserPromptSubmit:
+    - id: prompt-analytics
+      type: inline
+      module: ~/hooks/analytics.js
+      async: true
+```
+
+## Behavior
+
+- Fires immediately, does not await completion
+- Errors are swallowed (logged to `daemon.log` but don't affect response)
+- Results delivered via internal `onAsyncResult` callback
+- Metrics still recorded for async handlers
+
+## Limitations
+
+- Output NOT included in hook response to Claude Code
+- If `depends` is set on an async handler, it is forced synchronous (with warning)
+- Cannot be depended upon by other handlers
+
+> **Note:** Async handlers are ideal for side effects that should never slow down the user experience. If you need the handler's output to influence Claude's behavior, use a synchronous handler instead.
+
+---
+
+[Home](../index.md) | [Prev: Dependencies](dependencies.md) | [Next: Short-Circuit](short-circuit.md)

package/docs/guides/dependencies.md

@@ -0,0 +1,153 @@
+# Dependencies
+
+Handlers can declare dependencies on other handlers using the `depends` field. clooks resolves dependencies into execution "waves" using topological sort (Kahn's algorithm), running independent handlers in parallel while respecting ordering constraints.
+
+## Overview
+
+Without dependencies, all handlers for an event run in parallel. With dependencies, handlers are grouped into sequential waves:
+
+- **Wave 0:** Handlers with no dependencies.
+- **Wave 1:** Handlers whose dependencies are all in wave 0.
+- **Wave N:** Handlers whose dependencies are all in waves 0 through N-1.
+
+Handlers within the same wave run in parallel. Waves execute sequentially.
+
+## How It Works
+
+1. The dependency graph is built from `depends` fields across all eligible handlers for the event.
+2. Handlers are sorted into waves using Kahn's algorithm (BFS topological sort).
+3. Wave 0 executes first. All handlers in wave 0 run in parallel.
+4. When wave 0 completes, wave 1 starts. Its handlers can access outputs from wave 0.
+5. This continues until all waves have executed.
+
+## Example
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: context-loader
+      type: inline
+      module: ~/hooks/context.js
+      # No depends -- Wave 0
+
+    - id: security-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Check security of $TOOL_NAME with args: $ARGUMENTS"
+      # No depends -- Wave 0 (parallel with context-loader)
+
+    - id: deep-review
+      type: llm
+      model: claude-sonnet-4-6
+      prompt: "Perform deep review with full context: $ARGUMENTS"
+      depends: [context-loader, security-check]
+      # Both deps in Wave 0 -- this runs in Wave 1
+```
+
+Execution order:
+
+```
+Wave 0: context-loader + security-check (parallel)
+   |
+   v
+Wave 1: deep-review (after both wave 0 handlers complete)
+```
+
+## Accessing Dependency Outputs
+
+Handlers in wave N receive outputs from all previous waves via the `_handlerOutputs` field injected into their input:
+
+```json
+{
+  "session_id": "...",
+  "cwd": "...",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Write",
+  "_handlerOutputs": {
+    "context-loader": {
+      "additionalContext": "Loaded project context..."
+    },
+    "security-check": {
+      "additionalContext": "No security issues found."
+    }
+  }
+}
+```
+
+For inline handlers, access it directly from the input object:
+
+```javascript
+export default async function(input) {
+  const priorResults = input._handlerOutputs || {};
+  const securityResult = priorResults['security-check'];
+
+  // Use prior results to inform this handler's logic
+  if (securityResult?.additionalContext?.includes('issue')) {
+    return { decision: 'block', reason: 'Security issue detected upstream' };
+  }
+
+  return { additionalContext: 'All clear after deep review.' };
+}
+```
+
+For LLM handlers, dependency outputs are available in the input but not directly interpolable into prompt templates. Use an inline handler as a dependency to prepare context that downstream LLM handlers can consume.
+
+## Cycle Detection
+
+Circular dependencies are detected at execution time. If a cycle exists, clooks throws an error identifying the affected handler IDs:
+
+```
+Error: Dependency cycle detected among handlers: handler-a, handler-b
+```
+
+The daemon logs the error and skips all handlers involved in the cycle. Other handlers in the same event that are not part of the cycle execute normally.
+
+## Cross-Plugin Dependencies
+
+Plugin handlers are namespaced as `pluginName/handlerId`. Dependency references follow these rules:
+
+| Reference Style | Resolves To |
+|-----------------|-------------|
+| `depends: [other-handler]` | Same-plugin handler (auto-namespaced) |
+| `depends: [other-plugin/handler-id]` | Handler from a different plugin |
+| `depends: [user-handler-id]` | Handler defined in the user manifest |
+
+Example with a plugin handler depending on a user-defined handler:
+
+```yaml
+# In clooks-plugin.yaml (plugin: my-plugin)
+handlers:
+  PreToolUse:
+    - id: plugin-review
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Review after context load: $ARGUMENTS"
+      depends: [context-loader]  # References user manifest handler
+```
+
+The fully qualified ID of this handler is `my-plugin/plugin-review`. Other plugins or user handlers can depend on it using that full name.
+
+## Async and Dependencies
+
+Async handlers (`async: true`) that participate in dependency relationships are forced to run synchronously. This applies when:
+
+- An async handler has `depends` referencing other handlers in the same event.
+- Other handlers in the same event list an async handler in their `depends`.
+
+In both cases, clooks logs a warning and runs the handler synchronously:
+
+```
+[clooks] Warning: async handler "my-handler" has dependency relationships, running synchronously
+```
+
+This is because fire-and-forget execution cannot guarantee dependency ordering. If you need a handler to be truly async, remove it from all dependency chains.
+
+## Dependencies and Filtering
+
+Dependencies are resolved after filtering. If a handler's dependency is filtered out (by keyword filter, agent, or project scope), the dependency is treated as satisfied. The dependent handler will not find that dependency's output in `_handlerOutputs`, but it will not be blocked waiting for it.
+
+Only dependencies referencing handlers within the current event's eligible set are considered. References to unknown handler IDs are silently ignored.
+
+---
+
+[Home](../index.md) | [Prev: Filtering](filtering.md) | [Next: Async Handlers](async-handlers.md)

package/docs/guides/filtering.md

@@ -0,0 +1,153 @@
+# Filtering
+
+Handlers can be scoped to fire only under specific conditions. clooks provides three filtering mechanisms: keyword filters, agent scoping, and project scoping. All filters are AND'd together -- a handler only fires if every applicable filter passes.
+
+## Keyword Filters
+
+The `filter` field applies a keyword match against the JSON-stringified hook input. Matching is case-insensitive.
+
+### Syntax
+
+| Pattern | Meaning |
+|---------|---------|
+| `"word1\|word2"` | Match if ANY keyword is found (OR) |
+| `"!word"` | Exclude if keyword is found (NOT) |
+| `"word1\|!word2"` | Match if word1 is present AND word2 is absent |
+
+The filter string is split on `|`. Each term is classified as positive (no prefix) or negative (`!` prefix). The rules are:
+
+1. If ANY negative term is found in the input, the handler is **blocked**.
+2. If there are positive terms, at least ONE must be found for the handler to **fire**.
+3. If there are only negative terms and none matched, the handler **fires**.
+
+### Examples
+
+**Fire only for Bash or Execute tools:**
+
+```yaml
+- id: bash-guard
+  type: script
+  command: "node ~/hooks/guard.js"
+  filter: "Bash|Execute"
+```
+
+**Fire for everything except Read and Glob:**
+
+```yaml
+- id: write-logger
+  type: inline
+  module: ~/hooks/logger.js
+  filter: "!Read|!Glob"
+```
+
+This works because both `Read` and `Glob` are negative terms. The handler fires whenever neither term appears in the input.
+
+**Fire for Write unless "test" appears in the input:**
+
+```yaml
+- id: write-review
+  type: llm
+  model: claude-haiku-4-5
+  prompt: "Review: $ARGUMENTS"
+  filter: "Write|!test"
+```
+
+Here `Write` is a positive term and `test` is negative. The handler fires when the input contains "Write" but does not contain "test".
+
+> **Note:** The filter matches against the entire JSON-stringified hook input, not just the tool name. This means field values, file paths, and argument content are all searchable.
+
+## Agent Scoping
+
+The `agent` field restricts a handler to specific Claude Code agent sessions.
+
+### Syntax
+
+A comma-separated list of agent names (case-insensitive). The handler only fires when the current session's agent matches one of the listed names.
+
+```yaml
+- id: builder-guard
+  type: script
+  command: "node ~/hooks/builder-guard.js"
+  agent: "builder"
+```
+
+```yaml
+- id: multi-agent-hook
+  type: inline
+  module: ~/hooks/shared.js
+  agent: "builder,coo"
+```
+
+### How Agent Detection Works
+
+The agent name is extracted from the `agent_type` field of the `SessionStart` event payload. clooks caches this per `session_id`. Subsequent events in the same session use the cached value.
+
+If `agent` is omitted from a handler, it fires in all sessions regardless of agent type.
+
+## Project Scoping
+
+The `project` field restricts a handler to sessions running in specific directories. It is matched against the `cwd` field of the hook input.
+
+### Matching Rules
+
+- **With wildcards (`*`):** The pattern is split on `*` and each literal segment must appear in the cwd path. Order does not matter.
+- **Without wildcards:** The cwd must start with the pattern (prefix match) or equal it exactly.
+
+### Examples
+
+**Only fire in Driffusion projects:**
+
+```yaml
+- id: driffusion-lint
+  type: script
+  command: "node ~/hooks/driffusion-lint.js"
+  project: "*/Driffusion/*"
+```
+
+This matches any cwd containing `/Driffusion/` anywhere in the path.
+
+**Only fire in a specific directory:**
+
+```yaml
+- id: work-hook
+  type: inline
+  module: ~/hooks/work.js
+  project: "/Users/me/work"
+```
+
+This matches any cwd that starts with `/Users/me/work`.
+
+## Combining Filters
+
+All filters are evaluated in order. A handler fires only if every condition passes:
+
+1. `enabled` is not `false`.
+2. The handler is not auto-disabled (consecutive failures < 3).
+3. `agent` matches the current session agent (if specified).
+4. `project` matches the session cwd (if specified).
+5. `filter` keyword match passes (if specified).
+
+If any condition fails, the handler is skipped. Skipped handlers are recorded in metrics with `filtered: true` and zero execution time.
+
+### Full Example
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: targeted-review
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Review: $ARGUMENTS"
+      filter: "Write|Edit"
+      agent: "builder"
+      project: "*/Driffusion/*"
+```
+
+This handler fires only when:
+- The tool call input contains "Write" or "Edit".
+- The session is running the `builder` agent.
+- The working directory contains `/Driffusion/` in its path.
+
+---
+
+[Home](../index.md) | [Prev: LLM Handlers](llm-handlers.md) | [Next: Dependencies](dependencies.md)