Agentic AI & Claude Code

Simple: A recipe tells you how to make dinner. A cook makes dinner. Both know the same things — only one of them comes back with a plate.

Technical: The model is unchanged. What changes is the harness around it: its output is routed to tools, and the tools’ results are fed back in, so it can observe the consequences of an action and act again.

Simple: Text a friend about your broken bike and you get instructions. Hand them the bike and you get back a working bike.

Technical: Same weights, different loop. A chatbot’s context holds only your turns; an agent’s also holds tool output, so its next prediction is conditioned on the real state of your files rather than on what it remembers about projects in general.

Simple: It is how you find a leak under a sink: look, tighten something, run the tap, look again. Nobody fixes it in one move, and the tap is what tells you whether you are done.

Technical: The loop closes on an external signal — the test’s exit code — not on the model’s own confidence. That is the whole difference between iterating and repeating: the environment, not the model, decides whether Verify passed.

Simple: Like watching over someone’s shoulder while they work. You see every step they take, not just the finished result they hand you.

Technical: Every line is a tool call and the output it returned, appended to the conversation. There is no hidden scratchpad here — this transcript is what the model is reasoning over on the next turn.

Simple: A kitchen already has a knife, a hob and a tap before you buy a single gadget. These six are that kitchen — nothing to install, nothing to configure.

Technical: Each is a function the model may call, with a declared schema for its arguments. Read, Edit, Write, Glob and Grep are deliberately narrower than Bash: a narrow tool fails loudly on the wrong input instead of doing something plausible and unintended.

Simple: A kettle plugs into any wall socket because everyone agreed on the shape of the socket. Nobody manufactures a kettle-shaped hole in the wall.

Technical: MCP standardises the interface — how a server lists its tools, how a tool is invoked, how a result comes back. A server author targets the protocol once instead of writing an integration per AI product (Anthropic, 2024).

Simple: Ordering in a restaurant. You talk to the waiter, the waiter talks to the kitchen, and you never walk in and shout at the chef.

Technical: JSON-RPC over stdio or HTTP with a client in the middle. The client owns discovery, the permission prompt and the log, which is why no server ever gets to talk to the model directly — and why a compromised server is contained rather than catastrophic.

Simple: The other tools are specialised kitchen gadgets; the shell is the whole workshop. It is powerful for exactly the reason it needs supervision.

Technical: Bash makes the tool surface unbounded — any binary on your PATH becomes callable, and the agent cannot know in advance what each one does. That is why the permission gate sits on this tool rather than on a list of forbidden commands.

Simple: You can open a jar with a hammer. A jar opener is less exciting and breaks less glass.

Technical: Edit requires a unique match and errors when it finds none or two, so an ambiguous change fails instead of silently hitting the wrong line. A sed one-liner would have edited both and reported success.

Simple: A recipe card you wrote once because you make the same dish every Sunday. You are not inventing it again each week.

Technical: A skill is a stored prompt template invoked by name. The value is not that the model could not do it unprompted — it is that the instructions are identical every time, so the output is reproducible instead of re-improvised.

Simple: The note taped inside a shared kitchen cupboard: bins go out Tuesday, the oven runs hot. Nobody has to be told twice.

Technical: The file is read into context at the start of every session, so project conventions arrive as instructions rather than as something the model has to infer from the code — and inference is where a plausible-but-wrong convention gets invented.

Simple: A desk you cannot make bigger. Every new document you spread out means an older one has to be filed or binned.

Technical: The context window is a fixed token budget shared by instructions, files and tool output. These four commands are the only levers over what occupies it: add deliberately (@path), summarise (/compact), seed (/init), or persist outside it (Memory).

Simple: Picking a courier. Same city, same parcel — a bicycle, a van and a lorry are not ranked best to worst, they fit different jobs. Sending everything by lorry is not care, it is waste.

Technical: Model and effort are orthogonal, and coupling them is the error — high effort does not rescue a poorly-scoped task, and the strongest model does not compensate for a context you filled with noise. Effort buys reasoning depth before acting; the model sets the ceiling on what that reasoning can reach.

