How Claude Code Works — A Beginner’s Deep Dive

by

Most people who start using Claude Code treat it like a smarter version of a search box. They type a request, get some code back, paste it in, and move on. That works — for a while. But the moment something goes wrong, or a task gets complex, or the output isn’t quite right, that mental model breaks down completely. You’re left confused, not knowing why Claude Code did what it did or how to steer it differently.

This guide fixes that. Understanding what’s actually happening inside a Claude Code session — the loop it runs, the tools it reaches for, the way it reads your files and manages memory — turns you from a passive passenger into someone who can genuinely direct the tool. You’ll get better results, faster, with fewer surprises. You’ll also stop wasting tokens on things that don’t work. That’s worth ten minutes of your time.

## 📋 TL;DR

– Claude Code runs an agentic loop — it receives your prompt, picks a tool, executes it, reads the result, and repeats until the task is done.
– It has six core tools: Read, Write, Edit, Bash, Glob, and Grep. Every action Claude Code takes uses one of these.
– The context window is Claude Code’s working memory — everything in a session accumulates there, and managing it well is the key to long, productive sessions.
– CLAUDE.md is the single most important file you can create. Claude reads it at the start of every session and uses it to understand your project.
– Plan Mode makes Claude think before it acts — essential for complex tasks with serious consequences.
– The permission system controls what Claude is allowed to do without asking you first. Understanding it stops frustrating approval prompts.
– Every section below maps to a cluster article that goes deeper — use this page to understand the picture, then follow the links for hands-on practice.

Table of Contents

The Agentic Loop — What Actually Happens When You Hit Enter

When you type a prompt into Claude Code and press Enter, most people imagine something like a search engine: request in, answer out. The reality is completely different — and understanding it changes how you use the tool.

Claude Code runs what’s called an agentic loop. An agent is a system that takes a goal, figures out what steps are needed, executes those steps, checks the results, and adjusts — all on its own, without you guiding every move. The loop is the engine that makes that possible.

Here’s how a single loop cycle works:

  1. Claude receives your prompt along with the full conversation history so far.
  2. Claude decides what to do next. It looks at your request, thinks about what information it needs, and picks an action — usually calling one of its tools (more on those in a moment).
  3. The tool executes. Claude reads a file, runs a command, or makes an edit.
  4. The result comes back into the conversation. Claude sees what the tool returned — the file contents, the command output, the error message.
  5. Claude decides what to do next based on that result. If the task is done, it tells you. If not, it loops back to step 2 and takes another action.

This cycle repeats — sometimes two or three times for a simple task, sometimes dozens of times for a complex one — until Claude decides the goal is complete.

The practical implication is huge: Claude Code is not answering your question. It’s solving your problem. A chatbot gives you a response. Claude Code takes actions. That’s why it can do things like “find the bug in my app, trace it back to its source across multiple files, fix it, and run the tests to confirm” — all from a single prompt. Each step in that process is one cycle of the loop.

This also explains why Claude Code sometimes does more than you expected, or takes a path you didn’t anticipate. It’s making autonomous decisions inside the loop. You give it a goal; it figures out the route. Later in this guide, you’ll learn about Plan Mode — a way to see and approve the route before Claude starts driving.

Diagram showing the agentic loop as a cycle: Prompt → Decision → Tool Call → Result → Decision → next Tool Call, with an arrow looping back until “Task Complete”

[How to Write Your First Claude Code Prompt]

[Claude Code Session Management]

The Six Tools Claude Code Uses to Act

Claude Code doesn’t write code by magic. Every action it takes — reading a file, making an edit, running your tests — uses one of six specific tools. Understanding what each tool does helps you predict what Claude will do, write better prompts, and configure your permissions sensibly.

Read — Views the contents of any file on your system. This is how Claude Code learns what’s in your project. Before it edits anything, it almost always reads the relevant files first. Reading is low-risk; it doesn’t change anything.

Write — Creates a new file or completely overwrites an existing one. Claude uses this when creating files from scratch. It’s higher risk than Read because it can overwrite something important.

Edit — Makes a targeted change to an existing file. Rather than rewriting the whole thing, Edit finds the specific section Claude wants to change and updates only that part. This is the most common tool Claude uses when fixing or updating code.

