How to Check a Coding Agent's Package Installs with the Claude Code Hook
Run the Chainsaw install guard on every package install Claude Code is about to run — npm, pip, npx, uvx and the rest — and turn a malicious or typosquatted package into a refusal the agent reads, before anything is fetched.
What This Gets You
A coding agent installs whatever it decides it needs, including a package name it misremembered or invented, without anyone reading the command first. The Chainsaw Claude Code plugin checks every install in a Bash command before Bash runs it. When the install guard would refuse a package, Claude Code gets a deny with the reason, nothing is fetched, and the agent is told to check the name and ask you rather than retry another way.
It runs the same checks as the install guard (known-malicious packages, typosquats, offline by default), and it covers spellings the shell guard cannot see:
| Command the agent runs | Shell guard | Agent hook |
|---|---|---|
npm install x, pip install x, yarn add x, uv add x … | checked when the agent’s shell loads your rc file | checked |
command npm i x, /opt/homebrew/bin/npm i x, python3 -m pip install x | not checked | checked |
npx x, npm exec x, npm create x, pnpm dlx x, yarn create x, bunx x | not checked | checked |
uvx x, uv tool run x, pipx run x | not checked | checked |
bash -c "npm i x", cd web && npm ci (reads web/’s lockfile) | partly | checked |
You don’t need a Chainsaw account: the checks run on your machine. If you are signed in, the same server lookup the shell guard makes for npm and Homebrew installs runs here too.
Prerequisites
- Claude Code.
- The
chainsawCLI on yourPATH, recent enough to havechainsaw guard agent-hook. Check with:
chainsaw guard agent-hook --help
If that prints the general chainsaw guard help instead of a page about the
agent hook, update the CLI (Step 1).
Step 1: Install or Update the CLI
curl -fsSL https://chain305.com/install.sh | sh
The same command updates an existing install. For Windows and what the installer changes, see How to Block Malicious Packages at Install Time.
Step 2: Install the Plugin
claude plugin marketplace add Chain305/chainsaw-core
claude plugin install chainsaw-guard@chainsaw
Then run /reload-plugins in an open Claude Code session, or start a new one.
At session start the plugin checks the CLI. If chainsaw is missing or too
old, you see a chainsaw-guard: warning saying installs are not being checked,
with the command to fix it. No warning means the hook is active.
Step 3: Check It Works, Without Installing Anything
Hand the hook the payload Claude Code would send for an install of a known-malicious package. This runs the check only; nothing is installed:
printf '{"tool_name":"Bash","tool_input":{"command":"npm install lodahs"}}' | chainsaw guard agent-hook
You should get one line of JSON with "permissionDecision":"deny". Claude
Code shows the agent this reason:
Chainsaw refused this install; nothing was run.
- npm:lodahs: known-malicious (MAL-2025-25502) — the advisory covers every version of lodahs; …
Do not retry it another way (another package manager, a direct path, npx, or a script).
Check that the package name is the one intended. If this exact package is needed,
stop and ask the user to review it.
A command with no refused install prints nothing and runs as normal:
printf '{"tool_name":"Bash","tool_input":{"command":"npm install lodash"}}' | chainsaw guard agent-hook
What the Agent Sees
- A refused install: a deny with the reason. The command does not run.
- A package name only known at run time (
npm i "$PKG",xargs npm install): Claude Code asks you to approve the command, because the name cannot be checked until it runs. - Everything else: nothing. The hook never approves a command on your behalf, so your own permission settings still decide.
If a package is refused and you have checked it is the one you want, run the
install yourself in your terminal. The shell guard shows the
chainsaw guard allow command for a typosquat verdict there. The agent is
deliberately not shown it.
Settings It Shares with the Shell Guard
CHAINSAW_GUARD_SKIP=npm(comma-separated) turns the check off for those managers. Set it in the environment Claude Code starts from.CHAINSAW_COVERAGE_MODE=closedrefuses installs when a required signal source is missing, exactly as it does for the shell guard. Without it, a missing source never blocks.- Signed out, every check runs on your machine. Signed in, npm and Homebrew
installs also get the server lookup, as they do in the shell guard.
CHAINSAW_OFFLINE=1turns that lookup off.
Set It Up Without the Plugin
Add this to ~/.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "chainsaw guard agent-hook; s=$?; [ \"$s\" -eq 2 ] && exit 1; exit \"$s\""
}
]
}
]
}
}
Keep the exit-status part of the command: Claude Code treats exit status 2 as “block this command”, so it is turned into 1, an error Claude Code shows without blocking. The plugin does the same, and also adds the session-start check.
Limits
- It reads command text. An install inside a script file, a Makefile or
node -eis not checked. It is a second check beside the shell guard, not enforcement. For installs nobody can route around, point package managers at the Chainsaw proxy. - Not covered yet:
bun add/bun install. - MCP servers your agent app launches with
npx -y …are started by the app, not through Bash, so the hook never sees them. The proxy does, through your.npmrc.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
chainsaw-guard: the chainsaw CLI is not on PATH at session start | Claude Code’s environment has no chainsaw | Run Step 1, then restart Claude Code |
chainsaw-guard: this chainsaw CLI predates the agent hook | An older CLI | Run Step 1 to update |
| A hook error after every Bash command | The hook was added by hand with a typo, or an unsupported --format | Compare with the snippet above |
| An install the guard refused still ran | It was in a script file, or CHAINSAW_GUARD_SKIP names that manager | See Limits; check the environment |
Related
- How to Block Malicious Packages at Install Time with the CLI — the shell guard this hook shares its checks with.
- How to Connect Claude / Cursor / GPT to Chainsaw via the Built-in MCP Server — let the agent query Chainsaw, not just be checked by it.
chainsaw guard agent-hookreference