Simple: Two different ways to slow a decision down. One is asking a builder for drawings before they knock a wall through; the other is asking them to take a proper look first.

Technical: They act on different layers. Plan Mode is a permission constraint — the write tools are simply unavailable. Thinking Mode spends more output tokens on reasoning before the answer. You can run either alone, and they cost differently for that reason.

Simple: The interlock on a microwave door. It is not asking the microwave to behave — it physically cannot run with the door open.

Technical: A hook is deterministic code on a lifecycle event, outside the model’s control. A PreToolUse hook that exits non-zero cancels the call, which is a guarantee; an instruction in CLAUDE.md saying “never do this” is only a strong preference.

Simple: A note on the fridge saying check this before you cook chicken is useless unless it says chicken. Otherwise you either check everything or check nothing.

Technical: matcher is the event filter. It is matched against the tool name, so "Bash" scopes the hook to shell calls and "" fires on every occurrence of that event — including the ones your script was not written to handle.

Simple: The difference between a colleague who reads your work and one who also files the paperwork, chases the reviewer and closes the ticket.

Technical: None of this is a new capability — it is the same Bash and MCP tools pointed at a version-control host. What makes it automatable is -p (print mode): no interactive prompt, so it runs where there is no terminal to answer one.

Simple: Watching six different repairs before you attempt one yourself. The tasks differ; the rhythm of the work does not.

Technical: These transcripts are hardcoded, not live. What is worth reading across all six is what each loop converges on: a bug fix ends when a test passes, a refactor ends when behaviour is unchanged, a review ends when there is nothing left to say.

Simple: A “leaving the house” routine instead of separately remembering keys, lights and the back door. The steps were never hard; the order and the not-forgetting were.

Technical: A workflow encodes sequencing and failure handling that a single prompt does not: deploy only if tests pass, notify only if deploy succeeded. That ordering constraint is the artefact, not the individual commands.

Simple: Every appliance has more buttons than anyone presses. These five tabs are the ones worth finding.

Technical: The flags sort into three jobs: what the model is told (--system-prompt, --append-system-prompt), what it is permitted to do (--allowedTools, --permission-mode), and what shape comes back (--output-format, --json-schema). Learn the three jobs, not the fifty flags.

Simple: A bucket brigade: each person does one thing and hands the bucket on. None of them needs to know where the fire is.

Technical: -p turns claude into an ordinary Unix filter — reads stdin, writes stdout, exits with a status code. That is why it composes with cat, git diff and a CI runner without any of them knowing an AI is in the pipe.

Simple: Adding a channel to a TV. Either you tune to a broadcast someone else runs, or you plug a box in beside your own sofa.

Technical: --transport decides which, and the difference is lifetime, not just address: an HTTP server is already running and you authenticate to it with --header; a stdio server is a child process Claude Code starts and stops for you, configured with -e.

Simple: A dial that runs from “ask me before every turn” to “just drive.” Where you set it should depend on how far the car can travel before you notice.

Technical: The gate sits at the tool-call boundary, evaluated after the model has decided on a call and before it executes — so a mode narrows what happens, never what the model may propose. bypassPermissions removes the gate, which is only defensible when the blast radius is already bounded by a sandbox.

Simple: A printed timetable at a bus stop. Accurate the week it went up, and worth checking against the live board.

Technical: Read these three as one direction rather than three features: each buys back a scarce resource. ToolSearch defers tool descriptions to save context; --agents narrows the tool set to reduce ambiguity; -w isolates the filesystem to contain mistakes. Time-sensitive: verify against claude --help.

Simple: A library does not post every book to you on the off chance. It sends you the catalogue, and you request the one you want.

Technical: Deferred registration: the server advertises tool names and withholds the full schemas until ToolSearch asks. The saving is in input tokens on every single turn, not once at startup — which is why it compounds over a long session.

Simple: Assembling flat-pack furniture: three unglamorous steps, then the part you actually wanted.

Technical: Steps 1, 2 and 4 are per-session. Step 3 is the only one that persists — skip it and you re-explain the project on every future run, which is both slower and the main source of conventions being guessed at.