@mauribadnights/clooks 0.5.0 → 0.5.2

package/docs/guides/llm-handlers.md

@@ -0,0 +1,145 @@
+# LLM Handlers
+
+LLM handlers call the Anthropic Messages API directly from the manifest, with prompt templates, automatic batching, and cost tracking. This guide covers advanced usage beyond the basics in [Handlers](handlers.md).
+
+## Basics
+
+LLM handlers require an Anthropic API key. Provide it in one of two ways:
+
+1. **Environment variable:** `ANTHROPIC_API_KEY=sk-ant-...`
+2. **Manifest setting:** `settings.anthropicApiKey: sk-ant-...`
+
+The Anthropic SDK is lazy-loaded on the first LLM handler invocation. If the SDK is not installed, the handler fails with an actionable error message.
+
+### Supported Models
+
+| Model | Best For |
+|-------|----------|
+| `claude-haiku-4-5` | Fast, cheap checks (guards, simple reviews) |
+| `claude-sonnet-4-6` | Balanced analysis (code review, context synthesis) |
+| `claude-opus-4-6` | Deep reasoning (security audits, architecture review) |
+
+## Prompt Templates
+
+Prompts support `$VARIABLE` interpolation. Variables are replaced with actual values before the API call.
+
+| Variable | Requires Prefetch | Source |
+|----------|-------------------|--------|
+| `$TRANSCRIPT` | Yes (`transcript`) | Session transcript, last 50KB |
+| `$GIT_STATUS` | Yes (`git_status`) | `git status --porcelain` output |
+| `$GIT_DIFF` | Yes (`git_diff`) | `git diff --stat` output, max 20KB |
+| `$ARGUMENTS` | No | JSON-serialized `tool_input` (PreToolUse/PostToolUse) |
+| `$TOOL_NAME` | No | Tool name string (PreToolUse/PostToolUse) |
+| `$PROMPT` | No | User prompt text (UserPromptSubmit) |
+| `$CWD` | No | Current working directory |
+
+Variables that require prefetch will resolve to an empty string if the corresponding prefetch key is not listed in the manifest's `prefetch` array.
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+
+handlers:
+  PreToolUse:
+    - id: reviewer
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        You are reviewing a tool call in a Claude Code session.
+
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+        Working directory: $CWD
+        Git status: $GIT_STATUS
+
+        Flag any issues. Be concise.
+```
+
+## Batching
+
+Handlers with the same `batchGroup` value that fire on the same event are combined into a single API call. This reduces latency and cost when multiple LLM handlers need to analyze the same context.
+
+### How It Works
+
+1. Handlers sharing a `batchGroup` are collected.
+2. Their prompts are rendered individually, then combined into a structured multi-task prompt.
+3. A single API call is made. The model is instructed to return a JSON object keyed by handler ID.
+4. The response is parsed and each handler receives its portion of the result.
+5. Token usage and cost are split evenly across group members.
+
+### Scoping
+
+Batch groups are scoped by `session_id`. Two different Claude Code sessions firing the same batch group at the same time will produce separate API calls. There is no cross-session contamination.
+
+### Edge Cases
+
+- **Single-handler groups:** If a batch group contains only one handler, it falls through to individual execution (no batching overhead).
+- **Mixed models:** If handlers in a group specify different models, the first handler's model is used and a warning is logged.
+- **JSON parse failure:** If the batched response is not valid JSON, all handlers in the group receive the raw text as `additionalContext`.
+
+### Example
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: security-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Check this tool call for security issues:
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+      batchGroup: pre-tool-review
+      filter: "Write|Bash"
+
+    - id: style-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Check if this tool call follows project conventions:
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+      batchGroup: pre-tool-review
+      filter: "Write|Bash"
+```
+
+Both handlers fire on the same `PreToolUse` event with the same `batchGroup`. clooks combines them into one API call, halving latency and cost compared to two separate calls.
+
+## Cost Tracking
+
+All LLM handler invocations are logged to `~/.clooks/costs.jsonl`. Each entry records the timestamp, event, handler ID, model, token usage, cost in USD, and whether the call was batched.
+
+View cost data with:
+
+```bash
+clooks costs
+```
+
+### Pricing
+
+Pricing per million tokens (as of March 2026):
+
+| Model | Input | Output |
+|-------|-------|--------|
+| `claude-haiku-4-5` | $0.80 | $4.00 |
+| `claude-sonnet-4-6` | $3.00 | $15.00 |
+| `claude-opus-4-6` | $15.00 | $75.00 |
+
+For batched calls, the total token cost is split evenly across all handlers in the group.
+
+## Best Practices
+
+**Use Haiku for simple checks.** Guards, keyword detection, and light reviews run well on Haiku at a fraction of the cost. Reserve Sonnet and Opus for tasks that require deeper reasoning.
+
+**Use batchGroup to combine related analyses.** If two handlers analyze the same tool call from different angles, batching them saves an API round-trip and reduces total tokens (the shared context is sent once).
+
+**Set maxTokens conservatively.** Most handler responses are short. Setting `maxTokens: 256` or `maxTokens: 512` prevents runaway token usage on verbose responses.
+
+**Use filter to avoid unnecessary API calls.** An LLM handler without a filter fires on every matching event. Adding `filter: "Write|Edit"` ensures the API is only called when relevant tools are invoked.
+
+**Prefer prefetch over inline context.** If your prompt needs git status or the transcript, add the key to `prefetch` rather than running shell commands in a script handler. Prefetched data is fetched once and shared across all handlers.
+
+---
+
+[Home](../index.md) | [Prev: Handlers](handlers.md) | [Next: Filtering](filtering.md)

