Adding Claude Code hooks to a project that already has settings

Most guides assume an empty .claude/ folder. Real projects already have a settings.json and a CLAUDE.md. The safe approach is to add files without overwriting and merge by hand.

Prerequisites

• Node.js 20 or newer. Hook scripts that use only built-in modules (fs, path, child_process) need no packages and no jq.
• Claude Code 2.1.x. Hooks rely on the documented events PreToolUse, PostToolUse and Stop, and on exit code 2 to block or send feedback.
• A Next.js App Router project, meaning an app/ or src/app/ folder and next in package.json. Hooks that read files as text do not import Next.js, so they do not depend on its installed version (14, 15 and 16 are all fine). The Pages Router is a different matter and is not covered by App Router rules.

macOS and Linux are the safe assumptions. Windows may work but is untested.

Step 1: never overwrite

Copy new files in, but if a target already exists, leave yours alone and save the new one beside it with a suffix such as .new. That gives you something to compare rather than something to recover.

Step 2: merge settings.json by hand

Open the saved copy and copy the entries inside its "hooks" object into your existing "hooks" object. Use the same event names (PreToolUse, PostToolUse, Stop) and keep all of your existing entries. Delete the suffixed file when done.

Then validate the JSON, because a stray comma silently disables everything:

node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8'))"

Step 3: merge CLAUDE.md selectively

Do not paste a whole template over your own file. Read the new one and copy only the sections you want. The ones with the most effect are server and client component rules, environment variable handling, and the commands table. Replace every <...> placeholder, delete rules that do not apply, and keep it short. The file is read on every turn, so length costs you.

Step 4: restart and confirm

Hooks load when a session starts. Quit and restart claude from the project root, then run /hooks and check that the entries appear. Start claude in the folder that holds .claude/, not a subfolder, because hook commands use $CLAUDE_PROJECT_DIR.

Finish with a live test: ask Claude to add a variable to .env.local and confirm the edit is blocked with a message that names the hook.

Two setup errors to expect

• "node: command not found". Hooks run with the PATH of the environment Claude Code was started from. If you use a Node version manager, make sure node is on the PATH of a fresh terminal. As a fallback, put the absolute path from which node into the hook command.
• "Cannot find module .../.claude/hooks/...". You probably started claude from a subfolder. Start it from the project root.

Turning pieces off

Disable parts you do not want rather than deleting blindly. A slow typecheck on a big project is the usual one. After editing any hook, re-run whatever test covers it.

Going further

A ready-made set that follows this install pattern, with an installer that never overwrites and a self-test suite, is the Next.js Claude Code workflow pack.

This article was written with AI assistance.