Bash — Runs a shell command on your computer. This is the most powerful (and most sensitive) tool. Bash is how Claude Code runs your tests, installs packages, starts servers, checks Git status, and executes any other command-line operation. Because Bash has full system access, it’s the tool that gets the most attention from the permission system.

Glob — Finds files matching a pattern. If you ask Claude to “find all the TypeScript files in my project,” it uses Glob to locate them by pattern (*.ts, for example). This is how Claude navigates large codebases without reading every file one by one.

Grep — Searches for text inside files. If Claude needs to find every place in your codebase where a function is called, or every file that imports a specific module, it uses Grep. It’s a fast search, not a full file read.

These six tools combine in the agentic loop to handle almost anything. A request like “refactor this function and make sure the tests still pass” might look like: Grep (find all call sites) → Read (understand each file) → Edit (update the function) → Edit (update call sites) → Bash (run the test suite) → Read (check the output) → done.

💡 Pro Tip: When Claude Code seems to be going slowly or taking an unexpected path, you can ask it to explain its plan before it starts. Type “Before you do anything, tell me which files you’re going to read and what changes you’re going to make.” This gives you visibility into the tool sequence it’s planning, so you can redirect it before it starts executing.

How to Accept or Reject Claude Code’s Changes

Claude Code Keyboard Shortcuts

A Claude Code session showing individual tool calls being displayed — e.g., “Reading file: src/auth/login.js” then “Editing file: src/auth/login.js” — so readers can see the tools in action in the terminal output

The Context Window — Claude Code’s Working Memory

Here’s the most important concept for understanding why Claude Code behaves the way it does in longer sessions: the context window.

The context window is Claude’s working memory — everything it can “see” at once during a session. This includes your original prompt, every tool result (the contents of files it read, command outputs, error messages), every response it has given you, and any instructions from your CLAUDE.md file. All of it accumulates in the context window as your session progresses.

Claude Code’s context window can hold up to 1 million tokens. A token is roughly 4 characters of text, or about 0.75 words. A million tokens sounds enormous — and it is. It’s enough to hold an entire medium-sized codebase. But in a long, complex session with lots of file reads and back-and-forth, that limit can still come under pressure.

The key thing to understand: the context window does not reset between your messages. Every message you send, and every response Claude gives, adds to the pile. This is why Claude Code gets more knowledgeable about your project as a session goes on — it’s building up a detailed picture in its working memory. It’s also why starting a new session means starting from scratch. All that accumulated understanding is gone.

When the context window gets close to full, Claude Code uses a process called compaction. It summarizes older parts of the conversation into a compressed form to free up space, then continues working. You can also trigger this manually with the /compact command. During compaction, some detail from early in the session is simplified — which is why very long sessions can occasionally produce slightly less precise responses toward the end.

You can check how much of your context window is in use at any time by typing /context inside a session. This shows you a breakdown of what’s consuming space.

💡 Pro Tip: The single best way to extend the useful life of your context window is to keep your CLAUDE.md concise. A bloated CLAUDE.md that’s hundreds of lines long eats into your context budget at the start of every session before you’ve even typed your first prompt. Keep it focused: coding conventions, key architectural decisions, and anything Claude must not do. Cut the rest.

[What Are Tokens in Claude Code?]

[How to Give Claude Code Context]

CLAUDE.md — How to Give Claude Persistent Memory

Claude Code has no memory between sessions. Start a new session tomorrow and it won’t remember anything you discussed today. For most people, this is the single most frustrating thing about the tool — until they discover CLAUDE.md.

A CLAUDE.md file is a plain text file you put in the root folder of your project. Claude Code reads it automatically at the start of every session. Whatever you put in it is always in Claude’s context when it’s working on your project. Think of it as a briefing document Claude reads before starting work every single day.

What goes in CLAUDE.md? The things you’d otherwise have to re-explain every session:

  • What the project does and who it’s for
  • Your tech stack (frameworks, languages, databases)
  • Coding conventions (indentation, naming, file structure)
  • What Claude should not do (don’t touch the payments module, don’t use console.log)
  • How to run your tests and what passing looks like
  • Key architectural decisions and why you made them

