Nov '25 (edited) • Template Agent Diary
Building the Brain: How Hooks Turn an LLM into an Agent
Without structure, an LLM is just a probabilistic engine. It takes a "random walk" through a Markov chain of potential actions. There is no guarantee of how it will behave the next time.
This is the difference between an LLM and an Agent.
An LLM is just the engine. It gets lucky sometimes, and other times it fails.
An Agent is that engine plus a Brain.
### The Agent's Brain: The `.claude/` Directory
When you look at the Template Agent we are building, you'll see a `.claude/` directory. This isn't just a folder for settings. This is where your agent's knowledge, instructions, and context live.
And the most critical part of this brain? Hooks.
### What Are Hooks?
Technically, hooks are just logic files that live in your agent's brain.
But conceptually? Hooks are your agent's learned reflexes.
They are the dynamic pathways that sit *between* the LLM's decisions. They listen for specific events—like when you ask a question, or before the agent uses a tool—and they inject the best directive or instruction right into the context.
Previously, with our Markov chain model with key states (e.g., Respond, Think, Tool call (16 built-in), Ask for permission, Create a task, Compact, stop), the transitions were mainly probabilistic and oversensitive to the context. But, with hooks placed around all these events/actions, organize all the transitions and a space to define reproducible behavior.
As you would expect from a human personal assistant to learn and grow with experience, the hook layer is where the agent will grow. (and some other places -- a topic for later)
Instead of the LLM guessing what to do, the Hook ensures it knows what to do.
### Creating Stable Directions
Imagine you want your agent to *always* check your specific style guide before drafting an email.
* The LLM Way (Getting Lucky): You ask it nicely in the prompt. "Please check my style guide." Maybe it remembers. Maybe it hallucinates. You are relying on luck.
* The Agent Way (Stable Direction): You have a hook that automatically injects that style guide into the context whenever the agent is working on an "email". The LLM doesn't have to guess. The pathway is fixed.
### The 9 Control Units
To build this brain, we have exactly 9 "Control Units" (Hooks) available to us. Each one governs a specific moment in the agent's thought process:
1. SessionStart: Triggered when starting a new session, after a compact operation, and a few other initialization events.
2. UserPromptSubmit: Triggered when you submit a prompt to the agent.
3. PreToolUse: Triggered *before* the agent uses a tool (can also block the tool use).
4. PostToolUse: Triggered *after* the agent uses a tool.
5. PermissionRequest: Triggered when the agent needs permission to use a tool.
6. Notification: Triggered when the agent needs to notify you (often alongside a permission request).
7. SubagentStop: Triggered when a sub-agent finishes its task.
8. PreCompact: Triggered when the context is full (or manually requested) to summarize memories and free up space.
9. Stop: Triggered when Claude Code is done working.
*Note: You can have as many hooks as you need. Hooks with the same trigger will run in parallel.*
In the next few posts, we will dive into each of these units and see how to program them.
### Growing Your Agent
Here is where it gets exciting.
Because Claude Code knows about its own hook system, it can grow its own brain.
As you work with the Template Agent, you aren't just using it; you are teaching it. When you correct it, or when you define a new workflow, the agent can update its own hooks. It adds that new logic to its `.claude/` directory.
It gains experience.
This is our goal: To build an agent that doesn't just "act" like it works, but actually improves over time because it has this external context layer managing it.
In the next few posts, we'll see this in action. We will stop relying on luck and start building a brain.
2
1 comment
Building the Brain: How Hooks Turn an LLM into an Agent
powered by
skool.com/claude-agents-engineering-4513
Engineer your own AI assistant through conversation, not code.
Join professionals building custom CLI agents for their work. Opencode, Claude, Gemini
Suggested communities
Powered by