package/docs/guides/manifest.md

@@ -0,0 +1,237 @@
+# Manifest Reference
+
+The manifest file (`~/.clooks/manifest.yaml`) is the single configuration source for the clooks daemon. It defines which handlers run, when they fire, and how the daemon behaves.
+
+## Structure
+
+A manifest has three top-level sections:
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+  - git_diff
+
+handlers:
+  EventName:
+    - id: handler-id
+      type: script|inline|llm
+      # ...type-specific and shared fields
+
+settings:
+  port: 7890
+  logLevel: info
+  authToken: token
+  anthropicApiKey: sk-...
+```
+
+All sections are optional. A minimal manifest needs only a `handlers` block with at least one event and one handler.
+
+## Settings
+
+Global daemon configuration lives under `settings`:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `port` | number | 7890 | HTTP server port (1-65535) |
+| `logLevel` | string | `"info"` | Log verbosity: `debug`, `info`, `warn`, `error` |
+| `authToken` | string | — | Bearer token for HTTP authentication. Auto-generated by `clooks init` |
+| `anthropicApiKey` | string | — | Anthropic API key. Alternative to setting the `ANTHROPIC_API_KEY` env var |
+
+```yaml
+settings:
+  port: 7890
+  logLevel: info
+  authToken: clooks_a1b2c3d4e5f6
+```
+
+## Prefetch
+
+The `prefetch` array declares context that should be fetched once per hook invocation and shared across all handlers. This avoids redundant work when multiple handlers need the same data.
+
+| Key | Description | Size Limit |
+|-----|-------------|------------|
+| `transcript` | Last portion of the session transcript file | 50KB (tail) |
+| `git_status` | Output of `git status --porcelain` in the session's cwd | — |
+| `git_diff` | Output of `git diff --no-ext-diff --stat` in the session's cwd | 20KB (truncated) |
+
+Prefetched data is available to LLM handler prompts as template variables: `$TRANSCRIPT`, `$GIT_STATUS`, `$GIT_DIFF`. Each key is fetched independently — a failure in one does not block the others.
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+```
+
+## Handler Events
+
+Handlers are grouped by the Claude Code hook event they respond to. clooks supports all 9 events:
+
+| Event | When It Fires |
+|-------|---------------|
+| `SessionStart` | A new Claude Code session begins |
+| `UserPromptSubmit` | The user submits a prompt |
+| `PreToolUse` | Before Claude executes a tool |
+| `PostToolUse` | After a tool finishes executing |
+| `Stop` | Claude finishes its response |
+| `SubagentStart` | A subagent session starts |
+| `SubagentStop` | A subagent session ends |
+| `Notification` | Claude sends a notification |
+| `ConfigChange` | Claude Code configuration changes |
+
+See [Hook Events Reference](../reference/hook-events.md) for full payload documentation per event.
+
+Each event key contains an array of handler definitions:
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: first-handler
+      type: script
+      command: "node ~/hooks/check.js"
+    - id: second-handler
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Review this tool call: $TOOL_NAME"
+```
+
+## Shared Handler Fields
+
+Every handler, regardless of type, supports these fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `id` | string | required | Unique identifier across the entire manifest |
+| `type` | string | required | `script`, `inline`, or `llm` |
+| `enabled` | boolean | `true` | Toggle handler without removing it from the manifest |
+| `filter` | string | — | Keyword filter applied to hook input. See [Filtering](filtering.md) |
+| `timeout` | number | 5000 / 30000 | Milliseconds before handler is killed. Default is 5000ms for script/inline, 30000ms for LLM |
+| `async` | boolean | `false` | Fire-and-forget execution. See [Async Handlers](async-handlers.md) |
+| `depends` | string[] | — | Handler IDs this handler must wait for. See [Dependencies](dependencies.md) |
+| `sessionIsolation` | boolean | `false` | Reset handler state (error counts, auto-disable) on every `SessionStart` |
+| `agent` | string | — | Comma-separated agent names. Only fires in matching sessions. See [Filtering](filtering.md) |
+| `project` | string | — | Glob pattern matched against session cwd. See [Filtering](filtering.md) |
+
+Type-specific fields are covered in [Handlers](handlers.md).
+
+## Hot Reload
+
+The daemon watches `manifest.yaml` for filesystem changes. When the file is saved:
+
+1. The new manifest is parsed and validated.
+2. Handler lists are diffed against the previous version.
+3. State for removed handlers is cleaned up.
+4. Handlers with `sessionIsolation: true` that changed are reset.
+5. The new handler set becomes active immediately.
+
+No daemon restart is needed. Invalid manifests are rejected and the previous configuration continues running. Changes are logged at the `info` level.
+
+## Validation
+
+Run `clooks doctor` to validate your manifest structure. The validator enforces:
+
+- The `handlers` key must be an object.
+- Each event key must be a valid hook event name (`SessionStart`, `PreToolUse`, etc.).
+- Each event must contain an array of handler objects.
+- Every handler must have a string `id` and a valid `type`.
+- Handler IDs must be unique across the entire manifest (not just within an event).
+- Script handlers must have a `command` field.
+- Inline handlers must have a `module` field.
+- LLM handlers must have both `model` and `prompt` fields. Model must be one of: `claude-haiku-4-5`, `claude-sonnet-4-6`, `claude-opus-4-6`.
+- `prefetch` must be an array containing only valid keys: `transcript`, `git_status`, `git_diff`.
+- `settings.port` must be a number between 1 and 65535.
+- `settings.logLevel` must be one of: `debug`, `info`, `warn`, `error`.
+
+Invalid manifests produce specific error messages identifying the problem. For example:
+
+```
+Error: Unknown hook event: "PreTool". Valid events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, Notification, ConfigChange
+```
+
+```
+Error: Duplicate handler id: "my-guard"
+```
+
+## Complete Example
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+  - git_diff
+
+handlers:
+  SessionStart:
+    - id: check-update
+      type: script
+      command: "node ~/.clooks/hooks/check-update.js"
+      timeout: 6000
+
+  UserPromptSubmit:
+    - id: prompt-logger
+      type: inline
+      module: ~/.clooks/hooks/log-prompt.js
+      async: true
+
+  PreToolUse:
+    - id: bash-guard
+      type: script
+      command: "node ~/.clooks/hooks/bash-guard.js"
+      filter: "Bash"
+      timeout: 3000
+
+    - id: write-review
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Review this file write for potential issues:
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+        Git status: $GIT_STATUS
+      filter: "Write"
+      batchGroup: code-review
+
+    - id: style-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Check if this write follows project style conventions:
+        $ARGUMENTS
+      filter: "Write"
+      batchGroup: code-review
+      depends: []
+
+    - id: deep-analysis
+      type: llm
+      model: claude-sonnet-4-6
+      prompt: |
+        Perform deep security and correctness review:
+        $ARGUMENTS
+        Context from prior checks available in input.
+      depends: [write-review, style-check]
+      filter: "Write"
+
+  PostToolUse:
+    - id: metrics-collector
+      type: inline
+      module: ~/.clooks/hooks/metrics.js
+      async: true
+
+  Stop:
+    - id: session-summary
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Summarize what was accomplished in this session:
+        $TRANSCRIPT
+      maxTokens: 512
+
+settings:
+  port: 7890
+  logLevel: info
+  authToken: clooks_a1b2c3d4e5f6
+```
+
+---
+
+[Home](../index.md) | [Prev: Migration](../getting-started/migration.md) | [Next: Handlers](handlers.md)

