@mauribadnights/clooks 0.5.1 → 0.5.2

package/docs/plugins/creating-plugins.md

@@ -0,0 +1,144 @@
+# Creating Plugins
+
+## Overview
+
+A clooks plugin is a directory containing a `clooks-plugin.yaml` manifest and any handler scripts/modules it references. Plugins let you distribute reusable hook configurations.
+
+## Plugin Structure
+
+```
+my-plugin/
+├── clooks-plugin.yaml      # Required: plugin manifest
+├── README.md               # Recommended: usage docs
+├── handlers/
+│   ├── guard.js            # Handler scripts
+│   └── analyzer.js
+└── assets/                 # Optional: supporting files
+    └── rules.json
+```
+
+## Plugin Manifest (clooks-plugin.yaml)
+
+```yaml
+name: my-plugin                    # Required: unique name
+version: 1.0.0                    # Required: semver
+description: Security hooks suite  # Optional
+author: Your Name                  # Optional
+
+handlers:
+  PreToolUse:
+    - id: bash-guard
+      type: inline
+      module: $PLUGIN_DIR/handlers/guard.js
+      filter: "Bash|Execute"
+      timeout: 3000
+
+    - id: write-guard
+      type: inline
+      module: $PLUGIN_DIR/handlers/guard.js
+      filter: "Write|Edit"
+
+  PostToolUse:
+    - id: usage-tracker
+      type: script
+      command: "node $PLUGIN_DIR/handlers/tracker.js"
+      async: true
+
+prefetch:
+  - git_status
+
+extras:
+  skills:
+    - security-audit
+    - permission-guard
+  agents:
+    - security-reviewer
+  readme: README.md
+```
+
+## The $PLUGIN_DIR Variable
+
+Use `$PLUGIN_DIR` in `command` and `module` paths. When the plugin is installed, clooks resolves this to the absolute installation path (e.g., `~/.clooks/plugins/my-plugin/`).
+
+> **Note:** Always use `$PLUGIN_DIR` instead of relative paths. Plugins are copied to the plugins directory on install, so relative paths from the source won't work.
+
+## Required Fields
+
+- `name` (string) — Unique plugin identifier. Used as namespace prefix for handler IDs.
+- `version` (string) — Semantic version.
+
+## Optional Fields
+
+- `description` (string) — Shown in `clooks plugins` output
+- `author` (string) — Plugin author
+- `handlers` — Same format as user manifest handlers (all 3 types supported)
+- `prefetch` — Keys to pre-fetch (merged with user manifest)
+- `extras` — Freeform metadata:
+  - `skills` (string[]) — Skill names the plugin provides
+  - `agents` (string[]) — Agent names the plugin registers
+  - `readme` (string) — Relative path to README (resolved to absolute on install)
+  - Any other keys (extensible)
+
+## Handler Namespacing
+
+When installed, handler IDs become `plugin-name/handler-id`:
+
+- Source: `id: bash-guard` → Installed: `my-plugin/bash-guard`
+- Dependencies within the same plugin are auto-namespaced
+- Cross-plugin deps use full namespaced ID: `depends: [other-plugin/handler-id]`
+
+## Writing Inline Handlers for Plugins
+
+```javascript
+// handlers/guard.js
+export default async function(input) {
+  const { tool_name, tool_input } = input;
+
+  if (tool_name === 'Bash' && tool_input?.command?.includes('rm -rf')) {
+    return {
+      decision: 'block',
+      reason: 'Destructive command blocked by security plugin'
+    };
+  }
+
+  return { additionalContext: 'Security check passed' };
+}
+```
+
+## Writing Script Handlers for Plugins
+
+```javascript
+#!/usr/bin/env node
+// handlers/tracker.js
+import { readFileSync } from 'fs';
+
+const input = JSON.parse(readFileSync('/dev/stdin', 'utf8'));
+
+// Do tracking work...
+const result = { additionalContext: `Tracked ${input.hook_event_name}` };
+console.log(JSON.stringify(result));
+```
+
+## Testing Your Plugin
+
+Before publishing:
+
+1. Validate manifest: install locally with `clooks add ./my-plugin`
+2. Check handlers load: `clooks plugins` should show your plugin
+3. Test execution: trigger the relevant hook events
+4. Check metrics: `clooks stats` shows handler execution data
+5. Remove: `clooks remove my-plugin`
+
+## Distribution
+
+Currently plugins are installed from local directories:
+
+```bash
+clooks add /path/to/my-plugin
+```
+
+Share plugins as git repos or tarballs. Users clone/extract and `clooks add` the directory.
+
+---
+
+[Home](../index.md) | [Prev: Using Plugins](using-plugins.md) | [Next: CC Plugin Import](cc-plugin-import.md)

