Your First Real Change, Made by an Agent and Checked by You

Getting the tool onto your machine

The chapter walks through installing Claude Code as a standalone application rather than through npm, explaining why the native installer (fetched with curl or the PowerShell script) is the recommended path — it updates itself and needs no Node.js runtime — while noting Homebrew, WinGet, and Linux package repositories as valid alternatives, per the setup instructions. It covers system requirements, the sign-in flow through a browser, and the built-in diagnostic reached with slash doctor for fixing installation and network problems, drawn from the CLI reference.

Opening a real project

Once launched inside a small shared-list web app, the chapter shows the workspace trust prompt, the live session display showing model and context usage, and the two permission modes — Manual, which asks before every write or command, and Auto, now the default for Pro, Max and Team plans, which only interrupts for destructive operations. It draws on the permissions documentation and the interactive mode guide to explain what each mode actually shows you and why reading a diff before approving it matters.

Making one change and proving it

The core of the chapter is a single fix: stopping blank or whitespace-only list items from being added. It shows the tool describing the project first, proposing a small diff, running the test suite after a command-approval prompt, and then a manual click-through of the app to confirm the behavior actually changed — because a passing suite only proves what it already tested. A new test is added, deliberately watched failing and then passing, before a single readable commit closes the loop.

What changed recently in Claude Code

A short section flags two changes that affect a first session directly: Auto mode becoming the default permission mode on Pro, Max and Team plans, and Sonnet 5 becoming the default model with support for pinning a default model via environment variable, both listed in the Claude Code changelog and the what's new page.

Somewhere in your project there is a small wrong behavior you have been ignoring. Not a crisis. A blank item that shouldn't be addable, a button that stays enabled when it shouldn't. By the end of this chapter, one of those is fixed, in a real repository, by a tool that made the edit while you watched, and you will have run something that would have failed if the fix were wrong.

That last part is the whole point. The tool is not the achievement. The check is.

So let's start with what the tool actually is, because if you have only ever used Claude in a browser window, the difference matters more than it sounds.

Claude Code is an application that runs on your own computer. You start it from a terminal, inside a folder that holds your project. Once it is running, it uses a Claude model to decide what to do, and it uses tools to do it: reading files, editing files, running commands. Those tools act on your actual files on your actual disk, in the directory you launched it in.

Compare that to a chat window. In a chat window, you are the transport. You copy a file out of your editor, paste it into the browser, read the answer, copy the suggested code back, paste it into the right place, save, and run your tests yourself. The model never sees your project. It sees the fragment you showed it. If it guesses that your tests live in one place and they live in another, it has no way to find out.

Claude Code can find out. It can list the folder, open the test files, run the test command and read the failures. That is the difference: not a smarter model, but a model with hands.

There is a third thing people confuse with both, and it is worth naming once so you can stop wondering about it. The Claude API and the Agent SDK are for building your own programs — you write the code that calls the model and decides what happens next. That is a different job from the one you are doing today. Today you are a person using an application.

Claude Code has more than one interface. The one this chapter demonstrates is the command-line application: you type the word claude in a terminal, inside your project folder, and work in the session that opens. Other interfaces exist. We are not touring them.

Here is what this chapter does. Install the command-line application. Sign in. Launch it inside a small existing web app. Have it describe the project before it touches anything. Then state one intended behavior in a single sentence, ask for the change, approve the edit, read the diff, run the check that proves it, add a test if none existed, and commit. That is the chapter. It is one loop, walked slowly.

Installing, and getting the first request answered

The way to install this has changed since the earliest tutorials, and if you find an old blog post it will probably tell you the wrong thing first.

The officially recommended method now is the native standalone installer. On macOS, Linux, or Windows Subsystem for Linux, you fetch the install script from the Claude site with curl and pipe it into bash. On Windows in PowerShell, you fetch the PowerShell installer and pipe it into the shell's own execute command. On Windows using the older command prompt, you download the install command file, run it, and delete it afterward.

