How Claude Code Actually Works: The Tool System

Summary:

1. Claude Code is a tool-calling agent, not a chatbot. Every prompt fires a named tool.
2. The public docs list ~40 tools; the community counted ~60; most developers use six.
3. Map each prompt shape to its tool, then prompt to skip the steps you can skip.
4. Three facts (exact-string edits, resetting shell state, three subagent modes) change how you work.

Claude Code architecture tools are what the source leak actually exposed. Someone reverse-engineered what ships inside the package, posted it, and it went viral. People expected a chatbot with extra steps. What they found was an agent framework: a tool system, a permission model, a context manager, and a planning pipeline. Once you can see which tool fires for each prompt, you stop fighting the tool and start steering it. This is the map.

What is Claude Code’s architecture?

Claude Code is a tool-calling agent. It does not “generate an answer” the way a chat model does. It decomposes your request into a sequence of named tool calls, each passing through a permission check and operating inside a managed context. The community catalogued around 60 internal tool names; the public docs name about 40; most developers use six (read a file, edit a file, run a command, search, write, explain).

Tool names are the exact strings used in permission rules and hook matchers. Here are the core ones, from the tools reference:

Every prompt maps to a tool call

The fastest way to read the architecture is to watch what fires for each request. Six prompts, the exact tool calls behind them, and how knowing changes your prompt:

Those six tasks fan out to nine tool calls (the typo fix is a Read then an Edit; OAuth spawns two agents). Every action is one named call. Nothing is magic. The search task, for example, fires exactly this:

Claude Code calls: Grep
  pattern: "validateUser"
  path: "src/"

Three files come back with line numbers. Help it narrow and that call gets cheaper.

The three facts that change how you prompt

Edit is an exact string replacement, not a rewrite. When you ask for a change, Claude Code finds a specific string and swaps it. The rest of the file is untouched:

Claude Code calls: Edit
  file_path: src/lib/errors.ts
  old_string: "Something went wrong"
  new_string: "Request failed"

If that string is not unique, the edit fails and Claude Code grabs more surrounding context to make the match unambiguous. That is why you sometimes see it target a 10-line block for a 1-line change. So when an edit could be ambiguous, name the location: “change the error message in the createUser function” beats “change the error message” when there are five of them.

Shell state does not persist between Bash calls. If Claude Code runs export MY_VAR=hello and then echo $MY_VAR in a separate call, the variable is empty. The working directory persists; environment variables and aliases reset. That is why a setup-then-build has to chain in one call:

npm install express-rate-limit && npm run build

The Agent tool has three modes. A read-only research subagent scans the codebase fast and can’t edit. A Plan agent designs an approach, read-only. A general-purpose agent has full access and does the work. For a complex task, spell it out: “use a read-only research subagent to map the current auth system, then plan the OAuth addition, then build it.” You are telling Claude Code to use its deepest feature instead of guessing at it.

What should you actually do?

• Run the six prompts above on a real project and watch the tool call in each output. Confirm you can predict the tool before it fires.
• When you ask for an edit in a file with repeated strings, name the function or the line. You save the failed-match retry.
• When you search, narrow the path. Grep(pattern, path: "src/routes/") is cheaper than scanning the whole repo.
• For anything multi-step, name the subagent modes (research, then Plan, then build). Vague prompts make the planner guess; specific ones eliminate the guesses.
• If a long session feels slow or Claude Code keeps re-reading files, start a fresh one. Compression dropped the details, and a clean context reads precisely.

The bottom line

• Claude Code is not a chatbot. Read reads, Edit replaces strings, Grep searches, Bash runs, Agent spawns subagents. Every action is a named tool call through a permission gate.
• The diff between using Claude Code and mastering it starts with knowing which tool fires, because that is what lets you write the prompt that hits on the first attempt.
• The specific tool names will shift as the tool evolves. The understanding of how a tool-calling agent works is the part that lasts, and it is the part the source leak could not hand anyone who had not already watched it run.