package/docs/guides/short-circuit.md

@@ -0,0 +1,31 @@
+# Short-Circuit
+
+## Overview
+
+When a PreToolUse handler blocks a tool call (returns `decision: "block"`), clooks automatically skips PostToolUse handlers for that same tool. This prevents wasted execution on tools that were already denied.
+
+## How It Works
+
+1. PreToolUse handler returns `{ decision: "block", reason: "..." }`
+2. Server records denial in an in-memory DenyCache, keyed by `session_id:tool_name`
+3. When PostToolUse fires for the same session + tool, clooks checks the DenyCache
+4. If denied: PostToolUse handlers are skipped entirely
+5. Cache entries expire after 30 seconds (prevents memory leaks)
+
+## Configuration
+
+This is automatic — no configuration needed. It works for all PreToolUse handlers that return a `block` decision.
+
+The server also checks for `hookSpecificOutput.permissionDecision: "deny"` as an alternative denial signal.
+
+## Cache Lifecycle
+
+- Entries auto-expire after 30 seconds
+- Periodic cleanup runs every 60 seconds
+- Cache is in-memory only — cleared on daemon restart
+
+> **Note:** The 30-second TTL is deliberately short. It only needs to survive long enough for the matching PostToolUse event to arrive, which typically happens within milliseconds of the PreToolUse denial.
+
+---
+
+[Home](../index.md) | [Prev: Async Handlers](async-handlers.md) | [Next: System Service](system-service.md)

