Skip to content
meganemura/*

steerhook

steerhookApache-2.0

Rules that block or warn before a tool runs and tell Claude the alternative. Rules live in ~/.claude/steerhook/ and apply in every project.

Install

/plugin marketplace add meganemura/steerhook
/plugin install steerhook@steerhook

steerhook is a Claude Code plugin with a hook that steers. A rule names a command pattern you do not want Claude to run and the form you want instead. Before Claude runs a tool, steerhook checks the call against your rules, and a rule either blocks the call or lets it through with a warning. In both cases, the rule’s message reaches Claude, so Claude learns the alternative when it is about to act. steerhook is a fork of Anthropic’s hookify plugin for Claude Code, under the Apache License 2.0.

Features

Section titled “Features”
  • The message reaches Claude. A block sends the rule’s message as permissionDecisionReason, and a warning sends it as additionalContext. The user still sees it as systemMessage.
  • Your rules in one place. Rules are files in ~/.claude/steerhook/ and apply in every project. STEERHOOK_RULES_DIR names another directory, and a project’s own rules are never read.
  • Matches what the shell runs. A bash rule matches the code after steerhook reads the quoting, so codex exec inside a quoted argument does not fire it. command_literal, command_expanded, and command_raw name the other views of a command.
  • Rules from your words. /steerhook:add <what to prevent> drafts a rule from your words and a real example in the last exchanges, asks whether it should block or warn, and writes the file only after you agree.
  • Rules you can see. /steerhook:list prints every loaded rule with the first line of its message, and /steerhook:configure switches rules on and off.

How an agent uses it

Section titled “How an agent uses it”

Claude loads the writing-steerhook-rules skill when you ask for a rule in your own words, such as “stop me from force-pushing”, and /steerhook:add loads it first. The skill carries the file format, how to write a pattern that catches the real mistake, and how to write a message Claude can act on. When a later tool call matches a rule, Claude reads that message with the denial or the warning. Rules take effect on the next tool call, with no restart.

Getting started

Section titled “Getting started”

steerhook needs Node 22.18 or later, because the hooks are TypeScript files that node runs directly.

Terminal window
/plugin marketplace add meganemura/steerhook
/plugin install steerhook@steerhook

A rule is a markdown file with frontmatter, such as ~/.claude/steerhook/no-direct-codex-exec.md:

---
name: no-direct-codex-exec
enabled: true
event: bash
pattern: (^|[\s;&|(])codex\s+exec\b
action: block
---


Do not run `codex exec` from Bash. Send the task to the `codex:codex-rescue`
subagent with `--wait`, so the completion arrives as an agent notification.

Works with

Section titled “Works with”
  • The scenarios under features/ are steerhook’s behavior contract, written for nukadoko. npx nuka check checks them, and npx nuka run features runs every scenario against the hook scripts.