There are other supported paths. Homebrew has it as a cask. Windows has it in WinGet. There are official Debian and Ubuntu and Linux package repositories. And npm still works — the old instruction to install the package globally with npm has not been withdrawn.

I am telling you to use the standalone installer for one specific reason, and it is not taste. Standalone installations update themselves in the background. Package manager installations do not. As a beginner, the thing you least want is to spend an afternoon debugging behavior that was fixed three releases ago. There is a second reason worth knowing: the native install does not need a Node.js runtime at all. The npm route requires Node twenty-two or newer, and even then it is only a wrapper — it downloads the same precompiled binary for your platform and links it. Nothing runs through Node when you use it. So npm buys you nothing here except a Node dependency.

Before you run anything, check that your machine is in scope. You need macOS thirteen or later, or Windows ten from version eighteen-oh-nine onward, or Windows Server twenty-nineteen, or Ubuntu twenty-oh-four or later, or Debian ten, or Alpine three point nineteen. Your processor needs to be x64 or ARM64, and you need at least four gigabytes of memory. The search tool ripgrep comes bundled, so you do not install that separately. You need working internet access from a country Anthropic supports.

One extra note for Windows. Install Git for Windows if you have not. Claude Code prefers Bash and will fall back to PowerShell without it, and the difference will show up later as commands that behave oddly.

Now the part that stops people. Before your first request goes anywhere, you need an account with access. That means either an active paid Claude subscription — Pro, Max, Team, or Enterprise — or an Anthropic Console account with API credits on it. Those are two different arrangements and either satisfies the requirement. Third-party providers are also supported if your workplace already routes through Amazon Bedrock, Google Cloud, or Microsoft Foundry.

Assuming you have one of those, signing in is a browser round trip. Run claude with no credentials stored, and it starts an interactive sign-in flow. Your terminal prints an authorization link and opens your desktop browser to the Claude site. You authorize there. The application receives tokens and stores them locally — in the Keychain on macOS, or in its own folder under your home directory on Linux and Windows. You do this once per machine.

If you would rather use an API key, you can put it in an environment variable named for the Anthropic API key, or sign in against the Console explicitly with a flag on the login command. Worth knowing: if you have both a stored login and that environment variable set, the environment variable wins. That has confused people who thought they were on a subscription and were quietly spending credits.

There is a diagnostic worth learning now rather than at three in the morning. Inside a session, type slash doctor — it also answers to slash checkup — and it validates your local setup, your authentication, and whether it can reach the network, and repairs some problems on its own. It was extended more recently to explain organization policy errors too. Run it right after installing. If your first launch does anything strange, run it again before you start guessing.

Now launch. Change directory into your project root and type claude. You can pass a prompt inline as an argument if you want, but for your first session, start empty.

The first time you open a folder it has not seen, it asks whether you trust this workspace. This is not decoration. It will not load workspace files until you say yes. Say yes for your own project.

Then the session interface appears. It is a terminal application built with React and Ink, which means it redraws itself live rather than scrolling like an ordinary program. Across the top you get project information, which model is active, how much of the context window you have used, and which permission mode you are in. At the bottom there is an input line that begins with a greater-than sign. That is where you type.

Two things about that display. Type slash model to see or change the active model. And note the permission mode, because on Pro, Max and Team plans, sessions now default to Auto mode. In Auto mode, operations classified as safe run without asking you, and it interrupts only for destructive things — recursive deletes, destructive git resets, that family. If you want the older behavior where every write and every command asks first, type slash permissions and switch to Manual. For your first hour, I would switch to Manual. Not because Auto is reckless, but because approvals are how you learn what the tool is reaching for, and you cannot learn that from actions that already happened.

The project, described before it is touched

Here is the app we are working in. It is a shared list — the kind two people use for groceries. TypeScript, on a familiar React framework, with a PostgreSQL database behind it. The user journey is four clicks: open a list, type an item, add it, see it appear for both people. That is small enough that you can hold all of it in your head, which is exactly why it is a good first project.

Your first request should not change anything. Ask it to describe the project: where the pages live, how the app starts in development, and how the tests are run. In plain words, something like — look around this repository and tell me where the page components are, what command starts the dev server, and what command runs the tests.

