How Claude Code Works

1. What happens when you press Enter

You type a task into the Claude Code prompt and press Enter. What happens next is not magic — it is a structured sequence of steps that you can observe, interrupt, and steer. Understanding that sequence is the difference between using Claude Code as a black box and using it as a reliable collaborator.

The first thing Claude Code does is read the CLAUDE.md file in your project root, if one exists. This gives it your project conventions, preferred commands, and any standing instructions before it looks at a single line of code. Think of CLAUDE.md as a briefing document that runs before every session.

Next, Claude Code decides what context it needs. For a small task (“fix the typo in the README”), it may read one or two files and act immediately. For a larger task (“refactor the authentication module to use the new session store”), it will map the relevant directory structure, read the files that are most likely to be affected, and check git history to understand intent. This exploration phase is not overhead — it is what makes the subsequent steps correct.

Once Claude Code has enough context, it reasons about what needs to happen. For complex tasks, it will write out intermediate steps before taking any action. This planning output is surfaced to you in the terminal, which means you can catch misunderstandings before they turn into wrong edits. If the plan looks wrong, interrupt with Ctrl+C and clarify — it is much cheaper to correct a plan than to undo a set of file changes.

Then Claude Code acts: writes files, runs shell commands, installs packages, or calls external services. After each significant action, it checks the result. If a test runner returns failures, Claude Code reads the failure messages and loops back to diagnose and fix. This inner loop of act → verify → re-act is what gives Claude Code the feel of a developer who actually runs their code rather than just writing it.

2. The context window: a finite budget

Every Claude model operates within a context window — a fixed number of tokens that it can hold in “working memory” at one time. Everything Claude Code knows during a session must fit in that window: your CLAUDE.md, the files it has read, the conversation history, the output of every command it has run, and the response it is about to write.

This constraint has real practical consequences. In a long session, the context window fills. As it does, older material gets pushed out, and Claude Code’s ability to recall early conversation details or file contents it read at the start of the session degrades. You might notice that after 30 minutes of iterative work, Claude Code starts making mistakes that it would not have made fresh.

The solution is context hygiene. Use /clear between unrelated tasks to wipe the conversation history and start fresh. Use /compact when you need continuity but the window is getting full — it summarizes the conversation into a compressed form, recovering space while preserving the key decisions and context. Be deliberate about which files you ask Claude Code to read; reading a large file “just in case” spends budget that could have been used to hold the output of your test suite.

A useful rule of thumb: treat /clear like saving and closing a document. Finish one task, commit the result, then /clear before starting something new. The fresh context makes the next task faster and more accurate.

3. Permission modes: auto-accept vs. manual approval

Claude Code can operate in two broad modes that control how much it does before checking in with you.

In manual approval mode (the default for new users), Claude Code pauses before any action that could affect your system — writing a file, running a shell command, making a network request. You see exactly what it is about to do and press Enter to approve or Ctrl+C to stop. This mode is slower but safer. It forces you to read each action, which is also a great way to learn what Claude Code actually does under the hood.

In auto-accept mode (enabled with --yes or by responding “always” to a tool category), Claude Code takes approved actions without pausing. This is dramatically faster for routine tasks where you trust the action categories. A common intermediate approach is to auto-accept file reads but manually approve writes and bash execution.

The permission system is granular: you can approve all file reads, approve writes only for specific directories, or require approval for every bash command while auto-accepting everything else. This lets you tune the safety/speed tradeoff based on your actual risk tolerance for a given project.

4. The tool palette in detail

Claude Code arrives with a standard set of tools that cover the vast majority of development tasks.

Read file reads the content of any file you have permission to access. Claude Code uses this constantly — to read source files, configuration files, test files, package manifests, git logs, and anything else relevant to the task. It reads files selectively rather than dumping entire directory trees into context.

Write file creates or overwrites a file with new content. Before writing, Claude Code typically shows you a diff of what is about to change. You should always review this diff, especially for files you have not explicitly told Claude Code to modify.

Bash runs a shell command and returns its stdout and stderr. This is the most powerful and most general tool. It is how Claude Code runs your tests, installs packages, queries your database, or does anything that a shell script could do.

Web search and fetch let Claude Code look up current documentation, find examples on GitHub, or retrieve the content of any URL. This is useful when dealing with packages or APIs that postdate the model’s training cutoff, or when you need a specific piece of documentation rather than recalled knowledge.

List directory gives Claude Code a view of a directory’s contents without reading each file. It uses this to orient itself in unfamiliar codebases before deciding which files to read.

Beyond these built-ins, MCP servers (Model Context Protocol) extend the tool palette with purpose-built integrations: GitHub, Linear, Postgres, Stripe, and hundreds more. These are covered in depth in the MCP lesson.

cd ~/projects/your-repo
claude

Read src/index.ts, then src/router.ts, then src/database.ts and summarize what each one does.

claude --yes

Find all files that import from ../utils, check if there is a utils/index.ts, and tell me what it exports.