🦉 HooKit

Hooks with outcome-selected Pi Actions for Pi events.

HooKit applies user-configured Hooks to Pi Events — a policy that subscribes to a tool call, a finished turn, or a settled agent, runs a shell decision, and may own one outcome-selected Pi Action. Configuration lives in .pi/hookit.json; /hooks manages installation, enablement, defaults, Presets, and search in Pi's interactive TUI. Hook Evaluation also works in RPC, JSON, and print modes.

The documentation

The complete documentation is organized around three needs:

• Getting Started — installation, Hook authoring, troubleshooting, and the Hook library.
• Reference — the complete configuration contract and runtime behavior.
• Concepts — evaluation, composition, and security.
• Glossary — domain vocabulary.

These readable Markdown pages ship with each npm release, alongside the JSON Schema, and are authoritative for that installed version. The bundled skill routes help and authoring tasks to local references without network access. The documentation website is supplementary and may describe a newer version.

In a repository checkout, run npm ci and npm run package:prepare to generate the same local pages from site/content/docs/. Every designated JSON configuration example is validated against the schema.

Quick example

{
  "$schema": "https://raw.githubusercontent.com/meffmadd/HooKit/main/schema.json",
  "local": {
    "protect-env": {
      "description": "Block writes to dotenv files",
      "event": "tool_call",
      "filter": {
        "toolName": "^write$",
        "path": "(^|/)\\.env$"
      },
      "shell": "false",
      "action": {
        "type": "message",
        "outcome": "block",
        "code": 1,
        "message": "A dotenv write was blocked by HooKit.",
        "delivery": "followUp",
        "sendAs": "custom"
      },
      "default": true
    }
  }
}

In an interactive Pi TUI, open /hooks, focus protect-env, and press Enter to toggle its enablement. Follow Installation, then Write a hook for a complete Hook with an expected result at every step.

Security

Hook shells execute locally as trusted code with your Pi process permissions. They are not sandboxed; the 5-second default timeout bounds commands but is not a sandbox. Treat repository Hooks like third-party executable code and review their Source before installation. Read the security page before authoring or installing policies from untrusted sources.

Repositories

• HooKit — the extension, schema, documentation site, and stable Core Hook catalog. Core Hooks install remotely from meffmadd/HooKit; they are not bundled in the npm package.
• HooKit Extras — specialized, platform-specific, dependency-heavy, and incubating Hooks.