Meeting the Tool: Claude Code, From Zero

Last class you built an agent yourself: a model, a while-loop, three tools, a growing list of messages, about a hundred and twenty lines of Python. That was the point of building it by hand, not to end up with something useful, but to end up unable to be fooled by the word "agent" ever again. This class that same loop goes industrial. The tool is Claude Code, and this unit is the reference manual: what it actually is, how to run it, what every control does, where every file lives. It's dense on purpose. Everything in it gets used later in this course, on a real company's real books, so treat the density as a map you'll walk over and over, not a wall of trivia to memorize once.

The company, and the game

Everything from here through the end of the class runs against a company called Xolo Consulting, a small business whose books, invoices, and contracts you'll work through as this class's shared case study. If you're following along, clone the course template repository rather than forking it, and run the data generator before you start. The books are synthetic, generated on purpose, which matters for what comes next.

Buried in Xolo's data and contracts are seven problems, seeded deliberately. Three invoices were issued in the CRM and never collected, quietly hiding about a hundred thousand pesos. One deposit has a transposed digit, the classic fat-finger error that survives casual human review. One deposit came in as US dollars instead of pesos, which poisons any total it touches if nobody catches the currency mismatch. One invoice was collected twice, a duplicate that looks like extra revenue until someone checks. And there's a trap that isn't a data error at all, it's bait: the same client's name is spelled slightly differently across the CRM and the bank records, so anyone, human or model, who tries to match records by client name instead of a real identifier gets garbage back. Two more traps live outside the spreadsheets, in the contracts folder: one amendment contradicts itself, changing the payment numbers while its own conflict clause says the original terms still govern, and one contract is a scanned image with no text layer at all, unreadable by anything that only reads text.

I know exactly where all seven traps are. You don't. And here is the part worth sitting with before you touch a keyboard: the AI doesn't know either. The question this class is built to answer isn't "can Claude find a trap if I point at it." It's whether the organization we build around the model, the files, the procedures, the checks, surfaces these problems on its own, by default, without anyone pointing at anything.

We keep a running scoreboard across the class: found by the harness, out of seven. Right now, before anything has happened, it reads zero out of seven. That number moves twice this class, once badly and once well, and by the end it closes completely, not because anyone got smarter, but because the organization around the model changed.

The map for the class

Two lessons cover what you might call "meeting the tool and feeling the gap." This lesson gives you the full reference: what Claude Code is, how to install and run it, the screen, the tool belt, the permission system, the operating modes, the commands worth knowing, and the three ways to invoke it. The next lesson puts all of that to work on Xolo: a first, lazy attempt at reconciling the books that fails in an instructive way, an autopsy of exactly why it failed, and then the same task done properly, briefed well, in plan mode, with the scoreboard actually moving.

Two more lessons cover the second half, making what you learn permanent rather than something you have to redo by hand every time. One walks through the files that turn a conversation into an organization: memory, the project's constitution file, and the five real primitives Claude Code gives you for building durable procedures. The other watches that organization run on its own, watches a second, independent check confirm or refute its work, and watches the organization learn an entirely new skill live, closing the scoreboard for good. A final short lesson pulls the whole class into doctrine you can reuse on any task, plus your homework.

From your agent.py to Claude Code

Last class's equation was agent equals model plus loop plus tools plus context. Hold onto that, because every single thing in Claude Code maps onto one of those four terms, and every failure you'll ever debug in it traces back to exactly one of them.

The model term is unchanged in substance. Claude Code calls the same frontier Claude API you called directly from Python. There's no separate, secretly-different "agent model" running under the hood. The /model command lets you pick which tier of that same family handles your current session, but the model itself is the model you already know.

The loop term is your for turn in range(20) loop, grown up. It's the same request-response-tool-call cycle, now with streaming output so you watch it think in real time, automatic retries when a call fails, an interrupt key so you can stop it mid-thought, and a rewind so you can undo a turn and take the conversation in a different direction. None of that is conceptually new. It's the same loop with better manners.

The tools term is your three toys, list_files, read_file, run_python, grown into a real belt of tools you'll walk through below.

The context term is your growing Python list of messages, plus two mechanisms that get a lot of attention this class. First, a project file called CLAUDE.md gets automatically read into every session's context the moment it starts, no one has to paste it in. Second, procedures called skills load into context only when a task actually calls for them, instead of sitting in the window the whole time. We spend the second half of the class on both.

There's one more design decision underneath all of this that doesn't map onto any single term of the equation, because it governs all four at once.