It will read files, search, and answer. Notice what happens on your side: nothing asks permission. Reading files inside the workspace, searching with grep and glob, and read-only shell commands like listing a directory or checking git status all run automatically. That is not a loophole. It is the boundary between looking and touching, and looking is cheap and reversible.

But the real reason to spend a request on this is the answer itself. You already know where your tests are. You are not asking for your benefit. You are checking whether the tool found them. If it tells you the tests run one way and you know they run another, you have learned something important for free, and you have learned it before it wrote a line.

If the description is wrong, correct it in the next message and ask again. Do not proceed on an inaccurate picture and hope.

One sentence, then one change

Now the change. And before you ask for anything, write down the behavior you want, in one sentence, in plain language.

Adding an item with an empty or whitespace-only name should not create a list item.

That sentence is doing more work than it looks like. It is the thing your test will assert later. If you cannot state the behavior in one sentence, you do not yet know what you are asking for, and neither will the tool.

Now make the request. Something like — when the add-item form is submitted with an empty or whitespace-only name, do not create an item; keep the form and show a short message instead. Change as little as possible.

That last clause matters. Left unconstrained, a coding agent will happily tidy three files it noticed on the way past. You want one change you can read.

It will look at the relevant files and then propose an edit. In Manual mode, when it wants to modify a file, it shows you a colorized inline diff of the proposed change and asks whether to approve it. The prompt names the file — something like, Claude wants to edit the add-item component — and offers three answers: Yes, which approves this one edit; allow for session, which permits file modifications for the rest of this process and is never written to disk; or No, which refuses.

Read the diff before you answer. That is the entire reason the prompt exists. It is not a speed bump between you and the result; it is the last cheap moment to say no. And there is a fourth option people miss: press Tab while Yes or No is selected and you get a text field to type guidance with your answer. Refusing with a reason is far more useful than refusing.

Say Yes, and the file is written to disk.

Then ask it to run the tests. Something like — run the project's tests. Now you get the other kind of prompt. Mutating shell commands ask before they execute: Claude wants to run npm test, allow this command? You can answer Yes to run it once, or "yes, and don't ask again", or No.

That middle option has a consequence you should understand before you pick it. It does not just remember for this session. It writes an allow rule for that command prefix into a local settings file inside your repository, and that file is automatically added to your git excludes so it does not get committed. So it persists across sessions, on your machine, invisibly to your teammates. For running your test suite, that is a fine thing to persist. For anything that touches the world outside your project, say Yes each time until you have a reason not to.

The output streams into your terminal as it runs.

Reading the change, and proving it

Now the part beginners skip, which is reading what actually changed.

Inside the session, type slash diff. That opens a diff viewer in the terminal. If your window is a hundred and forty-four columns wide or more, it opens as a side panel that updates live while edits happen — which is genuinely better than checking after the fact, because you watch changes arrive. You can also leave the session, or open a second terminal, and use git status and git diff. Unstaged changes are on disk immediately, so your ordinary Git tools see them right away with no special step.

Read it with three questions. Did it change only the behavior you asked about? Did it touch any file you did not expect? And did it quietly rewrite something adjacent — a shared helper, a type, a piece of formatting — while it was in there?

That third one catches the most trouble. A change that also reformats a file is a change you can no longer read, because the fix you care about is buried in three hundred lines of moved whitespace. If that happens, undo and ask again with narrower instructions.

For our change you are looking for something small: the submit handler now trims the name, returns early if what remains is empty, and sets a message. Two or three lines in one file. If the diff is much larger than that, something else happened, and finding out what is more valuable than shipping.

Suppose the diff looks right and the tests pass. What has that established?

Less than it feels like. The suite passing tells you the change did not break anything the existing tests were watching. If no existing test ever submitted an empty item, then nothing in that run touched the behavior you just changed. A green suite is evidence, and it is real evidence, but it is not proof, and it is proof of nothing at all about a behavior it never exercised.

