@hasna/hooks weekly downloads statistics

@hasna/hooks

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

What it does

@hasna/hooks installs hooks into AI coding agents. A hook is a small program the agent runs at a fixed point: before a shell command, after a file edit, or when a turn ends. Hooks block a mistake, check the work, or automate a step. One CLI installs, lists, updates and removes them.

• Agents. Claude Code (the default target) and Codex. Compatible OpenCode and Sumi builds are supported for the stop-review hook. Gemini CLI is an install target (--target gemini), but the bundled shell guards do not yet recognise Gemini's tool names (run_shell_command rather than Bash), so do not rely on them there yet. Codewith targets remain for existing setups, but Codewith is deprecated. • Catalog. 57 bundled hooks in 10 categories, listed below. You can also install your own hooks from a local directory, a git URL or a manifest URL. • Safety core. Guards that: • block destructive git commands (gitguard); • send rm to a recoverable trash store instead of deleting (trash-guard). It needs the trash CLI from @hasna/trash on PATH; without it, trash-guard refuses the rm; • protect repository checkouts (workspace-repos-guard); • keep signed links out of agent transcripts (signed-link-guard).

scanoutput is detection only: it warns about a secret in tool output after the output is already in the transcript, and cannot prevent or redact it.

Each is installed as a hook. For Claude Code, Codex and Sumi, hooks safety install trash-guard --target can also register trash-guard, workspace-repos-guard and signed-link-guard as one native safety entry; the other guards are not part of it. --target defaults to codex, so name the agent. • Interfaces. The hooks CLI, an MCP server (hooks-mcp) and a self-hostable hook registry (hooks-serve).

Quick start

The CLI runs on Bun 1.0 or later, so bun must be on PATH. Without a Hasna hooks registry credential, use local mode: the bundled catalog and a local store in ~/.hasna/hooks. Set it in your shell profile, not only in the current shell. The agent runs each installed hook as hooks run , and that command needs the same setting. Without it the hook exits with REMOTE_API_CONFIG_MISSING and does not guard anything.

Starting the commands. The hooks, hooks-mcp and hooks-serve commands start through #!/usr/bin/env -S bun --config=/dev/null --no-env-file --no-macros --no-install. Started this way, they do not read the working directory's bunfig.toml or .env, so a project an agent works in cannot run code inside them. Starting them as commands needs GNU coreutils 8.30 or later, or the macOS/BSD env. That covers PATH, an npm or Bun bin link, bun x and bunx. The flags are verified with Bun 1.3.14, which silently ignores flags it does not know, so an older Bun may start the commands without one of these protections.

With BusyBox env (for example on Alpine) or older coreutils, start them through Bun with the same flags: • bun --config=/dev/null --no-env-file --no-macros --no-install /bin/index.js for hooks; • the same with bin/hooks-mcp.js or bin/serve.js for the others; • is $(npm root -g)/@hasna/hooks for an npm global install.

Without the flags, Bun reads the working directory's bunfig.toml and .env. Agents run installed hooks as hooks run . On such systems, put a hooks wrapper on PATH: a #!/bin/sh script that runs exec bun --config=/dev/null --no-env-file --no-macros --no-install /bin/index.js "$@". Otherwise every hook installed as hooks run fails at each event and guards nothing. The native-safety guards are registered with a pinned runtime and do not go through this shebang. For MCP, use "command": "bun" with those flags and /bin/hooks-mcp.js as its arguments.

Prompt for your agent

Paste this to your coding agent and it sets the hooks up itself:

Hook catalog

Run hooks list --all --verbose for each hook's description, or hooks info for one hook.

| Category | Hooks |

| Git safety | gitguard, branchprotect, checkpoint, worktree-guard, workspace-repos-guard, trash-guard, conflict-detect | | Code quality | checktests, checklint, checkfiles, checkbugs, checkdocs, checktasks, stylescheck, typecheck-gate, affected-tests | | Security | checksecurity, packageage, pre-bash, scanoutput, signed-link-guard, signed-link-output | | Permissions | permissionguard, protectfiles, promptguard, prompt-guard | | Context management | contextrefresh, precompact, knowledge-context, mementos-context | | Workflow automation | autoformat, autostage, tddguard, failure-to-task | | Environment | envsetup | | Notifications | phonenotify, agentmessages, desktopnotify, slacknotify, soundnotify | | Observability | sessionlog, commandlog, costwatch, errornotify, spiral-detector, scratch-lifecycle | | Agent teams | taskgate, session-start, stop-review, stop-sync, filelock, announce-start, announce-stop, dm-inject, fleet-catchup, agent-rules-version-check, fleet-blockers-gate |

CLI Usage

Trash startup readiness

The bundled trash-readiness observer checks an installed Trash ready plan at session startup. It reports a short ready or attention message. It does not capture files, repair settings, retry failed requests, or authorize deletion. Keep the separate trash-guard installed and enabled.

Claude and Codex use their native SessionStart event for startup, resume, clear and fork. Compaction does not repeat this check. Configuration and native execution are separate: successful setup leaves nativeAdoptionVerified:false until the actual consumer has been exercised.…

Description from the npm listing.