Claude Code — How It Actually Works

Understanding Claude Code as a coding agent — not just a chatbot — changes how you interact with it. This page goes behind the interface so you know what is happening when Claude reads your files, runs commands, and builds features.

Claude Code Is an Agent, Not a Chatbot

When you ask Claude Code to "add a contact form," it does not just generate text. It:

This is fundamentally different from a chatbot that writes code in a bubble. Claude Code is executing a sequence of actions on your actual project.

When you type claude in your project folder, Claude Code loads your CLAUDE.md — the project rules file — before you type a single request. Every session starts with full context about your project.

The Tool System

Claude Code has access to a set of "tools" — specific actions it can take on your computer. You can see these tool calls happening in real-time as Claude works.

Why this matters: When you see Claude "thinking" for a few seconds, it is actually reading files, running searches, and building a picture of your project. The output it gives you is informed by the actual content of your codebase — not a generic template.

Each line beginning with a bullet is a tool call — Claude reading a file, searching for a pattern, or editing code. You can watch exactly what it is doing and why, in real time.

The Permission System

Claude Code has three modes for how it handles actions that affect your files or system:

Auto-approve: Claude does it immediately without asking. Used for safe, reversible operations like reading files, searching for patterns, and writing to new files.

Ask first: Claude describes what it wants to do and waits for your confirmation. Used for potentially impactful operations like running terminal commands, installing packages, or modifying system files.

The permission prompt appears before any terminal command runs. You choose: approve once, skip this step, or always allow this type of command for the session. You are always in control.

Deny: Claude is blocked from doing certain things entirely. You configure this for operations you never want automated.

In practice for new developers: Start with Claude asking for confirmation on all Bash commands. As you get more comfortable and understand what Claude is doing, you can allow more automatic behavior. You will see a prompt in your terminal asking whether to allow the command.

Type y to allow once, always to allow that command type from now on, or n to deny.

How Claude Reads Your Codebase

Before Claude writes any significant code, it investigates. Here is a typical sequence when you ask for a new feature:

This exploration phase is what separates Claude Code from generic code generation. By the time Claude writes your new component, it has seen:

• What your existing components look like
• How you handle validation
• What hooks you already have
• What naming conventions you follow
• What imports are commonly used

The output matches your project because Claude actually read your project first.

The Session Model — Why CLAUDE.md Is Critical

Every time you start a new Claude Code session, Claude starts fresh. It does not remember the previous session.

This sounds like a limitation, but it is actually by design — a fresh session avoids accumulating incorrect assumptions. The mechanism that solves the memory problem is CLAUDE.md.

Ask Claude anything about your project and it answers from your CLAUDE.md — not from a generic guess. This is why a well-written CLAUDE.md is the most valuable file in your project.

What happens at session start:

Without CLAUDE.md: Every session starts cold. Claude does not know your stack, your conventions, your patterns, or your rules. You re-explain everything every time.

With CLAUDE.md: Every session starts warm. Claude knows your stack, your conventions, your patterns, and your rules from the first message. The deeper and more accurate your CLAUDE.md, the faster and better Claude performs.

This is covered in depth on the CLAUDE.md Mastery page.

What Claude Can See

Claude Code can access anything on your file system that your user account can access. In practice, for a project:

Claude sees:

• All your source code files
• Your package.json and dependencies
• Your configuration files (vite.config.ts, tsconfig.json, etc.)
• Your .env file (important — be careful about this)
• Your git history

Claude does NOT see:

• Remote databases (unless you give it connection strings)
• External APIs (unless it calls them via Bash)
• Browser state
• The running application's memory

Reading the Tool Calls — Understanding What Claude Is Doing

As Claude works, you can follow along by watching what tools it uses. Here is how to read a typical tool call sequence:

If you see Claude reading many files before writing anything — that is good. It is building context.

If you see Claude writing a file immediately without reading anything — that can produce generic code. You can help by telling Claude which files are relevant to read first.

If you see Claude running TypeScript checks or lint — that is Claude verifying its own work. You want this behavior.

When to Use Claude Code vs Claude.ai Chat

A common workflow: Think through the approach in Claude.ai chat, then switch to Claude Code to implement it in your actual project.

Keyboard Shortcuts and Useful Commands

In VS Code: If you have the Claude Code extension installed, you can open it from the Activity Bar sidebar. You get the same agent behavior but inside your editor — with the added benefit of seeing Claude's edits highlighted in the diff view.

The Cost Model

Understanding how costs work helps you use Claude Code efficiently without wasting your subscription.

What costs tokens:

• Your messages to Claude (prompt tokens)
• Claude's responses (output tokens)
• Files that Claude reads (input tokens)
• Previous messages in the conversation (input tokens — these accumulate)

What does NOT cost tokens (after initial read):

• CLAUDE.md content (it is cached — read once, available for free in subsequent turns)
• Skill files (also cached)

Practical implications:

1. A focused, specific prompt costs fewer tokens and gets a better answer than a vague, rambling one
2. Long conversations accumulate cost — start a new session when switching to a different task
3. If you paste an entire codebase into a chat, you are paying for every token. Claude Code's Read tool is more efficient — it reads only what it needs.
4. CLAUDE.md caching is significant: a well-written CLAUDE.md might be 4,000 tokens that gets referenced in 50 turns. Without caching, that costs 200,000 input tokens. With caching, it costs 4,000 tokens once.

Common Beginner Mistakes

Mistake 1: Accepting the first output without reviewing it

Claude's first attempt is usually good but not always perfect. Always read what it wrote. Ask it to adjust if something is off. Never commit Claude's output without reading it.

Mistake 2: Not telling Claude when something is wrong

If Claude writes something that does not work, tell it specifically what is wrong. "This does not work" is not enough. "The form submits but does not show a success message — the onSuccess callback is not being called" is specific and actionable.

Mistake 3: Giving a new task without clearing old context

If you just debugged a complex auth issue and now want to build a new page, use /clear first. Starting fresh avoids Claude carrying over wrong assumptions from the previous task.

Mistake 4: Not watching the tool calls

If Claude starts writing code without reading any of your existing files, it is working blind. Tell it to read relevant files first: "Before writing the form, read the existing login form to understand our patterns."

Mistake 5: Giving Claude a task that is too large

"Build the entire recruiter dashboard" is a project, not a task. Break it into smaller pieces: "Build the job listing table component," then "Add the filter sidebar," then "Connect it to the jobs query hook." Smaller tasks produce better, more focused results.

• I understand the difference between Claude.ai (conversational) and Claude Code (agentic — takes multi-step actions in my actual project)
• I can name the 6 core tools and say what each one does: Read, Write, Edit, Bash, Grep, Glob
• I understand the permission system — what gets auto-approved, what asks me, and why I should read before approving
• I have run a Claude Code session and seen it use the Read tool before doing anything
• I understand why Claude Code reads your codebase before writing — so output fits your patterns, not generic defaults