How Claude Code works

What you’ll learn: the agentic loop, the built-in tools, and what’s actually in your context window — the mental model that makes everything else predictable.

The agentic loop

     ┌──────────────────────────────────────────┐
     │                                          │
     ▼                                          │
 You prompt  →  Claude reasons  →  Claude calls a tool
                                          │
                                          ▼
                              Claude Code executes it
                              (subject to permissions)
                                          │
                                          ▼
                          Result goes back into context ─┘

                    ...until Claude has nothing left to do,
                    then it responds to you.

That’s it. Everything else — hooks, subagents, permissions, MCP — is a modification to some part of that loop:

Understanding this makes the whole system predictable. When something surprises you, ask: what’s in context, what tools does it have, and what gated the call?

The built-in tools

Claude Code ships with a tool suite. The main ones:

Two behaviours worth knowing:

Claude must Read a file before Editing it. This is enforced — an Edit on an unread file fails. It prevents blind edits.

Independent tool calls run in parallel. Reading three files happens simultaneously, not sequentially. This is why Claude Code feels fast on exploration.

Full list: Tools reference.

What’s in your context window

Run /context to see it. Typically:

The last one is where context goes to die. A session that has read forty files carries forty files.

Anthropic ships an interactive context window simulation that’s worth ten minutes.

Compaction

When context approaches the limit, Claude Code compacts: summarises the conversation so far and continues with the summary.

What you should know:

• Project-root CLAUDE.md survives. After /compact, Claude re-reads it from disk and re-injects it.
• Nested CLAUDE.md files in subdirectories are not re-injected automatically — they reload next time Claude reads a file there.
• Conversation-only instructions are lost. If you told Claude something important in chat and it disappeared after compaction, it was never written down. Put it in CLAUDE.md.
• /compact costs tokens — it’s a model call over your whole transcript.
• Compaction can be intercepted with PreCompact / PostCompact hooks, and you can re-inject context with a SessionStart hook using the compact matcher.

Often better than compacting: starting fresh. Current models are extremely good at rediscovering state from the filesystem. A new session that reads progress.txt and the git log frequently beats a compacted one.

Checkpointing and rewind

Claude Code tracks file changes so you can undo. /rewind can also resume a conversation from before a /clear.

See Checkpointing.

Sessions

Conversations persist. You can:

claude -c                    # continue the most recent here
claude -r                    # interactive picker
claude -r auth-refactor      # by name
claude -n "auth-refactor"    # name a new session
claude --resume abc --fork-session   # branch instead of continuing
claude --from-pr 123         # find the session that created a PR

Transcripts are stored locally. claude project purge clears local state for a project.

The .claude directory

Where everything lives:

your-project/
├── CLAUDE.md                    # or .claude/CLAUDE.md
├── CLAUDE.local.md              # personal, gitignored
└── .claude/
    ├── settings.json            # project settings (committed)
    ├── settings.local.json      # personal settings (gitignored)
    ├── rules/                   # modular instructions
    │   ├── testing.md
    │   └── api-design.md
    ├── skills/
    │   └── deploy/SKILL.md
    ├── agents/                  # custom subagents
    ├── commands/                # legacy custom commands (still work)
    └── hooks/                   # hook scripts

~/.claude/                       # user scope, all projects
├── CLAUDE.md
├── settings.json
├── skills/
├── agents/
├── rules/
└── projects/<project>/memory/   # auto memory

See Explore the .claude directory.

Settings precedence

When the same setting exists at several levels:

managed policy  >  --settings flag  >  local  >  project  >  user

And feature-specific layering:

• CLAUDE.md files are additive — all levels contribute simultaneously
• Skills override by name — managed > user > project
• Subagents override by name — managed > CLI flag > project > user > plugin
• MCP servers override by name — local > project > user
• Hooks merge — every registered hook fires

Debugging your setup

Four commands, in this order:

And when nothing makes sense:

claude --safe-mode    # start with all customisations disabled
claude --debug-file /tmp/claude.log

--safe-mode disables CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, themes, keybindings, LSP, and auto-memory — while leaving auth, model selection, built-in tools and permissions working. If the problem disappears, it’s one of your customisations.

Try it

Exercise 1 — Read your context. Run /context in a fresh session, note the total. Have a substantial conversation involving several file reads. Run it again. Note where the growth came from.

Exercise 2 — Force compaction. Deliberately fill a context window. Watch compaction happen. Then ask about something you discussed early on. Note what survived.

Exercise 3 — Parallel tools. Ask Claude to read five specific files. Watch the tool calls. They fire together.

Exercise 4 — Safe mode. Run claude --safe-mode in a project with customisations. Note the behaviour difference. This is your first move whenever something breaks.

Exercise 5 — Map your .claude. Run ls -la .claude/ and ls -la ~/.claude/ and identify every file. Anything you can’t explain is worth reading about.

Checkpoint

• You can draw the agentic loop and name where each extension plugs in
• You know what survives compaction and what doesn’t
• You know the four diagnostic commands and what each one answers

Going deeper

• How Claude Code works
• Explore the context window — interactive
• Tools reference
• Checkpointing
• Manage sessions
• Explore the .claude directory
• Debug your configuration
• Glossary