@hasna/hooks 0.2.3 → 0.2.5

package/README.md

@@ -1,95 +1,112 @@
-# Hooks
+# @hasna/hooks
 
-Open source library of 30 Claude Code hooks. Install any hook with a single command.
+Open source lifecycle hooks library for AI coding agents. 30 hooks across 10 categories, installable with a single command. Works with Claude Code and Gemini CLI.
 
-## Quick Start
-
-```bash
-# Interactive mode - browse and select hooks
-npx @hasna/hooks
-
-# Install specific hooks
-npx @hasna/hooks install gitguard branchprotect checkpoint
+## Features
 
-# List all available hooks
-npx @hasna/hooks list
-```
+- **30 hooks** in 10 categories (git safety, code quality, security, notifications, and more)
+- **Interactive CLI** (`hooks`) with React/Ink TUI for browsing, installing, and managing hooks
+- **MCP server** (13 tools) for agent-driven hook management over stdio or SSE
+- **Library** for programmatic access from Node.js/Bun
+- **Multi-agent support** for Claude Code and Gemini CLI with per-agent event mapping
+- **Agent profiles** with unique 8-char UUID identity system
+- **Zero file copy** -- hooks run from the globally installed package, nothing is copied to your project
+- **Web dashboard** for browsing hooks (Vite + React 19 + TailwindCSS 4)
+- **Health checks** via `hooks doctor` to verify hook installation integrity
+- Global or project-scoped installation
 
 ## Installation
 
 ```bash
-# Global install
 bun install -g @hasna/hooks
-
-# Or use npx (no install needed)
-npx @hasna/hooks
 ```
 
-## NPM Auth (Optional)
-
-If you need a scoped registry token (publish or private installs), copy an example file and set `NPM_TOKEN`:
+Or with npm:
 
 ```bash
-cp .npmrc.example .npmrc
+npm install -g @hasna/hooks
 ```
 
-See `CONTRIBUTING.md` for publishing and secrets guidance.
-
-## Usage
-
-### Interactive Mode
-
-Run without arguments to browse hooks by category:
+Or use without installing:
 
 ```bash
-hooks
+npx @hasna/hooks
 ```
 
-### Install Hooks
+## Quick Start
 
 ```bash
-# Install one or more hooks
+# Interactive mode -- browse and select hooks
+hooks
+
+# Install specific hooks
 hooks install gitguard branchprotect checkpoint
 
-# Hooks are installed to .hooks/ and registered in ~/.claude/settings.json
-```
+# Install all hooks in a category
+hooks install --category "Git Safety"
 
-### Search
+# Install all 30 hooks
+hooks install --all
+
+# List all available hooks
+hooks list
 
-```bash
 # Search by name, description, or tags
 hooks search security
-hooks search git
-```
 
-### List by Category
+# Check health of installed hooks
+hooks doctor
 
-```bash
-hooks list --category "Git Safety"
-hooks list --category "Code Quality"
+# Start MCP server for agent integration
+hooks mcp --stdio
 ```
 
-### Hook Info
-
-```bash
-hooks info gitguard
-```
+## Hook Categories
+
+| Category | Count | Description |
+|----------|------:|-------------|
+| Git Safety | 3 | Block destructive git ops, protect branches, create snapshots |
+| Code Quality | 6 | Check tests, lint, bugs, docs, files, and task completion |
+| Security | 2 | Security audits and typosquatting prevention |
+| Notifications | 5 | Phone, desktop, Slack, sound, and inter-agent messages |
+| Context Management | 2 | Re-inject context and save state before compaction |
+| Workflow Automation | 3 | Auto-format, auto-stage, and TDD enforcement |
+| Environment | 1 | Detect nvm/virtualenv/asdf/rbenv activation needs |
+| Permissions | 3 | Auto-approve safe commands, protect files, block prompt injection |
+| Observability | 4 | Session logs, command logs, cost tracking, error detection |
+| Agent Teams | 1 | Validate task completion criteria |
+
+## Hook Events
+
+| Event | Timing | Can Block | Matcher |
+|-------|--------|:---------:|---------|
+| PreToolUse | Before tool execution | Yes | Tool name pattern (e.g., `Bash`, `Write\|Edit`) |
+| PostToolUse | After tool execution | No | Tool name pattern |
+| Stop | Session ends | No | Empty string |
+| Notification | System events (e.g., compaction) | No | Empty string |
 
-### Check Registered Hooks
+Each hook receives JSON on stdin and outputs JSON on stdout:
 
