Chapter 11. Hooks and Screen Customization
Required Read this to follow this stage.One-line summary: A hook (Hook) is a command that Claude Code itself runs at set moments. It does not leave things to the AI's judgment, so use it for things that must happen.
The screens in this chapter come from running Claude Code 2.1.318 on Linux on November 6, 2026.
Let's make a hook that leaves a record every time a file changes. We will also adjust the status line at the bottom of the screen and the tone of answers to suit you.
What Is a Hook?
A hook is a shell command you set up. Claude Code runs that command at set points. So you do not have to hope that Claude will "remember and do it."[1]
Put it side by side with the CLAUDE.md from Chapter 8 and you can see the difference.
- Weak example: You write in CLAUDE.md, "When you change a file, leave one line in changelog.txt." The one keeping this rule is Claude. It can miss it.
- Better example: You make the same thing a hook. The one keeping this rule is Claude Code. The command runs after every file change.
Use hooks for things that must happen every single time.[2] That does not mean you need to move every rule into a hook. Rules like tone or document format are fine in CLAUDE.md. Use hooks only for "things that would cause trouble if skipped."
Quick check
You want a record every time a file changes, without fail. Why is a hook better than writing it in CLAUDE.md?
Making the Change-Log Hook
You make a hook by adding a hooks field to a settings file.[3] In this chapter, we put it in the project settings file .claude/settings.json. It is the same file that holds the deny rule from Chapter 7.
When you edit it by hand, a single comma can easily break it. So we overwrite the whole file at once. The deny rule from Chapter 7 is included as is in the content below, so it does not disappear.
Leave with /exit and, in the practice folder in the terminal, paste the whole block below. If it has not run yet after pasting, press Enter once more.
Several unfamiliar field names appear, but you do not need to know them all now. There are three big chunks:
permissions: the deny rule made in Chapter 7hooks: the change-log hook we are making nowstatusLine: the status line at the bottom of the screen
The detailed meanings are explained one by one right below the box.
cat > .claude/settings.json <<'EOF'
{
"permissions": {
"deny": ["Read(./secret/**)"]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{ "type": "command", "command": "date '+%F %T File changed' >> changelog.txt" }
]
}
]
},
"statusLine": { "type": "command", "command": "echo Organizing Corner Cafe" }
}
EOFIn Windows PowerShell, open Notepad with notepad .claude\settings.json. Delete the original content and put in only what is between the line starting with cat and the EOF line in the box above. Save with Ctrl + S and close it. We did not test this method.
Let's explain the unfamiliar words one by one. The last field, statusLine, is covered in the "Status Line" section later.
PostToolUse: Means after Claude uses a tool. It cannot undo what is already done. The point where you can step in and block before a tool is used isPreToolUse.[4]matcher: Sets which tools it reacts to.Write|Editare the tool that creates files and the tool that edits them. Here|means "or." This hook does not react to files Claude changes with shell commands.command: The command to run. It appends the current date, time, and a sentence to the end ofchangelog.txt. Broken into pieces, the command looks like this:date: A command that prints the current date and time.'+%F %T File changed': The format to print. The date (2026-11-06) goes in place of%F, and the time (11:19:11) in place of%T.>> changelog.txt: Appends the result to the end of that file. The>from Chapter 10 overwrites a file, while>>adds to the end. If the file does not exist, it creates a new one.
Instead of overwriting, you can also ask Claude in words.[5] For a file that already has settings in it, like your own project's, this way is better. The .claude folder is specially protected, so a permission prompt may appear at this point.[6]
Add a hook to .claude/settings.json. Make the command below run every time after Claude uses the Write or Edit tool. Do not delete what is already there.
date '+%F %T File changed' >> changelog.txtIf there is already a hooks field, do not replace it wholesale; add one more inside it.[7] We did not run this hook on Windows. The date command is in bash form, so it may not run as is. In that case, ask Claude to change it to a command that fits your environment.
Now let's test it. Start claude and send this:
Create hook-test.md in the notes folder and write just one line: "hook test".When it finishes, type ! cat changelog.txt. When we actually ran it, one line was left like this:
2026-11-06 11:19:11 File changedYou can see the full settings file at ch11-settings.json.txt.
Quick check
In hook settings, what point in time does `PostToolUse` mean?
Checking Your Hooks
To see whether a hook is registered, type /hooks in a session.[8] This screen is view-only. You cannot create or edit hooks here. The screen itself says so.
Hooks
1 hook on 1 event
This menu is read-only. To add or change a hook, edit settings.json or ask Claude. Learn more
PostToolUse after tool execution
❯ [Project] date '+%F %T File changed' >> changelog.txt Write|Edit · command
All events
Enter to view · Esc to closeIf a hook does not run, first ask yourself: Does it appear in /hooks? Is it under PostToolUse?[8:1] If it is still missing, check the syntax of the settings file. A settings file cannot have trailing commas or comments.[9] Overwriting with the box above again is the fastest fix.
Quick check
Which statement about the `/hooks` screen and the settings file is correct?
Hooks in a Folder Someone Gave You
If it is a practice folder you made yourself, the risk is low. What you need to watch out for is a folder you got from someone else.
A folder from someone else may contain hooks that person wrote.[10] If you run it with claude -p, those hooks run even in a folder you never said you trust.[11] So it is safer to assume those hooks run on your computer under your account. For a folder you received, read the settings file before starting Claude. This advice is this guide's own judgment, not a sentence from the official docs.
cat .claude/settings.jsonLook at what commands are in the hooks and statusLine fields. If you do not understand them, ask in a chat outside that folder. The plugins from Chapter 9 can also run code with your permissions.[12] Treat them with the same care.
Quick check
What does this guide recommend when you first use a folder someone else gave you?
Status Line
The status line (Status line) is a line at the bottom of the Claude Code screen that shows the output of a shell script you set.[13] Just add a statusLine field to the settings file.[14] The settings you overwrote earlier already include the line below. There is nothing more to change.
"statusLine": { "type": "command", "command": "echo Organizing Corner Cafe" }When we actually ran it, this appeared below the input box:
Organizing Corner CafeUntil you accept the folder trust dialog, the status line stays blank.[15] Because it is a feature that runs shell commands, it follows the same trust rules as hooks. The warning in the previous section applies here too.
You can also make one by writing the look you want in words after /statusline.[16] This guide did not try this feature.
Quick check
The status line is empty. What is one cause the docs mention?
Output Styles and Themes
You do not need to change these from the start. Pull them out when you need them. This guide did not try these two; this is what the official docs describe.
An output style (Output style) sets the role, tone, and format for every answer in a session. For example, Concise leads with the result and cuts down introductions and recaps.[17]
/output-style ConciseA theme is the colors. If the text on screen is hard to read, use /theme to pick colors that fit your terminal.[18]
Quick check
Which command can you use when you want answers short, with the result first?
Try It Yourself
- Leave with
/exitand paste the settings box in the terminal. - Start
claudeand check thatOrganizing Corner Cafeappears below the input box. - Type
/hooks, check that the hook appears underPostToolUse, and close it with Esc. - Send the hook-test request, then use
! cat changelog.txtto see whether a line was added.
Ask yourself: Did the hook really run? Answer by opening changelog.txt yourself, not by trusting Claude's answer.
Summary
- A hook is a command Claude Code runs at set points. Use it for things that must happen.
/hooksis view-only. You create and edit hooks in the settings file.- Do not use trailing commas or comments in the settings file's JSON.
- For a folder someone gave you, read
.claude/settings.jsonbefore starting (this guide's judgment). - Change the status line, output style, and theme only when you need to.
Glossary
| Term | One-line meaning |
|---|---|
| Hook | A command that runs automatically at set points |
PostToolUse | The point after a tool is used |
PreToolUse | The point before a tool is used |
| JSON | A text format used in settings files |
| Status line | A line at the bottom of the screen showing your command's output |
| Output style | A bundle of role, tone, and format for answers |
Finished this chapter?
Progress is saved only in this browser. See your progress on the full table of contents.
Next chapter: Chapter 12. Parallel Work and Remote
References (18)
Claude Code official docs, "Automate actions with hooks". "Hooks are user-defined shell commands." / "Claude Code runs them at specific points in its lifecycle, which gives you deterministic control: certain actions always happen rather than relying on the LLM to choose to run them." code.claude.com (checked on 2026-11-06) ↩︎
Claude Code official docs, "Output styles". "For something that has to happen every time, such as formatting after each edit or blocking a command, use a hook." code.claude.com (checked on 2026-11-06) ↩︎
Claude Code official docs, "Automate actions with hooks". "To create a hook, add a
hooksblock to a settings file." code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Automate actions with hooks". "
PostToolUsehooks can't undo actions since the tool has already executed." / "Before a tool call executes. Can block it" code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Automate actions with hooks". "You can also ask Claude to write the hook for you by describing what you want in the CLI." code.claude.com (checked on 2026-11-06) ↩︎
The
.claudefolder is a protected path, so writes to it are not simply approved. In Manual mode a permission prompt appears, and in auto mode a separate AI that checks actions in advance makes the call. Claude Code official docs, "Choose a permission mode". "Writes to a small set of paths are never auto-approved" / theautorow of the table: "Routed to the classifier" code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Automate actions with hooks". "If your settings file already has a
hookskey, addNotificationas a sibling of the existing event keys rather than replacing the whole object." code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Automate actions with hooks". "Type
/hooksat the Claude Code prompt to open the hooks browser." / "Run/hooksand confirm the hook appears under the correct event" code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Automate actions with hooks". "Verify your JSON is valid: trailing commas and comments aren't allowed" code.claude.com (checked on 2026-11-06) ↩︎
Claude Code official docs, "Automate actions with hooks". The sharing column in the
.claude/settings.jsonrow: "Yes, can be committed to the repo" code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Run Claude Code programmatically". "Without
--bare, a-psession runs the hooks in a project's.claude/settings.jsonand connects the servers in its.mcp.json, even in a folder you've never trusted." code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Plugins overview". "Whatever the tier, a plugin you install can run code with your user privileges." code.claude.com (checked on 2026-11-06) ↩︎
Claude Code official docs, "Customize your status line". "The status line is a customizable bar at the bottom of Claude Code that runs any shell script you configure." code.claude.com (checked on 2026-11-06) ↩︎
Claude Code official docs, "Customize your status line". "Add a
statusLinefield to your user settings (~/.claude/settings.json, where~is your home directory) or project settings." code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Customize your status line". "Until you accept the workspace trust dialog, the status line stays blank." / "Because
statusLineexecutes a shell command" code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Customize your status line". "The
/statuslinecommand accepts natural language instructions describing what you want displayed." code.claude.com (checked on 2026-11-06) ↩︎Claude Code official docs, "Output styles". "An output style is a set of instructions that sets Claude's role, tone, and response format for every response in a session." / "Responses lead with the result and leave out preamble, narration, and recaps" code.claude.com (checked on 2026-11-06) ↩︎
Claude Code official docs, "Configure your terminal for Claude Code". "Use the
/themecommand, or the theme picker in/config, to choose a Claude Code theme that matches your terminal." code.claude.com (checked on 2026-11-06) ↩︎