@mauribadnights/clooks 0.5.3 → 0.6.1

package/README.md

@@ -101,7 +101,7 @@ handlers:
       timeout: 3000
       enabled: true
 
-    # LLM handler -- calls Anthropic Messages API
+    # LLM handler -- calls Anthropic Messages API (default backend)
     - id: code-review
       type: llm
       model: claude-haiku-4-5
@@ -119,6 +119,14 @@ handlers:
       batchGroup: analysis
       agent: "builder"                  # only fire in builder agent sessions
 
+    # LLM handler -- spawns Claude Code CLI with an agent
+    - id: agent-review
+      type: llm
+      backend: claude-code              # spawn claude CLI instead of API call
+      llmAgent: security-reviewer       # --agent flag
+      prompt: "Audit this change: $TOOL_NAME $ARGUMENTS"
+      filter: "Bash|Write"
+
   UserPromptSubmit:
     # Inline handler -- imports a JS module in-process (no subprocess)
     - id: prompt-logger
@@ -152,7 +160,7 @@ settings:
 
 **inline** -- imports a JS module and calls its default export. No subprocess overhead.
 
-**llm** -- calls Anthropic Messages API with `$VARIABLE` interpolation. Supports batching and cost tracking.
+**llm** -- AI-powered analysis with `$VARIABLE` interpolation. Two backends: `api` (default, Anthropic API with batching and cost tracking) and `claude-code` (CLI spawn with agent support).
 
 ## Handler Fields Reference
 
@@ -162,15 +170,17 @@ settings:
 | `type` | string | required | all | `script`, `inline`, or `llm` |
 | `command` | string | required | script | Shell command to execute |
 | `module` | string | required | inline | Path to JS module with default export |
-| `model` | string | required | llm | `claude-haiku-4-5`, `claude-sonnet-4-6`, or `claude-opus-4-6` |
+| `model` | string | required | llm | `claude-haiku-4-5`, `claude-sonnet-4-6`, or `claude-opus-4-6`. Required for `api` backend, optional for `claude-code`. |
 | `prompt` | string | required | llm | Prompt template with `$VARIABLE` interpolation |
+| `backend` | string | `api` | llm | `api` (Anthropic API) or `claude-code` (CLI spawn) |
+| `llmAgent` | string | -- | llm | Agent name for `claude-code` backend (`--agent` flag) |
 | `filter` | string | -- | all | Keyword filter (see Filtering) |
 | `project` | string | -- | all | Glob pattern matched against cwd |
 | `agent` | string | -- | all | Only fire when session agent matches |
 | `async` | boolean | `false` | all | Fire-and-forget, don't block response |
 | `depends` | string[] | -- | all | Handler IDs to wait for before executing |
 | `sessionIsolation` | boolean | `false` | all | Reset handler state on SessionStart |
-| `batchGroup` | string | -- | llm | Group ID for batching into one API call |
+| `batchGroup` | string | -- | llm | Group ID for batching into one API call (`api` backend only) |
 | `maxTokens` | number | `1024` | llm | Maximum output tokens |
 | `temperature` | number | `1.0` | llm | Sampling temperature |
 | `timeout` | number | `5000`/`30000` | all | Timeout in ms (5s default, 30s for llm) |
@@ -213,13 +223,17 @@ filter: "word1|!word2"     # run if word1 present AND word2 absent
 
 ## LLM Handlers
 
-**Setup:**
+LLM handlers support two backends: `api` (default, Anthropic Messages API) and `claude-code` (spawns `claude` CLI).
+
+**API backend setup:**
 
 ```bash
-npm install @anthropic-ai/sdk    # peer dependency, required only for llm handlers
+npm install @anthropic-ai/sdk    # peer dependency, required only for api backend
 export ANTHROPIC_API_KEY=sk-...  # or set in manifest: settings.anthropicApiKey
 ```
 
+**Claude Code backend** requires no API key or SDK — just the `claude` CLI installed and authenticated. Supports the `llmAgent` field for running prompts with a specific agent (`--agent`).
+
 **Prompt template variables:**
 
 | Variable | Source | Description |
