Installation

This guide shows you how to install HooKit as a Pi package. HooKit is distributed as @meffmadd/hookit on npm.

Install HooKit

Use a user installation when you want HooKit available in every Pi session. This is the recommended setup for the Write a hook tutorial.

1. Install HooKit from npm:

   pi install npm:@meffmadd/hookit

2. Confirm that Pi recorded the package:

   pi list

By default, Pi records the package in ~/.pi/agent/settings.json and installs its content under ~/.pi/agent/npm/. pi list should include npm:@meffmadd/hookit.

Install HooKit for one project

Use a project installation when the project should declare HooKit for everyone who works in it.

From the project root, run:

pi install -l npm:@meffmadd/hookit

Pi records the package in .pi/settings.json. When another user opens the project, Pi asks them to review and trust its project resources before loading HooKit or installing a missing package. Project trust authorizes loading; it does not sandbox the extension or Hook shells.

Verify the extension

Open an interactive Pi TUI where the installation applies by running pi in a terminal without --mode rpc, --mode json, or --print. For a project installation, trust the project when Pi asks. Then run:

/hooks

The Hook Catalog panel should open. /hooks management requires the TUI; Hook Evaluation also works in headless runtime modes. If /hooks is unknown, check pi list, confirm that the package is installed in the intended user or project scope, and restart Pi.

Keep the installation current

To update installed Pi extension packages, including an unpinned HooKit npm installation, run:

pi update --extensions

Continue with Write a hook to configure and exercise a dependency-free policy.