A well-written CLAUDE.md transforms Claude Code from a tool that needs re-briefing every time into something that feels like a team member who already knows your project. The difference in output quality is dramatic.

CLAUDE.md also works at a higher level. You can put a CLAUDE.md in your home folder (~/.claude/CLAUDE.md) to give Claude instructions that apply to every project on your machine — things like your preferred coding style, languages you work in, and general rules that never change. And you can use it inside subdirectories to give more specific instructions for specific parts of a project.

Plan Mode (covered next) also respects CLAUDE.md. If you put instructions like “never modify the auth module without explicit permission” in your CLAUDE.md, Plan Mode will honor those constraints when building its execution plan.

[How to Give Claude Code Context]

[Claude Code Session Management]

A sample CLAUDE.md file open in a text editor, showing sections like “About this project,” “Tech stack,” “Coding conventions,” and “Off-limits files” — something readers can immediately model their own CLAUDE.md on

Plan Mode — Think First, Then Act

Here’s a scenario every Claude Code user eventually hits. You give Claude a complex task — something like “refactor the user authentication system.” Claude jumps in, starts making changes across a dozen files, and 20 minutes later you have a broken build, confused logic, and a hard-to-untangle mess.

The problem isn’t Claude Code. The problem is that it started acting before it fully understood the scope of the task. Plan Mode exists specifically to prevent this.

Plan Mode is a session setting that forces Claude to fully think through and map out a task before making any changes. In Plan Mode, Claude’s write tools are physically blocked — it literally cannot edit, create, or modify files. It can only read and reason. It produces a detailed plan: what files it will touch, what changes it will make, what commands it will run, and in what order.

You review that plan. If it looks right, you approve it and Claude executes. If something’s wrong — if it’s about to touch a file it shouldn’t, or take an approach you don’t like — you tell it, and it revises the plan before touching anything.

You can activate Plan Mode in three ways:

  • Type /plan before your prompt inside a session
  • Press Shift+Tab twice to toggle into Plan Mode
  • Start a session with the flag claude --permission-mode plan

Plan Mode uses extra tokens — roughly 30 seconds of additional processing per task — because Claude is doing a full reasoning pass before acting. That overhead is almost always worth it for complex tasks. For simple, single-file edits, normal mode is fine.

Claude Code has three main modes:

  • Normal mode** — Claude asks for approval before making changes. This is the default and the right starting point for beginners.
  • Plan Mode** — Claude reasons first, then you approve the plan before anything happens. Best for multi-file tasks and anything hard to reverse.
  • Auto-Accept Mode** — Claude applies changes without asking. Fast, but only appropriate when you completely trust the output.

Plan Mode Explained

[Claude Code Modes — Normal, Plan, Auto]

The Permission System — Who Controls What

Every time Claude Code wants to take an action — read a file, edit code, run a command — the permission system decides whether it needs to ask you first, or whether it can go ahead automatically.

Understanding this system stops two common frustrations: getting interrupted by approval prompts on every trivial action, and not realizing that Claude has permission to do something potentially destructive.

At the broadest level, tools fall into two risk categories:

Low-risk tools — Read, Glob, Grep — are generally auto-approved by default. They can only look at things, not change them.

Higher-risk tools — Write, Edit, Bash — require your approval by default, because they can modify files or execute commands on your system.

You can customize this using a file at .claude/settings.json inside your project. In this file, you create an allow list (tools that never need approval) and a deny list (tools that are always blocked). For example, you might auto-approve git status and npm run test (safe operations you run constantly) while permanently blocking rm -rf and any network commands that could exfiltrate data.

The four permission modes:

  • Default** — Reads are free; writes and commands prompt for approval. The right mode for most sessions.
  • Accept Edits** — File edits are auto-approved; Bash commands still prompt. Good when you’ve already reviewed the plan and want Claude to implement without interruption.
  • Read-Only** — Claude cannot write or execute anything. Useful for code review and safely exploring an unfamiliar codebase.
  • Bypass Permissions** — Everything is auto-approved. Only for automated pipelines with no human in the loop — not for everyday use.

You can view your active permission rules at any time during a session by typing /permissions.