Claude Code is scoped to whatever folder you start it in. That folder is the agent's entire world, nothing more, nothing less. This single fact is what makes the whole thing organizational rather than just a smarter autocomplete: the repository is the workspace, and the workspace is the organization. Every feature this class traces to one of the four equation terms; every failure traces to exactly one of them too. Keep that discipline and debugging Claude Code stops being mysterious.

What Claude Code actually is

Here's the plain definition, and then two misconceptions worth killing before they cost you anything. Claude Code is Anthropic's agentic command-line tool: a frontier model, the agent loop you already understand, and a set of real tools, all living in your terminal, scoped to one folder. You type plain language. It reads files, runs commands, edits things, searches, and works through multi-step problems for minutes at a stretch, while you watch, steer, or walk away entirely. Every action it takes is visible in the transcript, and every consequential action is gated behind your approval.

Two things worth knowing up front, because they shape how the tool behaves. It's built by Anthropic, the same company that trains the model, which means the harness and the model co-evolve together rather than being bolted on by a third party guessing at the model's behavior from outside. And while it's terminal-native, it isn't terminal-only: extensions surface the same underlying tool inside VS Code and JetBrains IDEs, and it also runs as an SDK for building entirely custom harnesses of your own, which you'll meet properly in a few weeks. We work in the raw terminal in this course specifically because seeing the loop happen, watching every tool call announce itself as it fires, is most of what teaches you to trust or distrust an agent's behavior. An IDE panel hides exactly the thing you need to be staring at right now.

Now the two misconceptions.

:::callout{type="pitfall" title="Misconception one: "code" means programmers"} "Code" is the surname here, not a requirement. Claude Code operates on files: CSVs, contracts, reports, images, whatever sits in the folder you point it at. Most real-world use of an agent like this is ordinary knowledge work, reconciliation, drafting, research, not software development at all. Xolo Consulting, the company you'll work with this class, never touches a line of application code. Its books are spreadsheets and PDFs. :::

Installing and running it

Getting Claude Code running takes three commands. Install, verify, then run it from inside the folder that will be your workspace.

curl -fsSL https://claude.ai/install.sh | bash

Verify the install worked with claude --version, then start the tool from inside your project folder: cd xolo-consulting && claude. The first time you run it, you'll be prompted to /login, signing in with a Claude account on any paid plan, or with an API key if you're wiring it into something programmatic later in the course.

What you actually need to run this is a short list: a terminal, a Claude subscription on any paid tier or an API key, and ideally git so the tool's version-control awareness works properly. That's the whole requirement.

There's one real gotcha, and it costs people real confusion the first time it bites: start Claude Code in the right folder. The working directory when you launch it is the entire world the agent can see and act on. Start it one level up from where you meant to, and it's operating on the wrong world, not failing, just confidently doing the wrong thing in a folder you didn't intend.

One more piece of course-long practical advice. Claude Code ships roughly weekly. Features move fast, which means specific screenshots, exact command names, and even some of what's on the slides for this course will drift over the semester. Run claude update periodically to stay current, run /doctor inside a session if something about your install feels off, and when in doubt, trust docs.claude.com over any blog post or course material, including this one. A weekly-shipping tool is a moving target by design, and the discipline of checking the actual current docs rather than trusting last month's screenshot is itself a habit worth building now.

The screen you'll be staring at

The first thirty seconds looking at a Claude Code session kill most of the intimidation, so let's spend those thirty seconds properly.

Three regions, three distinct jobs, worth naming explicitly because you'll be reading all three constantly.

The transcript is last class's messages list, rendered live in front of you. Reading the transcript is reading the loop: every thought the model surfaces, every tool it calls, every result that comes back. Nothing here is hidden from you by design; the transparency is deliberate, not accidental noise you have to scroll past.

The status line is your instrument panel. It tells you the current mode, which model tier is active, and, critically, how much context window remains. Treat that percentage the way you'd treat a fuel gauge in a car: it's a real, finite, degrading resource, and watching it tells you when you're approaching the point where the model's attention starts getting spread too thin across too much accumulated conversation.

Permission prompts appear inline, mid-loop, and when one appears, the loop parks. It does not proceed, does not guess at your intent, does not execute anything further until you answer. Nothing runs past you without your say-so. You'll watch all three of these regions move together in real time in the next lesson's first demo.

The tool belt, in four families

Every tool available to Claude Code is one function the model can request, exactly the shape of your three toys from last class, plus a written description the model reads when deciding whether a given tool is the right one for the current step. There are more than three now, but they group cleanly into four families, and once you know the families, tracking what the agent is doing at any moment becomes a matter of tagging each call, not memorizing a long list.