-```bash
-hooks list --registered
-```
+```json
+// Input (PreToolUse)
+{
+  "session_id": "abc123",
+  "cwd": "/path/to/project",
+  "tool_name": "Bash",
+  "tool_input": { "command": "git push --force" }
+}
 
-### Remove
+// Output (block)
+{ "decision": "block", "reason": "Destructive git operation blocked" }
 
-```bash
-hooks remove gitguard
+// Output (approve)
+{ "decision": "approve" }
 ```
 
 ## Available Hooks (30)
 
 ### Git Safety (3)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | gitguard | PreToolUse | Blocks destructive git operations like reset --hard, push --force, clean -f |
@@ -97,6 +114,7 @@ hooks remove gitguard
 | checkpoint | PreToolUse | Creates shadow git snapshots before file modifications for easy rollback |
 
 ### Code Quality (6)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | checktests | PostToolUse | Checks for missing tests after file edits |
@@ -107,12 +125,14 @@ hooks remove gitguard
 | checktasks | PostToolUse | Validates task completion and tracks progress |
 
 ### Security (2)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | checksecurity | PostToolUse | Runs security checks via headless agents |
 | packageage | PreToolUse | Checks package age before install to prevent typosquatting |
 
 ### Notifications (5)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | phonenotify | Stop | Sends push notifications to phone via ntfy.sh |
@@ -122,12 +142,14 @@ hooks remove gitguard
 | soundnotify | Stop | Plays a system sound when Claude finishes (macOS/Linux) |
 
 ### Context Management (2)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | contextrefresh | Notification | Re-injects important context every N prompts to prevent drift |
 | precompact | Notification | Saves session state before context compaction |
 
 ### Workflow Automation (3)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | autoformat | PostToolUse | Runs project formatter (Prettier, Biome, Ruff, Black, gofmt) after file edits |
@@ -135,11 +157,13 @@ hooks remove gitguard
 | tddguard | PreToolUse | Blocks implementation edits unless corresponding test files exist |
 
 ### Environment (1)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | envsetup | PreToolUse | Warns when nvm, virtualenv, asdf, or rbenv may need activation before commands |
 
 ### Permissions (3)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | permissionguard | PreToolUse | Auto-approves safe read-only commands and blocks dangerous operations |
@@ -147,6 +171,7 @@ hooks remove gitguard
 | promptguard | PreToolUse | Blocks prompt injection attempts and credential access requests |
 
 ### Observability (4)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | sessionlog | PostToolUse | Logs every tool call to .claude/session-log-\<date\>.jsonl |
@@ -155,74 +180,206 @@ hooks remove gitguard
 | errornotify | PostToolUse | Detects tool failures and logs errors to .claude/errors.log |
 
 ### Agent Teams (1)
+
 | Hook | Event | Description |
 |------|-------|-------------|
 | taskgate | PostToolUse | Validates task completion criteria before allowing tasks to be marked done |
 
-## How Hooks Work
+## CLI Commands
+
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `hooks` | `hooks interactive`, `hooks i` | Interactive hook browser (default) |
+| `hooks install <names...>` | `hooks add` | Install one or more hooks |
+| `hooks install --all` | | Install all 30 hooks |
+| `hooks install --category <cat>` | | Install all hooks in a category |
+| `hooks list` | `hooks ls` | List available hooks |
+| `hooks list --registered` | `hooks list -r` | Show currently registered hooks |
+| `hooks list --category <cat>` | `hooks list -c <cat>` | Filter by category |
+| `hooks search <query>` | | Search hooks by name, description, or tags |
+| `hooks info <name>` | | Show detailed info about a hook |
+| `hooks remove <name>` | `hooks rm` | Unregister a hook |
+| `hooks update [names...]` | | Re-register hooks (picks up new package version) |
+| `hooks doctor` | | Check health of installed hooks |
+| `hooks docs [name]` | | Show documentation (general or hook-specific) |
+| `hooks categories` | | List all categories with counts |
+| `hooks init` | | Register a new agent profile |
+| `hooks run <name>` | | Execute a hook (called by AI agents) |
+| `hooks mcp` | | Start MCP server (SSE or `--stdio`) |
+| `hooks upgrade` | | Self-update to latest version |
+
+### Scope Options
+
+Most commands accept scope flags:
+
+| Flag | Description |
+|------|-------------|
+| `--global`, `-g` | Global scope (`~/.claude/settings.json`) -- default |
+| `--project`, `-p` | Project scope (`.claude/settings.json`) |
+| `--json`, `-j` | Machine-readable JSON output |
+| `--profile <id>` | Agent profile ID to scope hooks to |
+| `--overwrite`, `-o` | Overwrite existing hook registration |
+
+## MCP Server
+
+Start the MCP server for AI agent integration:
 
-Claude Code hooks are lifecycle interceptors that run during agent sessions:
+```bash
+# Stdio transport (for agent MCP registration)
+hooks mcp --stdio
 