💡 Pro Tip: Build your allow list gradually rather than all at once. Run a few normal sessions, note which Bash commands Claude keeps prompting you to approve, and add the safe, repetitive ones to your allow list in .claude/settings.json. After a week of this, approval prompts nearly disappear — and the ones that do appear are flagging genuinely risky actions worth your attention.

How to Accept or Reject Claude Code’s Changes

[Claude Code Modes — Normal, Plan, Auto]

How Claude Code Reads Your Codebase

One of Claude Code’s most impressive capabilities is understanding your entire project — not just the one file you paste in, but how everything fits together. How does it actually do this?

The answer is a combination of smart tool use and the context window. When you launch Claude Code in a project directory, it doesn’t immediately read every file. That would be wasteful and slow. Instead, it starts with a high-level survey using Glob to map the file structure — what folders exist, what files are where, what the project layout looks like.

From that map, Claude makes educated guesses about what’s important. It reads configuration files (like package.json, requirements.txt, or tsconfig.json) to understand your tech stack. It reads your CLAUDE.md if you have one. It reads the entry points — the main files that everything else connects to. Only then does it start reading deeper into the files actually relevant to your task.

When you ask about a specific problem, Claude uses Grep to find relevant code quickly — searching for function names, error messages, or specific imports — rather than reading every file top to bottom. This is why Claude Code can navigate a large codebase efficiently: it doesn’t read everything, it reads strategically.

For very large projects, Claude Code can also spawn sub-agents — isolated instances with their own context windows — to explore different parts of the codebase in parallel. The main agent sends a sub-agent to investigate the frontend, another to the API layer, another to the database schema. Each sub-agent does its exploration and returns a compact summary to the main agent. This way, Claude can understand a project that’s too large to fit in a single context window.

This is also why giving Claude useful starting points matters. If you’re working on a specific feature, mention which files are relevant at the start of the session. Claude still does its own exploration, but your guidance helps it prioritize correctly from the beginning.

How Claude Code Reads Your Codebase

[How to Use Claude Code in VS Code]

[How to Use Claude Code in JetBrains]

Common Beginner Mistakes and How to Fix Them

Mistake 1: Starting a new session every time something goes wrong

The problem: Claude Code gives you something that’s not quite right. You quit, start fresh, and try again — losing all the context Claude had built up about your project.

The fix: Stay in the session. Tell Claude what’s wrong. Paste the error message. Claude can see everything that happened in the session so far and can diagnose the problem much better from inside the existing context than starting cold. Use /clear to reset the conversation if you genuinely want a fresh start, but keep the session running so CLAUDE.md stays loaded and Claude keeps its project awareness.

Mistake 2: Ignoring the context window until things go weird

The problem: Halfway through a long session, Claude Code starts giving less precise answers or seems to “forget” things you told it earlier. You don’t know why.

The fix: Type /context periodically during long sessions to check how full your context window is. If you’re approaching the limit, run /compact to compress older parts of the conversation. Better yet, start sessions with a focused CLAUDE.md so Claude always has your project’s key facts available even after compaction flattens the early conversation.

Mistake 3: Skipping Plan Mode for complex tasks

The problem: You give Claude a big, multi-file task, it jumps straight into execution, takes an approach you didn’t anticipate, and you spend an hour untangling the results.

The fix: For any task touching more than two or three files, or any task with consequences that are hard to reverse (database changes, auth logic, deployment config), use Plan Mode. Type /plan before your prompt. Spend two minutes reviewing Claude’s proposed approach. You’ll save far more time than you spend.

Mistake 4: Not having a CLAUDE.md file

The problem: You’re re-explaining your project’s tech stack, your coding conventions, and your off-limits files at the start of every single session.

The fix: Create a CLAUDE.md in your project root today. Even a ten-line version is dramatically better than nothing. Include what the project does, your main stack, one or two key coding rules, and any files or folders Claude should never touch. You’ll notice the difference in the very next session.

Mistake 5: Approving changes without reading the diff

The problem: Claude Code proposes an edit and asks for your approval. You click yes without reading what it’s about to do. The change is fine — until the one time it isn’t, and you’ve already approved it.

The fix: Before you approve any edit, read the diff — the side-by-side view of what’s changing. Claude Code displays this before making any file modification. It takes 20 seconds. If something looks unexpected, ask Claude to explain its reasoning or propose a different approach. This habit alone prevents most painful Claude Code surprises.