package/docs/guides/system-service.md

@@ -0,0 +1,62 @@
+# System Service
+
+## Overview
+
+clooks can install itself as a system service that starts automatically on login and restarts on crash. Supports macOS (launchd), Linux (systemd), and Windows (Task Scheduler).
+
+## Install
+
+```bash
+clooks service install
+```
+
+This is also done automatically by `clooks init` and `clooks migrate`.
+
+## Uninstall
+
+```bash
+clooks service uninstall
+```
+
+## Check Status
+
+```bash
+clooks service status    # running | stopped | not-installed
+clooks status            # Full daemon status including service
+```
+
+## Platform Details
+
+### macOS (launchd)
+
+- Plist: `~/Library/LaunchAgents/com.clooks.daemon.plist`
+- Runs `clooks start --foreground`
+- Auto-restarts on crash
+- Survives sleep/wake cycles
+- Commands used: `launchctl load/unload`
+
+### Linux (systemd)
+
+- Service file: `~/.config/systemd/user/clooks.service`
+- User service (no root required)
+- Auto-restarts with 3-second delay
+- Commands: `systemctl --user enable/start/stop`
+
+### Windows (Task Scheduler)
+
+- Task name: `clooks`
+- Created via `schtasks`
+- Triggers on user login
+
+## Daemon Resilience
+
+- PID file at `~/.clooks/daemon.pid` tracks running process
+- `clooks start` detects stale PIDs (e.g., after macOS sleep) and cleans up
+- `/health` endpoint used for orphan recovery when PID file is missing
+- `clooks ensure-running` (called by SessionStart hook) auto-starts if needed
+
+> **Note:** On macOS, launchd handles restart-on-crash natively. The PID staleness check is a secondary safety net for edge cases like hard reboots or force-kills that leave a stale PID file behind.
+
+---
+
+[Home](../index.md) | [Prev: Short-Circuit](short-circuit.md) | [Next: Using Plugins](../plugins/using-plugins.md)

package/docs/index.html

@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>clooks docs</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.min.css">
+  <style>
+    :root {
+      --theme-color: #7c3aed;
+      --sidebar-width: 260px;
+      --sidebar-nav-link-color--active: #7c3aed;
+      --sidebar-nav-link-border-color--active: #7c3aed;
+    }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'clooks',
+      repo: 'https://github.com/mauribadnights/clooks',
+      loadSidebar: true,
+      subMaxLevel: 2,
+      search: {
+        placeholder: 'Search docs...',
+        noData: 'No results',
+        depth: 3
+      },
+      auto2top: true,
+      coverpage: false,
+      homepage: 'index.md'
+    }
+  </script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/docsify-copy-code@2/dist/docsify-copy-code.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-typescript.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+</body>
+</html>