-- **PreToolUse**: Runs before a tool executes. Can **block** the operation.
-- **PostToolUse**: Runs after a tool executes. Async, non-blocking.
-- **Stop**: Runs when a session ends. Async, non-blocking.
-- **Notification**: Runs on notification events. Async, non-blocking.
+# SSE transport (default, port 39427)
+hooks mcp
+hooks mcp --port 8080
+```
 
-Each hook receives JSON on stdin and outputs JSON on stdout:
+### Registration
+
+Add to `~/.claude/mcp.json` or equivalent agent config:
 
 ```json
-// PreToolUse input
 {
-  "session_id": "abc123",
-  "cwd": "/path/to/project",
-  "tool_name": "Bash",
-  "tool_input": { "command": "git push --force" }
+  "mcpServers": {
+    "hooks": {
+      "command": "hooks",
+      "args": ["mcp", "--stdio"]
+    }
+  }
 }
+```
 
-// PreToolUse output (block)
-{ "decision": "block", "reason": "Destructive git operation blocked" }
+### MCP Tools (13)
 
-// PreToolUse output (approve)
-{ "decision": "approve" }
-```
+| Tool | Description |
+|------|-------------|
+| `hooks_list` | List all available hooks, optionally filtered by category |
+| `hooks_search` | Search for hooks by name, description, or tags |
+| `hooks_info` | Get detailed information about a specific hook including install status |
+| `hooks_install` | Install one or more hooks by name |
+| `hooks_install_category` | Install all hooks in a category |
+| `hooks_install_all` | Install all available hooks |
+| `hooks_remove` | Remove (unregister) a hook from agent settings |
+| `hooks_doctor` | Check health of installed hooks |
+| `hooks_categories` | List all hook categories with counts |
+| `hooks_docs` | Get documentation (general overview or hook-specific README) |
+| `hooks_registered` | Get list of currently registered hooks for a scope |
+| `hooks_init` | Register a new agent profile |
+| `hooks_profiles` | List all registered agent profiles |
+
+## Agent Profiles
+
+Agents can register a profile to get a unique 8-char UUID. This identity is injected into hook input when running with `--profile`.
 
-## Hook Structure
+```bash
+# Register a profile
+hooks init --agent claude --name "my-agent"
+# Agent profile created
+#   Agent ID:   a1b2c3d4
+#   Type:       claude
 
-Each hook follows a consistent structure:
+# Install hooks scoped to a profile
+hooks install gitguard --profile a1b2c3d4
 
+# The registered settings entry becomes:
+#   hooks run gitguard --profile a1b2c3d4
 ```
-hook-{name}/
-├── src/
-│   ├── hook.ts     # Main hook logic (stdin → stdout)
-│   ├── cli.ts      # CLI for install/uninstall/status
-│   └── index.ts    # Library exports
-├── package.json
-├── CLAUDE.md
-├── README.md
-└── tsconfig.json
+
+Profiles are stored at `~/.hooks/profiles/<agent_id>.json`.
+
+## Library Usage
+
+```typescript
+import {
+  HOOKS,
+  CATEGORIES,
+  searchHooks,
+  getHook,
+  getHooksByCategory,
+  installHook,
+  installHooks,
+  getRegisteredHooks,
+  removeHook,
+  createProfile,
+  listProfiles,
+  type HookMeta,
+  type Category,
+} from "@hasna/hooks";
+
+// Search for hooks
+const securityHooks = searchHooks("security");
+
+// Get hooks by category
+const gitHooks = getHooksByCategory("Git Safety");
+
+// Install a hook programmatically
+const result = installHook("gitguard", { scope: "global" });
+
+// Check what's registered
+const registered = getRegisteredHooks("global");
+
+// Create an agent profile
+const profile = createProfile({ agent_type: "claude", name: "my-bot" });
 ```
 
-## Installing Individual Hooks
+## Writing a Custom Hook
 
-You can also install hooks individually as npm packages:
+Hooks follow a stdin/stdout JSON protocol. Create a new hook at `hooks/hook-<name>/`:
 