So do the thing that actually matters. Start the dev server and click the journey yourself. Open a list. Click Add with the field empty. Then type a single space and click Add. No item should appear either time, and you should see the message. Then add a real item and confirm that still works — the most common way this fix goes wrong is that it blocks everything, including valid input.

That click-through is the check that speaks to the user. The test suite speaks to the code.

And because you just found a mistake the application could really make, it deserves a test that catches it. Ask for one: add a test that submitting the add-item form with a whitespace-only name creates no item. Then read that diff too, and here is a trick worth keeping. Undo the fix temporarily, run the new test, and watch it fail. A test you have never seen fail is a test you have not verified. Put the fix back, run again, watch it pass. Now you know the test is attached to the behavior and not just sitting nearby being green.

If you want to undo something inside the session, type slash rewind, or press Escape twice on an empty prompt, and files revert to a checkpoint taken before a prompt turn.

Then commit. One commit, containing the fix and its test, with a message a person can read in eight months. Something like: reject empty and whitespace-only list item names on submit. Not "fix bug". Not "updates". The message's job is to answer, for a future stranger who is probably you, why this line looks like this.

If the change turns out to be wrong later, your ordinary Git paths still apply, because nothing here bypassed Git. Before you commit, git restore on the file throws the change away. After you commit, git revert on that commit creates a new commit undoing it, which is the safe choice on anything shared. That is why the commit boundary matters: a small commit is a small thing to reverse.

When you are done, exit with slash exit, or Control-D twice quickly, or Control-C twice on an empty prompt. Your transcript is saved automatically. Tomorrow, in the same repository, claude with the dash c flag reopens your most recent session with its conversation and tool history intact, or dash r gives you a picker to choose from older ones.

So: inspect, state, request, read, check, commit. Inspect so you know the tool understands the ground. State the behavior in one sentence so there is something to check against. Request one small change. Read the diff yourself. Run the check, and click the journey, because those are different checks. Commit something legible.

That loop is the unit of work for everything that follows, and it does not get more sophisticated as the tasks get bigger. It only gets faster.

The one thing left is that you had to tell the tool where your tests live. A fresh session tomorrow will not know either. The next step is teaching the project to explain itself, so it does not have to ask.

What changed lately, and what it costs you

Two recent changes to Claude Code will affect what you do in your very first session, so they are worth a minute even though you have not built up much to compare them against.

The first is the one I flagged while you were launching. Auto mode is now the default permission mode for new sessions on Pro, Max and Team, as of the middle of August. Previously you got interactive approval prompts for writes and for mutating commands. Now safe reads and writes execute automatically, sorted by a background risk classification, and you are interrupted only for genuinely destructive operations — recursive deletes, destructive git resets, that category.

Which task does that change? The one you just did. If you had launched without knowing this, your first edit would have landed on disk without a prompt, and the moment I told you to read before approving would never have arrived. So the smallest useful next action is: launch, type slash permissions, look at what is actually active, and switch to Manual for your first few sessions. Not forever. Approvals get tedious once you know what the tool reaches for, and Auto mode is a reasonable place to end up. But you cannot learn to read a diff at the moment of decision if there is no moment of decision.

The second is model selection, which quietly determines both quality and cost of everything above. Claude Sonnet five is now the default on Pro, Team and Enterprise plans, with a one-million-token context window and adaptive thinking. Claude Opus five launched as the default Opus choice. And support was added for an environment variable named for the Anthropic default model, so you can pin your session model permanently rather than choosing each time.

The task this affects is every task, which is why a two-second habit pays. Type slash model at the prompt and read what is actually running. If you want it fixed, export that default model environment variable in your shell profile — setting it to Sonnet five, say — and it applies to new sessions from then on.

Here is your check, and it is the same shape as the check in the lesson. Set the variable, open a new terminal so the profile reloads, launch in your project, and type slash model. If it reports what you pinned, the setting took. If it reports something else, your profile did not load or the variable name is misspelled, and slash doctor will tell you which. Do not assume a setting worked because you typed it correctly. Ask the tool what it thinks, the same way you asked it where your tests were.