What is Claude Code?

1. Beyond the chat box

When most developers first encounter AI coding assistants, they picture a chat interface — you type a question, a model types back an answer, and you copy-paste whatever looks useful. That model is perfectly fine for quick questions, but it has a hard ceiling: the model never actually touches your code. It reasons about text you paste in, and every session begins with a blank slate.

Claude Code is built on a fundamentally different premise. It is a command-line agent that runs in your terminal, reads and writes real files on your disk, executes shell commands, searches the web, and persists its understanding across a working session. The gap between “AI assistant” and “AI developer” is tool use — and Claude Code is built around it.

When you launch Claude Code inside a project directory, it can immediately read your directory structure, open specific files, look at recent git commits, and run your test suite. It does not need you to paste context in. It can discover what it needs the same way a new engineer would on their first day: by exploring. This changes what you can delegate to it. Instead of “here is a function, can you suggest improvements?” you can say “there is a failing test in the auth module, figure out what is broken and fix it” — and Claude Code will do the investigation, not just answer a question.

The other key difference is the ability to act. A chat assistant can tell you the shell command to run; Claude Code can run it and read the output. It can write a file and immediately verify that the code compiles. It can make a change, run the tests, see a failure, read the traceback, and revise the fix — all in one uninterrupted cycle, without you ever switching windows.

2. The agentic loop

The mental model that makes Claude Code comprehensible is the agentic loop: a repeating cycle of observe, plan, act, and verify. Understanding this loop is the key to working with Claude Code effectively rather than fighting it.

Observe — Claude Code begins every task by gathering context. It reads the files most relevant to your request, checks the current state of the codebase, and may look at git history or run a quick search. This is not overhead; it is the foundation that makes the subsequent steps reliable. A Claude Code session that skips observation usually produces confident but wrong output.

Plan — Before writing a single line of code, Claude Code reasons about what needs to happen. For simple tasks this planning is implicit and fast. For complex tasks — cross-file refactors, adding a feature that touches several modules — you can and should ask it to write out a plan first. Reviewing the plan before Claude Code acts is one of the highest-leverage checkpoints available to you.

Act — Claude Code uses its tools to carry out the plan. It writes files, runs commands, installs packages, or searches for information. Each action is discrete and auditable — you can see exactly what it did.

Verify — After acting, Claude Code checks whether the action produced the intended result. It might run tests, read error output, or re-read the file it just wrote to confirm it looks right. If verification fails, the loop begins again: observe the new state, revise the plan, act again.

This loop is what separates Claude Code from autocomplete tools. Autocomplete predicts the next token; Claude Code pursues a goal across multiple steps, adapting when it encounters unexpected results. The loop also means that longer, more complex tasks are within reach — the agent does not give up after one attempt, it keeps iterating.

3. The tool palette

Claude Code’s capabilities are defined by the tools it has access to. On a standard installation you get:

File system tools — read any file, write files, create directories, move and delete files. These are the most fundamental tools and the ones Claude Code uses in almost every task.

Bash execution — run arbitrary shell commands and read their output. This covers compiling code, running tests, installing dependencies, grepping for patterns, checking git status, and thousands of other operations. Bash execution is powerful but also the tool that warrants the most careful approval — more on this in later lessons.

Web search and fetch — look up documentation, search for examples, retrieve the content of a URL. This lets Claude Code reference current information rather than relying entirely on what it learned during training.

MCP tool connections — a growing ecosystem of Model Context Protocol servers that add purpose-built tools: GitHub operations, database queries, Linear ticket management, and more. MCP servers extend Claude Code’s reach into the systems your project actually uses.

Understanding which tool Claude Code is using at any moment is easy — it displays every tool call before and after execution. You always know what it is doing and can interrupt at any point.

4. Claude Code vs. alternatives

Knowing what Claude Code is good at requires knowing what it is not the right tool for.

Claude Code excels at multi-step tasks with clear success criteria: fixing a failing test, refactoring a module to a new API, migrating a configuration format, writing and running a data processing script. Tasks where you could write a checklist of steps and know when each one is done are ideal.

It is less suited to open-ended creative design: choosing an overall architecture for a new system, deciding on product priorities, or designing a user interface from scratch. These tasks benefit from human judgment and back-and-forth dialogue. For those, a chat interface or a whiteboarding session may be more appropriate.

Lightweight autocomplete tools like GitHub Copilot are a better fit when you are actively typing and want inline suggestions — they integrate into your editor and work at keystroke speed. Claude Code is a better fit when you step back from the editor and want to delegate a task at a higher level of abstraction.

npm install -g @anthropic-ai/claude-code

claude --version

cd ~/projects/my-app

claude

Describe the overall architecture of this project. What are the main modules and how do they relate?

Find any TODO comments in the codebase and list them with file and line number.