package/docs/plugins/using-plugins.md

@@ -0,0 +1,63 @@
+# Using Plugins
+
+## Overview
+
+clooks plugins are self-contained directories that ship handler definitions in a `clooks-plugin.yaml` file. Install them locally to extend your hook pipeline without editing your manifest.
+
+## Installing a Plugin
+
+```bash
+clooks add ./path/to/plugin-directory
+```
+
+What happens:
+
+1. Validates `clooks-plugin.yaml` in the source directory
+2. Copies the entire directory to `~/.clooks/plugins/{name}/`
+3. Resolves `$PLUGIN_DIR` variables in handler commands to the installed path
+4. Updates plugin registry (`~/.clooks/plugins/installed.json`)
+5. Syncs settings.json with any new HTTP hook entries
+
+## Listing Plugins
+
+```bash
+clooks plugins
+```
+
+Shows: name, version, handler count, skills (if declared), agents (if declared).
+
+## Removing a Plugin
+
+```bash
+clooks remove plugin-name
+```
+
+Removes the plugin directory and registry entry. Daemon hot-reloads to drop the handlers.
+
+## How Plugins Merge
+
+- Plugin handlers are namespaced: `plugin-name/handler-id` (prevents ID collisions)
+- Prefetch keys are merged (union of user + all plugins)
+- Settings come from user manifest only (plugins cannot override port, auth, etc.)
+- Handlers from all plugins + user manifest execute together, respecting dependencies
+
+## Plugin Registry
+
+Installed plugins tracked at `~/.clooks/plugins/installed.json`:
+
+```json
+{
+  "plugins": [
+    {
+      "name": "security-suite",
+      "version": "1.0.0",
+      "path": "/Users/you/.clooks/plugins/security-suite",
+      "installedAt": "2026-03-25T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+[Home](../index.md) | [Prev: System Service](../guides/system-service.md) | [Next: Creating Plugins](creating-plugins.md)

package/docs/reference/cli.md

@@ -0,0 +1,213 @@
+# CLI Reference
+
+clooks provides a single `clooks` command with subcommands for daemon management, configuration, plugins, observability, and system service control.
+
+All commands read configuration from `~/.clooks/manifest.yaml` unless otherwise noted.
+
+---
+
+## Daemon
+
+### `clooks start`
+
+Start the daemon process.
+
+| Flag | Description |
+|------|-------------|
+| `-f, --foreground` | Run in foreground instead of detaching |
+| `--no-watch` | Disable manifest file watching |
+
+```bash
+clooks start           # Background (detached)
+clooks start -f        # Foreground (for debugging)
+clooks start --no-watch  # Background, no manifest hot-reload
+```
+
+> **Note:** When started in background mode, the daemon writes its PID to `~/.clooks/daemon.pid` and logs to `~/.clooks/daemon.log`.
+
+### `clooks stop`
+
+Stop the running daemon. Tries the PID file first, then falls back to the health endpoint for orphan recovery.
+
+```bash
+clooks stop
+```
+
+### `clooks status`
+
+Show daemon status including: running/stopped, PID, port, uptime, handler count, plugin count, and service status.
+
+```bash
+clooks status
+```
+
+### `clooks ensure-running`
+
+Start the daemon if it is not already running. This is a no-op if the daemon is healthy.
+
+Used internally by the SessionStart hook to guarantee the daemon is available before a Claude Code session begins.
+
+```bash
+clooks ensure-running
+```
+
+---
+
+## Configuration
+
+### `clooks init`
+
+Create default configuration. Generates the `~/.clooks/` directory tree, a starter `manifest.yaml`, an auth token, and installs the clooks agent and system service.
+
+```bash
+clooks init
+```
+
+> **Note:** Safe to run multiple times. Existing configuration is not overwritten.
+
+### `clooks migrate`
+
+Migrate existing Claude Code command hooks to clooks HTTP hooks. Backs up `settings.json`, creates manifest entries from existing hooks, and rewrites the hooks to HTTP POST calls.
+
+```bash
+clooks migrate
+```
+
+The original settings are saved to `~/.clooks/settings.backup.json` and can be restored with `clooks restore`.
+
+### `clooks restore`
+
+Restore the original `settings.json` from the backup created during `clooks migrate`.
+
+```bash
+clooks restore
+```
+
+### `clooks sync`
+
+Sync `settings.json` with the manifest. Ensures HTTP hook entries exist in Claude Code settings for every event that has handlers defined in the manifest.
+
+```bash
+clooks sync
+```
+
+### `clooks rotate-token`
+
+Generate a new auth token. Updates both `manifest.yaml` and `settings.json` with the new token.
+
+```bash
+clooks rotate-token
+```
+
+### `clooks update`
+
+Update clooks to the latest npm version. Restarts the daemon automatically if it was running.
+
+```bash
+clooks update
+```
+
+---
+
+## Plugins
+
+### `clooks add <path>`
+
+Install a plugin from a local directory. Validates the plugin manifest, copies files to the plugins directory, and syncs settings.
+
+```bash
+clooks add ./my-plugin
+clooks add ~/plugins/security-suite
+```
+
+### `clooks remove <name>`
+
+Uninstall a plugin by name.
+
+```bash
+clooks remove security-suite
+```
+
+### `clooks plugins`
+
+List installed plugins with name, version, handler count, skills, and agents.
+
+```bash
+clooks plugins
+```
+
+### `clooks import-plugins`
+
+Discover and import hooks from Claude Code plugins located in `~/.claude/plugins/`.
+
+```bash
+clooks import-plugins
+```
+
+---
+
+## Observability
+
+### `clooks stats`
+
+Show hook execution metrics. Displays an interactive TUI by default.
+
+| Flag | Description |
+|------|-------------|
+| `-t, --text` | Plain text output (auto-detected when piped) |
+
+```bash
+clooks stats            # Interactive TUI
+clooks stats -t         # Plain text output
+clooks stats | head     # Auto-selects text mode when piped
+```
+
+### `clooks costs`
+
+Show LLM cost breakdown by model and handler.
+
+```bash
+clooks costs
+```
+
+### `clooks doctor`
+
+Run diagnostic health checks across config, manifest, daemon, port, settings, plugins, service, and agent.
+
+```bash
+clooks doctor
+```
+
+Each check reports `ok`, `warn`, or `error` with a human-readable message.
+
+---
+
+## System Service
+
+### `clooks service install`
+
+Install clooks as a system service using the platform-native mechanism (launchd on macOS, systemd on Linux, Task Scheduler on Windows). Enables auto-start on login and auto-restart on crash.
+
+```bash
+clooks service install
+```
+
+### `clooks service uninstall`
+
+Remove the system service.
+
+```bash
+clooks service uninstall
+```
+
+### `clooks service status`
+
+Show service status: `running`, `stopped`, or `not-installed`.
+
+```bash
+clooks service status
+```
+
+---
+
+[Home](../index.md) | [Prev: CC Plugin Import](../plugins/cc-plugin-import.md) | [Next: Hook Events](hook-events.md)

package/docs/reference/config-files.md

@@ -0,0 +1,129 @@
+# Config Files
+
+All configuration, state, and data files used by clooks, with their locations, formats, and schemas.
+
+---
+
+## File Map
+
+| Path | Format | Purpose |
+|------|--------|---------|
+| `~/.clooks/` | Directory | Configuration root |
+| `~/.clooks/manifest.yaml` | YAML | Handler definitions and settings |
+| `~/.clooks/daemon.pid` | Text | Running daemon PID |
+| `~/.clooks/daemon.log` | Text | Daemon log output |
+| `~/.clooks/metrics.jsonl` | JSONL | Hook execution metrics (max 5MB, rotated) |
+| `~/.clooks/costs.jsonl` | JSONL | LLM cost tracking (max 1MB, rotated) |
+| `~/.clooks/hooks/` | Directory | Built-in hook scripts |
+| `~/.clooks/plugins/` | Directory | Installed plugin directories |
+| `~/.clooks/plugins/installed.json` | JSON | Plugin registry |
+| `~/.clooks/settings.backup.json` | JSON | Pre-migration settings backup |
+| `~/.claude/settings.json` | JSON | Claude Code settings (HTTP hooks added here) |
+| `~/.claude/settings.local.json` | JSON | Local settings override |
+| `~/.claude/agents/clooks.md` | Markdown | clooks expert agent |
+
+---
+
+## Metrics File Format
+
+`metrics.jsonl` stores one JSON object per line. Each entry records a single handler execution.
+
+**Standard entry:**
+
+```json
+{
+  "ts": "2026-03-25T10:00:00.000Z",
+  "event": "PreToolUse",
+  "handler": "bash-guard",
+  "duration_ms": 12,
+  "ok": true,
+  "filtered": false,
+  "session_id": "abc123",
+  "agent_type": "builder"
+}
+```
+
+**LLM handler entry** (includes additional fields):
+
+```json
+{
+  "ts": "2026-03-25T10:00:00.000Z",
+  "event": "PreToolUse",
+  "handler": "code-review",
+  "duration_ms": 850,
+  "ok": true,
+  "filtered": false,
+  "session_id": "abc123",
+  "agent_type": "builder",
+  "usage": { "input_tokens": 150, "output_tokens": 80 },
+  "cost_usd": 0.00045
+}
+```
+
+---
+
+## Cost File Format
+
+`costs.jsonl` tracks LLM-specific cost data, one entry per LLM handler invocation.
+
+```json
+{
+  "ts": "2026-03-25T10:00:00.000Z",
+  "event": "PreToolUse",
+  "handler": "code-review",
+  "model": "claude-haiku-4-5",
+  "usage": { "input_tokens": 200, "output_tokens": 100 },
+  "cost_usd": 0.00056,
+  "batched": true
+}
+```
+
+---
+
+## Plugin Registry Format
+
+`installed.json` tracks all plugins installed via `clooks add`.
+
+```json
+{
+  "plugins": [
+    {
+      "name": "security-suite",
+      "version": "1.0.0",
+      "path": "/Users/you/.clooks/plugins/security-suite",
+      "installedAt": "2026-03-25T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+## File Rotation
+
+Data files are rotated when they exceed their size limit:
+
+| File | Max Size | Rotated To |
+|------|----------|------------|
+| `metrics.jsonl` | 5MB | `metrics.jsonl.1` |
+| `costs.jsonl` | 1MB | `costs.jsonl.1` |
+
+Only one rotated copy is kept. When rotation occurs, the existing `.1` file is overwritten.
+
+---
+
+## Service Files
+
+System service files are platform-specific:
+
+| Platform | Path |
+|----------|------|
+| macOS | `~/Library/LaunchAgents/com.clooks.daemon.plist` |
+| Linux | `~/.config/systemd/user/clooks.service` |
+| Windows | Task Scheduler task named `"clooks"` |
+
+These are managed by `clooks service install` and `clooks service uninstall`. Do not edit them manually.
+
+---
+
+[Home](../index.md) | [Prev: HTTP API](http-api.md) | [Next: Types](types.md)

package/docs/reference/hook-events.md

@@ -0,0 +1,128 @@
+# Hook Events
+
+Claude Code sends hook events to clooks via HTTP POST. Each event carries a HookInput payload with common fields plus event-specific data. There are 9 events in total.
+
+---
+
+## Common Fields
+
+All events include these fields in the HookInput payload:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `session_id` | `string` | Claude Code session identifier |
+| `transcript_path` | `string` | Path to the session transcript file |
+| `cwd` | `string` | Current working directory |
+| `permission_mode` | `string` | Active permission level |
+| `hook_event_name` | `string` | Event name (matches the route) |
+
+---
+
+## Events
+
+### SessionStart
+
+Fired when a Claude Code session begins.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `source` | `string` | How the session was started |
+| `agent_type` | `string` | Active agent name (e.g., `"builder"`, `"coo"`) |
+
+clooks caches `agent_type` for the duration of the session. Handlers with `sessionIsolation: true` are reset on this event.
+
+### UserPromptSubmit
+
+Fired when the user submits a prompt.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `prompt` | `string` | The user's prompt text |
+
+### PreToolUse
+
+Fired before Claude Code executes a tool. Handlers can block tool execution by returning a deny decision.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tool_name` | `string` | Tool being called (e.g., `"Bash"`, `"Write"`, `"Read"`) |
+| `tool_input` | `object` | Tool arguments |
+
+A handler can return the following to prevent execution:
+
+```json
+{
+  "decision": "block",
+  "reason": "Destructive command detected"
+}
+```
+
+### PostToolUse
+
+Fired after a tool completes.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tool_name` | `string` | Tool that was called |
+| `tool_input` | `object` | Tool arguments |
+
+> **Note:** This event is skipped if PreToolUse returned a `block` decision for the same tool invocation (short-circuit behavior).
+
+### Stop
+
+Fired when a session is ending.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `stop_hook_active` | `boolean` | Whether the stop hook is active |
+
+### SubagentStart
+
+Fired when a subagent is spawned.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `agent_type` | `string` | Subagent type |
+
+### SubagentStop
+
+Fired when a subagent completes. No additional fields beyond the common set.
+
+### Notification
+
+Fired when a system notification is sent. No additional fields beyond the common set.
+
+### ConfigChange
+
+Fired when Claude Code configuration changes. No additional fields beyond the common set.
+
+---
+
+## Event Flow
+
+A typical session produces events in this order:
+
+```
+SessionStart
+  UserPromptSubmit
+    PreToolUse  -> (if allowed) -> PostToolUse
+    PreToolUse  -> (if blocked) -> [no PostToolUse]
+    ...
+  UserPromptSubmit
+    ...
+Stop
+```
+
+Subagent events nest within the parent session:
+
+```
+SessionStart
+  SubagentStart
+    PreToolUse -> PostToolUse
+  SubagentStop
+Stop
+```
+
+---
+
+[Home](../index.md) | [Prev: CLI Reference](cli.md) | [Next: HTTP API](http-api.md)