The first family is look: Read, Grep, and Glob. These are read-only and low-risk, opening files, searching their contents, and finding files by name pattern. This is where an agent spends most of its early turns on any real task, because exploration is cheap and safe, and a well-run agent orients itself before it acts.

The second family is act: Write, Edit, and Bash. This is your run_python grown up, and it's the only family that can actually hurt you, because it creates files, modifies them, or runs arbitrary commands. Worth noting specifically: Edit is a surgical find-and-replace against an existing file, not a wholesale rewrite, which is exactly why diffs produced by Claude Code stay small and reviewable rather than replacing entire files on every change. Because risk concentrates almost entirely in this one family, this is where the permission gate does almost all of its work.

The third family is reach: WebSearch, WebFetch, and, through a protocol called MCP, connections outward to databases, Slack, email, browsers, whatever a server chooses to expose. This is the socket where a lot of Xolo's future capability plugs in, once the course gets to wiring real infrastructure into the agent rather than working from static files.

The fourth family is organize, the meta family: Task, which spawns a subagent running in its own separate context window, and TodoWrite, which keeps a visible checklist going on longer jobs. Hold onto the Task tool specifically; it becomes the mechanism behind an idea called the verifier later this class, and it's one of the more structurally important pieces of the whole system.

During the demos in the next lesson, get in the habit of tagging each tool call in your head as it fires: look, act, reach, or organize. You'll notice quickly that risk concentrates almost entirely in one family, and that's exactly where the permission gate is positioned to bite.

The permission system

The permission system earns real attention here, three separate slides' worth in the original teaching material, because it's the entire safety story of the tool, and most quick introductions wave at it without actually explaining the mechanism. Understanding it properly now saves you from either being needlessly paranoid about the tool or dangerously casual with it later.

Here's the anatomy of a single prompt. Claude Code shows you the exact action it wants to take before it happens, not a vague description, the literal command or file write. Underneath that, three numbered choices: yes, just this once; yes, and don't ask again for this pattern of action; or no, and tell it what to do differently instead.

The second option is how a session actually gets smoother as it goes: approving a pattern once, "yes to python commands," means that entire class of action stops interrupting you for the rest of the session. And the third option is worth sitting with, because it's easy to read "no" as a wall when it's actually a steering wheel. Saying no and explaining what you want instead means the denial itself becomes part of the model's context. It isn't refused into silence; it adapts, on the next attempt, to what you actually wanted.

Beyond the interactive prompt, the whole permission perimeter can be written down as a file, .claude/settings.json, sitting at the project root.

Xolo's real perimeter file pre-approves the safe tools, reads, and running python, hard-denies the unacceptable, reading anything under a secrets folder, running rm, reaching out over the network with curl, and leaves everything else to ask at the moment. Three properties of this file are worth noticing. It's declarative: you can read the whole security posture of the project in one file. It's versioned in git, which means your security policy carries a diff history, exactly as reviewable as any other change to the codebase, which should delight anyone who cares about auditability. And it composes cleanly: allow, deny, and everything else defaults to asking.

One more thing worth naming honestly: a flag exists, --dangerously-skip-permissions, sometimes called YOLO mode, that turns off the entire gate and lets the agent act without asking at all. The name is the documentation. It has a real use, inside sandboxes or throwaway virtual machines where nothing consequential can actually break. In this course, on a machine you actually care about, the answer is never.

Four gears

One key, Shift+Tab, cycles Claude Code through its operating modes, and it's worth thinking of these as gears, because each one trades off speed against how much you're actively steering.

The first gear is the default: ask before acting. Reads happen freely, and every write or command pauses for your approval. This is the gear for everyday work and for anything unfamiliar, where you don't yet know what the agent is likely to do.

The second gear is auto-accept: file edits apply without asking, and you review the resulting diff afterward instead of gating each one individually. This is fine for low-risk, bulk, mechanical work, but only inside a repo that's clean in git before you start. Git is your undo here, not a formality, commit first, let it run, diff after, and you can revert cleanly if something goes sideways.

The third gear is the one worth calling doctrine rather than just a mode: plan mode. In plan mode, the agent is entirely read-only. It explores your files, reasons about the task, and lays out a plan for your approval, and it is structurally incapable of touching a single file until you say go.

The fourth gear is the one you already met on the permissions section: --dangerously-skip-permissions, bypassing the gate entirely. Its self-documenting name is the whole warning label; it belongs in sandboxes, not on your working machine.

