@hasna/hooks

Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command

Install

npm install -g @hasna/hooks

CLI Usage

hooks --help

• hooks install
• hooks list
• hooks search
• hooks remove
• hooks categories
• hooks info
• hooks doctor
• hooks run

Codewith-native hooks

@hasna/hooks includes unprefixed Codewith-native hook names:

• session-start — SessionStart digest and additional context.
• prompt-guard — UserPromptSubmit guard for pasted fake policy/freeze/run-this-now content.
• pre-bash — PreToolUse Bash gate for staged secrets scans, scoped destructive-operation blocks, and risky-op comms checks.
• worktree-guard — PreToolUse guard for managed repos worktree boundaries and file-tool-like payloads touching protected Hasna scopes.
• stop-sync — Stop turn-end heartbeat/evidence best effort.
• knowledge-context — deterministic Knowledge context packs for SessionStart, UserPromptSubmit, and SubagentStart.

For Codewith, the installer is renderer-safe by default: it emits a TOML fragment instead of mutating managed ~/.codewith/config.toml.

hooks install session-start prompt-guard pre-bash worktree-guard stop-sync knowledge-context --target codewith

The scoped destructive-operation guard does not block every cleanup command. It blocks resolved shell/file-tool targets that threaten ~/.hasna, configured workspace roots, Hasna division/scope roots, or active repo/worktree roots, including recursive rm, rsync --delete, destructive find, and destructive git clean / git reset --hard forms.

Apply that fragment through open-configs or the managed config renderer. A direct write path exists only for explicit local/test use:

hooks install knowledge-context --target codewith --apply-codewith --codewith-config /tmp/codewith-config.toml

Storage

Hooks stores data locally by default in ~/.hasna/hooks/ and uses SQLite directly for hook event history. The package owns its database schema and migrations; it does not depend on the deprecated shared runtime or its CLI. The repo includes its own PostgreSQL migration definitions for optional remote storage deployments. Use the hooks log commands to inspect local hook event data.

hooks storage status --json
HASNA_HOOKS_DATABASE_URL=postgres://... hooks storage push --tables hook_events,feedback --json
hooks storage pull --json
hooks storage sync --json

Configure database storage with HASNA_HOOKS_DATABASE_URL or fallback HOOKS_DATABASE_URL. Optional storage mode env vars are HASNA_HOOKS_STORAGE_MODE and HOOKS_STORAGE_MODE, with local, hybrid, or remote values.

Runtime model

This package is an npm/local CLI, MCP server, and static dashboard package. It does not require a deployed cloud or self-hosted runtime to install or run hooks.

Data Directory

Data is stored in ~/.hasna/hooks/.

License

Apache-2.0 -- see LICENSE