Quick Reference Cheatsheet

**Concept** **What it is / What to do**
Agentic loop Claude’s cycle: decide → tool → result → repeat until done
Read Tool for viewing file contents (safe, no changes made)
Write Tool for creating new files or overwriting existing ones
Edit Tool for targeted changes to a specific part of a file
Bash Tool for running shell commands (most powerful, most sensitive)
Glob Tool for finding files by pattern (e.g., all `*.py` files)
Grep Tool for searching text inside files
Context window Claude’s working memory — everything in the current session
`/context` Check how much of your context window is currently in use
`/compact` Compress older session content to free up context space
`/clear` Clear the conversation and start fresh within the same session
CLAUDE.md Your project briefing file — Claude reads it every session automatically
`~/.claude/CLAUDE.md` Global CLAUDE.md — applies rules to every project on your machine
Plan Mode Activate with `/plan` — Claude thinks and plans before it acts
`Shift+Tab` twice Toggle Plan Mode on/off inside a running session
`/permissions` See what’s currently allowed and denied in your session
`.claude/settings.json` Where you set permanent per-project permission rules
Sub-agents Isolated Claude instances for parallel codebase exploration
`/model` Switch between Sonnet and Opus mid-session
`/cost` See your token usage for the current session

What to Learn Next

Now that you understand what’s happening under the hood, every other Claude Code topic clicks faster. Here’s where to go next:

Start here — put this knowledge into practice:

  • [How to Write Your First Claude Code Prompt] — Now that you know about the agentic loop and tools, your first prompts will be significantly more effective.
  • How Claude Code Reads Your Codebase — A deeper look at the reading strategies Claude uses and how to help it navigate large projects.
  • [How to Give Claude Code Context] — Everything about CLAUDE.md, session context, and making sure Claude always has what it needs to work well.

Master the modes:

  • Plan Mode Explained — The complete guide to Plan Mode: when to use it, how to read a plan, and how to modify it before Claude acts.
  • [Claude Code Modes — Normal, Plan, Auto] — All three modes covered with concrete examples of when each is the right choice.
  • How to Accept or Reject Claude Code’s Changes — How the diff view works, what to look for, and how to push back when something’s not right.

Work smarter:

  • [What Are Tokens in Claude Code?] — Tokens explained properly: what they are, how they’re counted, and why they affect your plan choice.
  • [Claude Code Session Management] — How to continue sessions, fork them, and manage long-running work across multiple days.
  • Claude Code Keyboard Shortcuts — The shortcuts that save the most time in everyday use.

Use Claude Code in your IDE:

  • [How to Use Claude Code in VS Code] — Setting up and using Claude Code directly inside Visual Studio Code.
  • [How to Use Claude Code in JetBrains] — The same for IntelliJ, PyCharm, WebStorm, and other JetBrains IDEs.

Key Takeaways

  • Claude Code runs an agentic loop**, not a chat response. It takes actions — using tools to read files, write code, and run commands — cycling through them repeatedly until your task is complete. Understanding the loop means understanding why Claude does what it does.
  • Six tools power everything**: Read, Write, Edit, Bash, Glob, and Grep. Every action Claude Code takes is built from these six primitives. Knowing which tool does what helps you prompt more effectively and set up permissions that make sense.
  • The context window is Claude’s working memory**, and it accumulates throughout a session without resetting. Long sessions get richer and more useful. Starting a new session means losing all that built-up context — so staying in a session and guiding Claude is almost always better than starting over.
  • CLAUDE.md is the highest-leverage file you can create.** A well-written CLAUDE.md means Claude Code starts every session already knowing your project, your conventions, and your constraints. Without it, you re-explain everything, every time.
  • Plan Mode and the permission system are your safety net, not obstacles.** Plan Mode lets you review Claude’s full approach before it touches a single file. The permission system lets you permanently allow safe routine actions while blocking anything destructive. Together they let you give Claude genuine autonomy without giving up control.

Last updated: July 2026. Claude Code evolves quickly — check Anthropic’s official documentation at docs.claude.com for the latest details on any feature covered here.