@@ -234,7 +248,7 @@ export ANTHROPIC_API_KEY=sk-...  # or set in manifest: settings.anthropicApiKey
 
 `$TRANSCRIPT`, `$GIT_STATUS`, and `$GIT_DIFF` require the corresponding key in `prefetch`. The others are always available from the hook input.
 
-**Batching:** Handlers sharing a `batchGroup` on the same event are combined into a single API call. Three Haiku calls become one, saving ~2/3 of input token cost and eliminating two round-trips. Batch groups are scoped per session to prevent cross-session contamination.
+**Batching (API backend only):** Handlers sharing a `batchGroup` on the same event are combined into a single API call. Three Haiku calls become one, saving ~2/3 of input token cost and eliminating two round-trips. Batch groups are scoped per session to prevent cross-session contamination. Claude Code backend handlers always execute individually.
 
 ## Async Handlers
 
@@ -408,7 +422,7 @@ src/
   manifest.ts     Manifest loading and validation
   metrics.ts      Metrics collection and aggregation
   tui.ts          Interactive terminal dashboard (ANSI-based)
-  llm.ts          Anthropic API integration and batching
+  llm.ts          LLM execution (Anthropic API + Claude Code CLI) and batching
   filter.ts       Keyword filter engine
   prefetch.ts     Pre-fetch context (transcript, git status/diff)
   plugin.ts       Plugin install/remove/list

package/agents/clooks.md

@@ -33,7 +33,7 @@ You can run clooks CLI commands:
 ### Handler types
 - **script** — spawns `sh -c "command"`, pipes hook JSON to stdin, reads stdout (~5-35ms)
 - **inline** — imports a JS module, calls default export in-process (~0ms after first load)
-- **llm** — calls Anthropic Messages API with prompt template and $VARIABLE interpolation
+- **llm** — AI-powered analysis with prompt template and $VARIABLE interpolation. Two backends: `api` (Anthropic API, default) and `claude-code` (spawns `claude` CLI)
 
 ### Handler fields
 Every handler has:
@@ -49,9 +49,11 @@ Every handler has:
 - `enabled` — boolean
 
 ### LLM handler extra fields
-- `model` — claude-haiku-4-5, claude-sonnet-4-6, or claude-opus-4-6
+- `model` — claude-haiku-4-5, claude-sonnet-4-6, or claude-opus-4-6 (required for `api` backend, optional for `claude-code`)
 - `prompt` — template with $TRANSCRIPT, $GIT_STATUS, $GIT_DIFF, $ARGUMENTS, $TOOL_NAME, $PROMPT, $CWD
-- `batchGroup` — handlers with same group + same session = one API call
+- `backend` — `api` (default, Anthropic API) or `claude-code` (spawns `claude -p`)
+- `llmAgent` — agent name for `claude-code` backend (passes `--agent` to CLI)
+- `batchGroup` — handlers with same group + same session = one API call (`api` backend only)
 - `maxTokens`, `temperature`
 
 ### Plugin system
@@ -82,6 +84,13 @@ handlers:
       batchGroup: analysis
       async: true
 
+    - id: agent-review
+      type: llm
+      backend: claude-code
+      llmAgent: reviewer
+      prompt: "Review this prompt for clarity: $PROMPT"
+      async: true
+
   Stop:
     - id: session-logger
       type: inline
@@ -134,7 +143,8 @@ SessionStart includes a command hook for `clooks ensure-running` that auto-start
 - Mark non-blocking handlers as `async: true`
 - Use `filter` to skip irrelevant invocations
 - Use `project`/`agent` to scope handlers to relevant contexts
-- Batch LLM handlers with `batchGroup`
+- Batch `api` backend LLM handlers with `batchGroup`
+- Use `claude-code` backend when agent capabilities are needed or to avoid API key management
 - Use `prefetch` to avoid redundant file reads
 
 ### Writing new handlers

package/dist/llm.d.ts