package/docs/index.md

@@ -0,0 +1,96 @@
+# clooks
+
+clooks is a persistent hook runtime for Claude Code that eliminates process spawning overhead -- making hooks 112x faster.
+
+## Why clooks?
+
+- **Performance.** A single long-lived HTTP daemon replaces per-invocation process spawning. Hook latency drops from ~35ms to ~0.3ms.
+- **LLM handlers.** Define AI-powered hooks with prompt templates, variable interpolation, and automatic batching -- no scripts required.
+- **Plugin ecosystem.** Package and share reusable handler sets as plugins. Install with `clooks add`, namespace automatically.
+- **Dependency resolution.** Declare `depends` between handlers. clooks resolves them into topological execution waves -- parallel where possible, sequential where required.
+
+## Quick Navigation
+
+```
+docs/
+├── Getting Started
+│   ├── installation.md
+│   ├── quickstart.md
+│   └── migration.md
+├── Guides
+│   ├── manifest.md
+│   ├── handlers.md
+│   ├── llm-handlers.md
+│   ├── filtering.md
+│   ├── dependencies.md
+│   ├── async-handlers.md
+│   ├── short-circuit.md
+│   └── system-service.md
+├── Plugins
+│   ├── using-plugins.md
+│   ├── creating-plugins.md
+│   └── cc-plugin-import.md
+├── Reference
+│   ├── cli.md
+│   ├── hook-events.md
+│   ├── http-api.md
+│   ├── config-files.md
+│   └── types.md
+└── Operations
+    ├── monitoring.md
+    ├── security.md
+    ├── troubleshooting.md
+    └── architecture.md
+```
+
+### Getting Started
+
+- [Installation](getting-started/installation.md) -- prerequisites, install, and init
+- [Quickstart](getting-started/quickstart.md) -- first handler in 5 minutes
+- [Migration](getting-started/migration.md) -- convert existing command hooks to clooks
+
+### Guides
+
+- [Manifest](guides/manifest.md) -- manifest.yaml structure and fields
+- [Handlers](guides/handlers.md) -- script, inline, and LLM handler types
+- [LLM Handlers](guides/llm-handlers.md) -- prompt templates, batching, cost tracking
+- [Filtering](guides/filtering.md) -- keyword-based handler filtering
+- [Dependencies](guides/dependencies.md) -- topological execution waves
+- [Async Handlers](guides/async-handlers.md) -- fire-and-forget execution
+- [Short-Circuit](guides/short-circuit.md) -- deny caching and PostToolUse skipping
+- [System Service](guides/system-service.md) -- launchd and systemd auto-start
+
+### Plugins
+
+- [Using Plugins](plugins/using-plugins.md) -- install, remove, and list plugins
+- [Creating Plugins](plugins/creating-plugins.md) -- plugin manifest and packaging
+- [CC Plugin Import](plugins/cc-plugin-import.md) -- importing Claude Code plugin hooks
+
+### Reference
+
+- [CLI](reference/cli.md) -- all commands and flags
+- [Hook Events](reference/hook-events.md) -- event types and payloads
+- [HTTP API](reference/http-api.md) -- daemon endpoints
+- [Config Files](reference/config-files.md) -- paths, formats, defaults
+- [Types](reference/types.md) -- TypeScript type definitions
+
+### Operations
+
+- [Monitoring](operations/monitoring.md) -- metrics, costs, and stats TUI
+- [Security](operations/security.md) -- auth tokens and access control
+- [Troubleshooting](operations/troubleshooting.md) -- common issues and clooks doctor
+- [Architecture](operations/architecture.md) -- system design and internals
+
+## Performance
+
+| Metric | Command Hooks | clooks | Improvement |
+|--------|---------------|--------|-------------|
+| Single invocation | ~34.6ms | ~0.31ms | 112x faster |
+| Full session (120 calls) | ~3,986ms | ~23ms | 99% time saved |
+| 5 parallel handlers | ~424ms | ~96ms | 4.4x faster |
+
+> **Note:** Benchmarked on Apple Silicon (M-series), Node v24.4.1. Run `npm run bench` to reproduce.
+
+---
+
+Next: [Installation](getting-started/installation.md)