The dashboard: commands that manage the window

Command syntax follows one clean rule worth internalizing immediately: a slash talks to the tool itself, and plain text talks to the model. Four commands manage the context window directly, and they're worth knowing cold, because context problems are the single most common cause of an agent's output degrading partway through a long session, without anything announcing that it's happening.

/context diagnoses: it shows you an actual breakdown of what's currently occupying the window, system prompt, the project's memory file, tool definitions, conversation so far. When output quality drops, this is the first place to look, not the model's competence. Nine times out of ten, the window is simply stuffed with more than it needs.

/clear resets: it wipes the window entirely. A new task deserves a new session, and this is, honestly, the most underused command that exists in this tool. People carry a conversation forward out of habit long after the task it was built for has finished, and the leftover context quietly taxes every turn that follows.

/compact survives: it summarizes the conversation history to reclaim space mid-task, when you're deep into something and can't afford to lose the thread entirely. It's lossy by nature, so prefer /clear at a real task boundary and save /compact for when you're mid-flight and actually need the room.

/cost accounts: it reports tokens spent and dollar cost for the current session. Engineering without cost accounting is theater, and your homework this class asks you to record cost per run, not as busywork, but because a number you never measure is a number you can never actually manage.

The rest of the day to day

A handful of other commands round out daily use.

A further set of commands, /init, /memory, /permissions, /agents, /mcp, and /hooks, are the org-building commands, the ones that let you construct durable procedures rather than one-off conversations. Those get their own full treatment, each next to its real file format, in the lesson on the permanent files. Don't try to memorize any of this list right now; a cheatsheet exists in the course repository specifically so you can keep it open while you work instead of holding it in your head.

Input superpowers

A handful of typing conventions let you feed the context window with real precision instead of prose descriptions, and they're worth knowing before you're mid-task and reaching for the slow way to do something there's a fast way to do.

The # prefix means "remember this": typing a line starting with # mid-session appends it directly to a memory file, no separate step required. This is the compounding gesture of the whole system, made frictionless. You notice, mid-session, a rule worth keeping, "always report row counts," and one keystroke later it's permanent rather than something you'll forget to write down and have to relearn the hard way next month.

The ! prefix runs a shell command yourself, directly, with its output landing in the context window. You're feeding the window precisely, rather than describing to the model what a command would show.

An @ followed by a filename pulls that specific file into context by name. This beats describing a file in prose every time; precision beats description, always, when precision is available.

Ctrl+V pastes an image directly into the conversation, a screenshot of an error, a chart, a whiteboard photo. An artifact beats a description of an artifact every single time, and this is the fastest way to hand the model something exact rather than something approximate.

Then there's steering the loop itself, which matters as much as feeding it.

Three doors into the same harness

There are three distinct ways to invoke Claude Code, and the third one is where this whole course is quietly headed, even this early, in Class 3.

The first door is interactive: just claude, the REPL you've been reading about this entire lesson. You steer every step, and this is where all real skill-building happens, this class included.

The second door is continue: claude -c reopens your most recent session, and claude -r lets you pick any past session from history. Transcripts persist to disk, which means closing your laptop and walking away costs you nothing. Tomorrow, -c picks the thread back up exactly where you left it.

The third door is headless: claude -p "some instruction" --output-format json, no REPL at all. It runs one task, prints the result, and exits, which makes it scriptable, croneable, wireable into CI. Notice specifically what can sit inside the quotes: a slash command, the exact same kind of command you'll build later this class. Which means everything you're about to construct, the procedures, the checks, the whole organization, is already automatable the moment it exists. This is the entire zero-employee thesis compressed into one line of shell: a scheduler invoking the third door, a human reviewing the drafts it leaves behind. That's a story for a later class, but plant the sentence now, because it's the reason everything else this class is worth building carefully rather than throwing together.

What's next

You now have the reference manual: what Claude Code is, how to run it, the screen's three regions, the four tool families, the permission system and its four gears, the commands that manage context, the input tricks that feed and steer it precisely, and the three doors that invoke it. None of this was meant to stick from a single read. It's meant to be recognizable when you see it in motion.

The next lesson puts all of it in front of Xolo Consulting for real. You'll watch what a lazy, eight-word brief produces when it's audited against the seven seeded traps, why it fails in a specific and instructive way that has nothing to do with the model being insufficiently smart, and then what changes when the same task is briefed properly, in plan mode, with a one-sentence correction along the way. The scoreboard moves for the first time. Bring the reference manual with you; you'll use every part of it.