-```bash
-bun install -g @hasna/hook-gitguard
-bun install -g @hasna/hook-branchprotect
-bun install -g @hasna/hook-checkpoint
+```
+hooks/hook-myhook/
+  src/
+    hook.ts       # Main hook logic (stdin JSON -> stdout JSON)
+  package.json
+  README.md
 ```
 
-Then use their built-in CLI:
+### Hook Template (PreToolUse)
 
-```bash
-hook-gitguard install    # Register in Claude settings
-hook-gitguard status     # Check if registered
-hook-gitguard uninstall  # Unregister
+```typescript
+#!/usr/bin/env bun
+import { readFileSync } from "fs";
+
+interface HookInput {
+  session_id: string;
+  cwd: string;
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+}
+
+interface HookOutput {
+  decision?: "approve" | "block";
+  reason?: string;
+}
+
+// Read JSON from stdin
+const input: HookInput = JSON.parse(readFileSync(0, "utf-8"));
+
+// Your logic here
+if (input.tool_name === "Bash") {
+  const command = input.tool_input.command as string;
+  if (command.includes("rm -rf /")) {
+    console.log(JSON.stringify({ decision: "block", reason: "Dangerous command" }));
+    process.exit(0);
+  }
+}
+
+// Approve by default
+console.log(JSON.stringify({ decision: "approve" }));
 ```
 
+Key rules:
+- Read from **stdin** (JSON), write to **stdout** (JSON)
+- Log diagnostics to **stderr** only (stdout must be clean JSON)
+- PreToolUse hooks return `{ "decision": "approve" | "block", "reason"?: string }`
+- PostToolUse/Stop/Notification hooks return informational JSON (not blocking)
+
+### Registering a Custom Hook
+
+Add the hook to `src/lib/registry.ts` in the `HOOKS` array, then update `dashboard/src/data.ts` to keep the dashboard in sync.
+
 ## Configuration
 
-Hooks are registered in `~/.claude/settings.json`:
+Hooks are registered in `~/.claude/settings.json` (Claude) or `~/.gemini/settings.json` (Gemini):
 
 ```json
 {
@@ -231,7 +388,7 @@ Hooks are registered in `~/.claude/settings.json`:
       {
         "matcher": "Bash",
         "hooks": [
-          { "type": "command", "command": "hook-gitguard" }
+          { "type": "command", "command": "hooks run gitguard" }
         ]
       }
     ]
@@ -239,29 +396,67 @@ Hooks are registered in `~/.claude/settings.json`:
 }
 ```
 
+Event names are mapped per agent:
+
+| Internal Event | Claude Code | Gemini CLI |
+|---------------|-------------|------------|
+| PreToolUse | PreToolUse | BeforeTool |
+| PostToolUse | PostToolUse | AfterTool |
+| Stop | Stop | AfterAgent |
+| Notification | Notification | Notification |
+
 ## Development
 
 ```bash
-# Install dependencies
+git clone https://github.com/hasna/hooks.git
+cd hooks
 bun install
 
-# Run CLI in development
-bun run dev
+bun run dev              # Run CLI in development (interactive mode)
+bun run build            # Build CLI (bin/) + library (dist/)
+bun run typecheck        # TypeScript type checking
+bun test                 # Run all tests (592 tests, 1816+ assertions)
 
-# Build
-bun run build
+# Dashboard (separate Vite + React 19 app)
+bun run dashboard:dev    # Dev server at localhost:5173
+bun run dashboard:build  # Production build to dashboard/dist/
+```
 
-# Type check
-bun run typecheck
+## Architecture
+
+```
+src/
+  cli/          Commander.js CLI + React/Ink interactive TUI
+    components/   App, Header, CategorySelect, HookSelect, SearchView, DataTable, InstallProgress
+    index.tsx     CLI entry point (all commands)
+  lib/          Core logic
+    registry.ts   Hook metadata registry (HOOKS array, categories, search)
+    installer.ts  Hook registration in agent settings files
+    profiles.ts   Agent profile identity system
+  mcp/          MCP server (stdio + SSE transport, 13 tools)
+    server.ts     Tool definitions and transport setup
+  hooks/        Hook runtime test
+  index.ts      Library re-exports
+
+hooks/          30 hook implementations
+  hook-gitguard/
+    src/hook.ts   Main hook logic (stdin -> stdout)
+    package.json
+    README.md
+  hook-branchprotect/
+  hook-checkpoint/
+  ...
+
+dashboard/      Web dashboard (Vite + React 19 + TailwindCSS 4)
+  src/data.ts   Static copy of hook metadata (sync with registry.ts)
 ```
 
-## Contributing
+### Build Outputs
 
-1. Fork the repository
-2. Create a new hook in `hooks/hook-{name}/`
-3. Follow the existing hook patterns
-4. Submit a pull request
+Two separate `bun build` invocations:
+- **CLI binary** (`bin/index.js`) -- Commander.js + Ink/React interactive UI
+- **Library** (`dist/index.js` + `dist/index.d.ts`) -- Registry + installer + profile APIs
 
 ## License
 
-Apache-2.0
+[Apache License 2.0](LICENSE)