clooks

clooks

Persistent hook runtime for Claude Code. Eliminate cold starts. Get observability.

[](https://www.npmjs.com/package/@mauribadnights/clooks) [](LICENSE)

**[Documentation](https://mauribadnights.github.io/clooks/)**

Performance

Metric	Without clooks	With clooks	Improvement
Single hook invocation	~34.6ms	~0.31ms	112x faster
Full session (120 invocations)	~3,986ms	~23ms	99% time saved
5 parallel handlers	~424ms	~96ms	4.4x faster

Benchmarked on Apple Silicon (M-series), Node v24.4.1. Run `npm run bench` to reproduce.

Installation

npm install -g @mauribadnights/clooks
clooks migrate    # migrates existing hooks, installs system service, installs clooks agent
clooks start

`clooks migrate` converts your `settings.json` command hooks into HTTP hooks backed by the daemon, auto-installs a system service (launchd/systemd) for auto-start and crash recovery, and installs the `clooks` expert agent (`claude --agent clooks`). Starting fresh instead? Use `clooks init` to create a blank manifest.

How It Works

One persistent HTTP server replaces per-invocation process spawning. Claude Code POSTs hook events to the daemon, which dispatches to handlers defined in `~/.clooks/manifest.yaml`. Handlers that fail 3 times consecutively are auto-disabled.

Quick Reference -- Commands

**Daemon lifecycle:**

Command	Description
clooks start	Start the daemon (-f foreground, --no-watch disable manifest watching)
clooks stop	Stop the daemon
clooks status	Show daemon status, uptime, handler count, service state
clooks ensure-running	Start daemon if not running (used internally by SessionStart hook)

**Observability:**

Command	Description
clooks stats	Interactive TUI for execution metrics (-t for plain text)

...