@@ -6,7 +6,7 @@ export declare function resetClient(): void;
  */
 export declare function calculateCost(model: string, usage: TokenUsage): number;
 /**
- * Execute a single LLM handler: render prompt, call Messages API, return result.
+ * Execute a single LLM handler, dispatching to the appropriate backend.
  */
 export declare function executeLLMHandler(handler: LLMHandlerConfig, input: HookInput, context: PrefetchContext): Promise<HandlerResult>;
 /**

package/dist/llm.js

@@ -1,10 +1,11 @@
 "use strict";
-// clooks LLM handler execution — Anthropic Messages API with batching
+// clooks LLM handler execution — Anthropic Messages API with batching, Claude Code CLI spawn
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetClient = resetClient;
 exports.calculateCost = calculateCost;
 exports.executeLLMHandler = executeLLMHandler;
 exports.executeLLMHandlersBatched = executeLLMHandlersBatched;
+const child_process_1 = require("child_process");
 const prefetch_js_1 = require("./prefetch.js");
 const constants_js_1 = require("./constants.js");
 /** Lazy-loaded Anthropic SDK client */
@@ -44,17 +45,27 @@ function calculateCost(model, usage) {
     return inputCost + outputCost;
 }
 /**
- * Execute a single LLM handler: render prompt, call Messages API, return result.
+ * Execute a single LLM handler, dispatching to the appropriate backend.
  */
 async function executeLLMHandler(handler, input, context) {
+    if (handler.backend === 'claude-code') {
+        return executeClaudeCodeHandler(handler, input, context);
+    }
+    return executeAPIHandler(handler, input, context);
+}
+/**
+ * Execute via Anthropic Messages API.
+ */
+async function executeAPIHandler(handler, input, context) {
     const start = performance.now();
     const timeout = handler.timeout ?? constants_js_1.DEFAULT_LLM_TIMEOUT;
     const maxTokens = handler.maxTokens ?? constants_js_1.DEFAULT_LLM_MAX_TOKENS;
     try {
         const client = await getClient();
         const prompt = (0, prefetch_js_1.renderPromptTemplate)(handler.prompt, input, context);
+        const model = handler.model; // Guaranteed by manifest validation for api backend
         const apiCall = client.messages.create({
-            model: handler.model,
+            model,
             max_tokens: maxTokens,
             messages: [{ role: 'user', content: prompt }],
         });
@@ -65,7 +76,7 @@ async function executeLLMHandler(handler, input, context) {
             input_tokens: response.usage?.input_tokens ?? 0,
             output_tokens: response.usage?.output_tokens ?? 0,
         };
-        const cost_usd = calculateCost(handler.model, usage);
+        const cost_usd = calculateCost(model, usage);
         return {
             id: handler.id,
             ok: true,
@@ -84,6 +95,72 @@ async function executeLLMHandler(handler, input, context) {
         };
     }
 }
+/**
+ * Execute via Claude Code CLI spawn (`claude -p "prompt"`).
+ * Supports --agent and --model flags.
+ */
+function executeClaudeCodeHandler(handler, input, context) {
+    const start = performance.now();
+    const timeout = handler.timeout ?? constants_js_1.DEFAULT_LLM_TIMEOUT;
+    const prompt = (0, prefetch_js_1.renderPromptTemplate)(handler.prompt, input, context);
+    const args = ['-p', prompt, '--output-format', 'text'];
+    if (handler.llmAgent) {
+        args.push('--agent', handler.llmAgent);
+    }
+    if (handler.model) {
+        args.push('--model', handler.model);
+    }
+    if (handler.maxTokens) {
+        args.push('--max-tokens', String(handler.maxTokens));
+    }
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)('claude', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout,
+            env: { ...process.env },
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.stdin.end();
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+        }, timeout);
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            const duration_ms = performance.now() - start;
+            if (code !== 0) {
+                resolve({
+                    id: handler.id,
+                    ok: false,
+                    error: `claude exit code ${code}${stderr ? ': ' + stderr.trim() : ''}`,
+                    duration_ms,
+                });
+                return;
+            }
+            resolve({
+                id: handler.id,
+                ok: true,
+                output: { additionalContext: stdout.trim() },
+                duration_ms,
+            });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({
+                id: handler.id,
+                ok: false,
+                error: `Claude Code spawn error: ${err.message}`,
+                duration_ms: performance.now() - start,
+            });
+        });
+    });
+}
 /**
  * Execute a batched group of LLM handlers: combine prompts into a single
  * multi-task API call, parse JSON response back into individual results.
@@ -91,7 +168,7 @@ async function executeLLMHandler(handler, input, context) {
 async function executeBatchGroup(handlers, input, context) {
     const start = performance.now();
     // Use model from first handler; warn if others differ
-    const model = handlers[0].model;
+    const model = handlers[0].model; // Guaranteed by manifest validation — batching only applies to api backend
     for (let i = 1; i < handlers.length; i++) {
         if (handlers[i].model !== model) {
             console.warn(`[clooks] Batch group "${handlers[0].batchGroup}": handler "${handlers[i].id}" ` +
@@ -192,10 +269,14 @@ function splitUsage(total, count) {
  */
 async function executeLLMHandlersBatched(handlers, input, context, sessionId) {
     // Group by batchGroup, scoped by sessionId to prevent cross-session batching
+    // claude-code handlers can't be batched — always run individually
     const grouped = new Map();
     const ungrouped = [];
     for (const handler of handlers) {
-        if (handler.batchGroup) {
+        if (handler.backend === 'claude-code') {
+            ungrouped.push(handler);
+        }
+        else if (handler.batchGroup) {
             // Scope the batch key by sessionId so different sessions never batch together
             const batchKey = sessionId
                 ? `${handler.batchGroup}:${sessionId}`

package/dist/manifest.js

@@ -63,15 +63,38 @@ function validateManifest(manifest) {
             }
             if (handler.type === 'llm') {
                 const llm = handler;
-                if (!llm.model) {
-                    throw new Error(`LLM handler "${handler.id}" must have a "model" field`);
-                }
                 if (!llm.prompt) {
                     throw new Error(`LLM handler "${handler.id}" must have a "prompt" field`);
                 }
-                const validModels = ['claude-haiku-4-5', 'claude-sonnet-4-6', 'claude-opus-4-6'];
-                if (!validModels.includes(llm.model)) {
-                    throw new Error(`LLM handler "${handler.id}" model must be one of: ${validModels.join(', ')}`);
+                // Validate backend
+                const validBackends = ['api', 'claude-code'];
+                if (llm.backend && !validBackends.includes(llm.backend)) {
+                    throw new Error(`LLM handler "${handler.id}" backend must be one of: ${validBackends.join(', ')}`);
+                }
+                // llmAgent is only valid with claude-code backend
+                if (llm.llmAgent && llm.backend !== 'claude-code') {
+                    throw new Error(`LLM handler "${handler.id}" llmAgent requires backend: claude-code`);
+                }
+                // model is required for api backend, optional for claude-code
+                if (llm.backend !== 'claude-code') {
+                    if (!llm.model) {
+                        throw new Error(`LLM handler "${handler.id}" must have a "model" field`);
+                    }
+                    const validModels = ['claude-haiku-4-5', 'claude-sonnet-4-6', 'claude-opus-4-6'];
+                    if (!validModels.includes(llm.model)) {
+                        throw new Error(`LLM handler "${handler.id}" model must be one of: ${validModels.join(', ')}`);
+                    }
+                }
+                else if (llm.model) {
+                    // claude-code backend with explicit model — still validate it
+                    const validModels = ['claude-haiku-4-5', 'claude-sonnet-4-6', 'claude-opus-4-6'];
+                    if (!validModels.includes(llm.model)) {
+                        throw new Error(`LLM handler "${handler.id}" model must be one of: ${validModels.join(', ')}`);
+                    }
+                }
+                // batchGroup is incompatible with claude-code backend
+                if (llm.batchGroup && llm.backend === 'claude-code') {
+                    console.warn(`[clooks] Warning: LLM handler "${handler.id}" has batchGroup but uses claude-code backend — batching will be ignored`);
                 }
             }
             // Validate async field type

package/dist/server.js

@@ -91,11 +91,15 @@ function readBody(req) {
 }
 function sendJson(res, status, data) {
     const body = JSON.stringify(data);
-    res.writeHead(status, {
-        'Content-Type': 'application/json',
-        'Content-Length': Buffer.byteLength(body),
-    });
-    res.end(body);
+    res.socket?.on('error', () => { }); // suppress EPIPE if client disconnected early
+    try {
+        res.writeHead(status, {
+            'Content-Type': 'application/json',
+            'Content-Length': Buffer.byteLength(body),
+        });
+        res.end(body);
+    }
+    catch (_) { }
 }
 /**
  * Create the HTTP server for hook handling.

package/dist/types.d.ts

@@ -17,14 +17,18 @@ export interface HookInput {
 }
 /** Supported LLM models */
 export type LLMModel = 'claude-haiku-4-5' | 'claude-sonnet-4-6' | 'claude-opus-4-6';
+/** LLM execution backend */
+export type LLMBackend = 'api' | 'claude-code';
 /** Handler types — extended with 'llm' */
 export type HandlerType = 'script' | 'inline' | 'llm';
 /** LLM-specific handler config fields */
 export interface LLMHandlerConfig {
     id: string;
     type: 'llm';
-    model: LLMModel;
+    model?: LLMModel;
     prompt: string;
+    backend?: LLMBackend;
+    llmAgent?: string;
     batchGroup?: string;
     maxTokens?: number;
     temperature?: number;

package/docs/getting-started/quickstart.md

@@ -68,7 +68,7 @@ This launches an interactive TUI showing execution counts, latency, and errors p
 ## What to try next
 
 - Add a `filter` to scope handlers to specific tools
-- Try an `llm` handler for AI-powered review
+- Try an `llm` handler for AI-powered review (use `backend: claude-code` to skip API key setup)
 - Run `clooks migrate` to convert existing command hooks
 
 ---

package/docs/guides/handlers.md

@@ -119,28 +119,31 @@ export default async function(input: HookInput) {
 
 ## LLM Handlers
 
-LLM handlers call the Anthropic Messages API with prompt templates. They require no scripts -- the prompt is defined directly in the manifest.
+LLM handlers run AI-powered analysis with prompt templates. They support two backends: the Anthropic Messages API (`api`, default) and Claude Code CLI spawn (`claude-code`).
 
 ### How They Work
 
 1. The handler's `prompt` template is rendered by replacing `$VARIABLES` with actual values.
-2. The rendered prompt is sent to the Anthropic API using the specified `model`.
-3. The response text is returned as `{"additionalContext": "..."}`.
+2. **API backend:** The rendered prompt is sent to the Anthropic API using the specified `model`.
+3. **Claude Code backend:** The rendered prompt is passed to `claude -p`, optionally with `--agent` and `--model`.
+4. The response text is returned as `{"additionalContext": "..."}`.
 
 ### Required Fields
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `model` | string | `claude-haiku-4-5`, `claude-sonnet-4-6`, or `claude-opus-4-6` |
 | `prompt` | string | Prompt template with `$VARIABLE` interpolation |
+| `model` | string | `claude-haiku-4-5`, `claude-sonnet-4-6`, or `claude-opus-4-6`. Required for `api` backend, optional for `claude-code`. |
 
 ### Optional Fields
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `maxTokens` | number | 1024 | Maximum tokens in the API response |
+| `backend` | string | `api` | `api` (Anthropic API) or `claude-code` (CLI spawn) |
+| `llmAgent` | string | — | Agent name for `claude-code` backend (`--agent` flag) |
+| `maxTokens` | number | 1024 | Maximum tokens in the response |
 | `temperature` | number | 1.0 | Sampling temperature |
-| `batchGroup` | string | — | Group ID for batching multiple handlers into one API call |
+| `batchGroup` | string | — | Group ID for batching into one API call (`api` backend only) |
 
 ### Default Timeout
 
@@ -166,6 +169,7 @@ prefetch:
 
 handlers:
   PreToolUse:
+    # API backend (default) — fast, supports batching and cost tracking
     - id: code-reviewer
       type: llm
       model: claude-haiku-4-5
@@ -178,9 +182,17 @@ handlers:
         If there is a problem, explain it briefly. Otherwise say "Looks good."
       filter: "Write|Edit"
       maxTokens: 256
+
+    # Claude Code backend — supports agents, no API key needed
+    - id: agent-review
+      type: llm
+      backend: claude-code
+      llmAgent: security-reviewer
+      prompt: "Audit this tool call for security issues: $TOOL_NAME $ARGUMENTS"
+      filter: "Bash|Write"
 ```
 
-See [LLM Handlers](llm-handlers.md) for batching, cost tracking, and advanced usage.
+See [LLM Handlers](llm-handlers.md) for backends, batching, cost tracking, and advanced usage.
 
 ## Handler Output Format
 

package/docs/guides/llm-handlers.md

@@ -1,16 +1,57 @@
 # 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).
+LLM handlers run AI-powered analysis from the manifest, with prompt templates, automatic batching, and cost tracking. Two backends are available: the **Anthropic Messages API** (default) and **Claude Code CLI** spawn. This guide covers advanced usage beyond the basics in [Handlers](handlers.md).
 
-## Basics
+## Backends
 
-LLM handlers require an Anthropic API key. Provide it in one of two ways:
+LLM handlers support two execution backends via the `backend` field:
+
+| Backend | Value | Description |
+|---------|-------|-------------|
+| Anthropic API | `api` (default) | Direct API call. Supports batching, cost tracking, token usage. Requires API key and SDK. |
+| Claude Code CLI | `claude-code` | Spawns `claude -p "prompt"`. Supports agents. No API key needed — uses your Claude Code subscription. |
+
+### API Backend (default)
+
+The `api` backend requires 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.
 
+### Claude Code Backend
+
+The `claude-code` backend spawns a `claude` CLI process. It requires the Claude Code CLI to be installed and authenticated. No API key or SDK is needed.
+
+```yaml
+- id: deep-review
+  type: llm
+  backend: claude-code
+  prompt: "Review this tool call: $TOOL_NAME $ARGUMENTS"
+```
+
+Key differences from the API backend:
+
+- **No cost tracking** — usage is billed through your Claude Code subscription, not per-token.
+- **No batching** — each handler spawns its own `claude` process. `batchGroup` is ignored.
+- **Agent support** — use `llmAgent` to run the prompt with a specific agent.
+- **Model is optional** — omit `model` to use Claude Code's default, or specify one to override.
+
+#### Using Agents
+
+The `llmAgent` field passes `--agent <name>` to the Claude Code CLI, running the prompt with a specific agent's instructions and tools:
+
+```yaml
+- id: agent-review
+  type: llm
+  backend: claude-code
+  llmAgent: security-reviewer
+  prompt: "Audit this change for vulnerabilities: $ARGUMENTS"
+```
+
+> **Note:** `llmAgent` is only valid with `backend: claude-code`. Using it with the `api` backend produces a validation error.
+
 ### Supported Models
 
 | Model | Best For |
@@ -19,6 +60,8 @@ The Anthropic SDK is lazy-loaded on the first LLM handler invocation. If the SDK
 | `claude-sonnet-4-6` | Balanced analysis (code review, context synthesis) |
 | `claude-opus-4-6` | Deep reasoning (security audits, architecture review) |
 
+`model` is required for the `api` backend. For `claude-code`, it is optional — when provided, it is passed as `--model` to the CLI.
+
 ## Prompt Templates
 
 Prompts support `$VARIABLE` interpolation. Variables are replaced with actual values before the API call.
@@ -56,9 +99,9 @@ handlers:
         Flag any issues. Be concise.
 ```
 
-## Batching
+## Batching (API Backend Only)
 
-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.
+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. Batching only applies to handlers using the `api` backend — `claude-code` handlers always execute individually.
 
 ### How It Works
 
@@ -128,15 +171,28 @@ Pricing per million tokens (as of March 2026):
 
 For batched calls, the total token cost is split evenly across all handlers in the group.
 
+## Choosing a Backend
+
+| Consideration | `api` | `claude-code` |
+|---------------|-------|---------------|
+| Latency | Lower (direct HTTP) | Higher (process spawn) |
+| Cost model | Per-token (tracked) | Subscription (not tracked) |
+| Batching | Yes | No |
+| Agent support | No | Yes (`llmAgent`) |
+| Requires API key | Yes | No |
+| Requires SDK | Yes | No |
+
+**Use `api`** for high-frequency, latency-sensitive handlers (guards, quick checks). **Use `claude-code`** when you need agent capabilities, don't want to manage API keys, or want handlers to use your subscription.
+
 ## 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).
+**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). Only applies to the `api` backend.
 
 **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.
+**Use filter to avoid unnecessary calls.** An LLM handler without a filter fires on every matching event. Adding `filter: "Write|Edit"` ensures the handler is only invoked when relevant tools are used.
 
 **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.
 

package/docs/guides/manifest.md

@@ -137,7 +137,9 @@ Run `clooks doctor` to validate your manifest structure. The validator enforces:
 - 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`.
+- LLM handlers must have a `prompt` field. The `model` field is required for the `api` backend (default) and optional for `claude-code`. Model must be one of: `claude-haiku-4-5`, `claude-sonnet-4-6`, `claude-opus-4-6`.
+- LLM handler `backend` must be `api` or `claude-code` (if specified).
+- `llmAgent` is only valid when `backend` is `claude-code`.
 - `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`.
@@ -211,6 +213,13 @@ handlers:
       depends: [write-review, style-check]
       filter: "Write"
 
+    - id: agent-audit
+      type: llm
+      backend: claude-code
+      llmAgent: security-reviewer
+      prompt: "Audit this Bash command for security: $ARGUMENTS"
+      filter: "Bash"
+
   PostToolUse:
     - id: metrics-collector
       type: inline

package/docs/index.md

@@ -53,7 +53,7 @@ docs/
 
 - [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
+- [LLM Handlers](guides/llm-handlers.md) -- prompt templates, batching, cost tracking, Claude Code CLI backend
 - [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

package/docs/operations/architecture.md

@@ -38,7 +38,8 @@ clooks daemon (localhost:7890)
     +-- Execute each wave
     |   +-- Script handlers: spawn sh -c, pipe JSON stdin
     |   +-- Inline handlers: dynamic ES module import
-    |   +-- LLM handlers: Anthropic API (batched by group)
+    |   +-- LLM handlers (api): Anthropic API (batched by group)
+    |   +-- LLM handlers (claude-code): spawn claude CLI (with optional --agent)
     |
     +-- Record metrics + costs
     +-- Track deny decisions (short-circuit cache)
@@ -68,9 +69,9 @@ Dependency resolution produces "waves" — groups of handlers that can run in pa
 - **Correct ordering** across waves
 - **Data flow** — outputs from earlier waves are available to later waves
 
-### LLM Batching
+### LLM Batching (API Backend)
 
-Multiple LLM handlers with the same `batchGroup` are combined into a single API call. One prompt with multiple tasks, one response parsed and distributed. This typically halves cost and latency for multi-handler analysis.
+Multiple LLM handlers using the `api` backend with the same `batchGroup` are combined into a single API call. One prompt with multiple tasks, one response parsed and distributed. This typically halves cost and latency for multi-handler analysis. Handlers using the `claude-code` backend always execute individually.
 
 ### Hot Reload
 
@@ -90,7 +91,8 @@ When a PreToolUse handler blocks a tool, PostToolUse is skipped. The denial is c
 - **Main process:** HTTP server, manifest loading, file watching, metric collection
 - **Script handlers:** Spawned as child processes (`sh -c`), piped JSON on stdin/stdout
 - **Inline handlers:** Loaded as ES modules in the main process (no subprocess)
-- **LLM handlers:** Async HTTP calls to Anthropic API from the main process
+- **LLM handlers (api):** Async HTTP calls to Anthropic API from the main process
+- **LLM handlers (claude-code):** Spawned as `claude -p` child processes (with optional `--agent`)
 
 ## Resilience
 

package/docs/operations/monitoring.md

@@ -37,7 +37,7 @@ clooks stats | less      # Auto-detects piped output, switches to text
 
 ## Cost Tracking
 
-LLM handler costs are logged to `~/.clooks/costs.jsonl`, rotated at 1MB.
+LLM handler costs (API backend only) are logged to `~/.clooks/costs.jsonl`, rotated at 1MB. Handlers using the `claude-code` backend do not produce cost entries — usage is billed through the Claude Code subscription.
 
 ```bash
 clooks costs

package/docs/plugins/creating-plugins.md

@@ -71,7 +71,7 @@ Use `$PLUGIN_DIR` in `command` and `module` paths. When the plugin is installed,
 
 - `description` (string) — Shown in `clooks plugins` output
 - `author` (string) — Plugin author
-- `handlers` — Same format as user manifest handlers (all 3 types supported)
+- `handlers` — Same format as user manifest handlers (all 3 types supported, including both `api` and `claude-code` LLM backends)
 - `prefetch` — Keys to pre-fetch (merged with user manifest)
 - `extras` — Freeform metadata:
   - `skills` (string[]) — Skill names the plugin provides

package/docs/reference/config-files.md

@@ -64,7 +64,7 @@ All configuration, state, and data files used by clooks, with their locations, f
 
 ## Cost File Format
 
-`costs.jsonl` tracks LLM-specific cost data, one entry per LLM handler invocation.
+`costs.jsonl` tracks LLM-specific cost data, one entry per LLM handler invocation using the `api` backend. Handlers using the `claude-code` backend do not produce cost entries.
 
 ```json
 {

package/docs/reference/types.md

@@ -90,11 +90,13 @@ interface InlineHandlerConfig extends BaseHandler {
 
 interface LLMHandlerConfig extends BaseHandler {
   type: 'llm';
-  model: LLMModel;
+  model?: LLMModel;         // Required for 'api' backend, optional for 'claude-code'
   prompt: string;
-  batchGroup?: string;
-  maxTokens?: number;      // Default: 1024
-  temperature?: number;    // Default: 1.0
+  backend?: LLMBackend;     // Default: 'api'
+  llmAgent?: string;        // Agent name for 'claude-code' backend (--agent flag)
+  batchGroup?: string;      // 'api' backend only
+  maxTokens?: number;       // Default: 1024
+  temperature?: number;     // Default: 1.0
 }
 
 type HandlerConfig = ScriptHandlerConfig | InlineHandlerConfig | LLMHandlerConfig;
@@ -106,6 +108,15 @@ type HandlerConfig = ScriptHandlerConfig | InlineHandlerConfig | LLMHandlerConfi
 type LLMModel = 'claude-haiku-4-5' | 'claude-sonnet-4-6' | 'claude-opus-4-6';
 ```
 
+### LLMBackend
+
+```typescript
+type LLMBackend = 'api' | 'claude-code';
+```
+
+- `api` — Direct Anthropic Messages API call. Supports batching and cost tracking. Requires `ANTHROPIC_API_KEY` and the `@anthropic-ai/sdk` package.
+- `claude-code` — Spawns `claude -p "prompt"`. Supports `llmAgent` for agent-based execution. No API key or SDK required.
+
 ### HandlerResult
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mauribadnights/clooks",
-  "version": "0.5.3",
+  "version": "0.6.1",
   "description": "Persistent hook runtime for Claude Code — eliminates process spawning overhead and gives you observability",
   "bin": {
     "clooks": "./dist/cli.js"