Installing, and your first session

Claude Code is a program that runs in your terminal, in a directory you point it at. It can read the files in that directory, write to them, and run commands. That last part is the whole difference between it and a chat window: you are not copying code out of a browser any more, you are watching something edit your working tree.

Which is also the reason the rest of this part is careful about permissions. A thing that can run npm test can run other commands too.

What it costs, once, and then not again

Claude Code needs a paid Claude plan: Pro, Max, Team, Enterprise, or a Console account. The free plan does not include it. That is the only time this course will talk about money, because which tier is right for you depends on how much you use it and that changes, and a course that tells you what to buy ages into an advertisement.

Everything else here is free, including the repository you are about to clone.

How do you install Claude Code?

On macOS, Linux, or WSL:

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

On Windows in PowerShell:

irm https://claude.ai/install.ps1 | iex

If you would rather not pipe a script into a shell, Homebrew has it (brew install --cask claude-code), so does WinGet (winget install Anthropic.ClaudeCode), and there is an npm package (npm install -g @anthropic-ai/claude-code). They all install the same binary. The difference is that the native install updates itself in the background and the others do not, so with Homebrew or WinGet you will be running brew upgrade yourself every so often.

Then check it landed:

claude --version

You should get a version number and the words (Claude Code) after it, like 2.1.232 (Claude Code). If you get command not found, the installer put the binary somewhere your shell is not looking; opening a new terminal fixes it most of the time.

There is a second command worth knowing before you need it:

claude doctor

That prints diagnostics about the install and your settings files without starting a session. It is the first thing to run when something is wrong and the last thing anyone remembers exists.

Get the codebase

Everything from here runs against one repository. It is a small inventory tool called stockroom: items, a ledger of stock movements, five reports, a command line and a read-only HTTP view of the reports.

git clone https://github.com/gorgekara/stockroom.git
cd stockroom
npm install
npm test

You need Node 24 or newer. There is no build step; Node runs the TypeScript directly.

The tests will not all pass:

 Test Files  3 failed | 3 passed (6)
      Tests  9 failed | 77 passed (86)

That is correct. Nine tests fail because there are three real bugs in there, planted on purpose and left where a real bug would be. A repository where everything works teaches you what a demo looks like. You will fix the first of them in the next lesson.

The rest of the mess is deliberate too. One 335-line file that should be three, a config flag nothing reads, a README that documents a command which was renamed, and an untyped JavaScript importer nobody wants to touch. All of it is there because that is what the code you get paid to work on looks like, and because a tool that only helps on clean code is not much help.

One more thing about the repo, and then we can start.

Several lessons change it, and they build on each other: lesson 15 assumes lesson 12’s fixes, lesson 26 assumes lesson 19’s branch. If you break something badly, or come back a fortnight later and cannot remember where you were, there is a tag for the state the repo should be in after each lesson that changes code.

git tag

after-lesson-11  after-lesson-12  after-lesson-14
after-lesson-19  after-lesson-27  after-lesson-28

git reset --hard after-lesson-14 puts you at the state lesson 15 expects, throwing away whatever you had. Use it to get unstuck, and use git diff after-lesson-12 after-lesson-14 to see what a lesson’s exercise actually changed once you have had your own go at it. The README lists what each tag contains.

There is no tag for the lessons that only add a configuration file, because those hand you the whole thing to paste and there is nothing to get wrong.

Start a session

From inside stockroom:

claude

The first time, three things happen. It asks whether you trust the directory, because it is about to be able to run things in it. It sends you to a browser to log in. And then you get a prompt, which is where you type.

Type this and press Enter:

How many test files are in this repo, and what do they cover?

It will read around for a few seconds and answer. Six files, one per module, and it should name them. Now you have seen the loop that the rest of this part elaborates: you ask in English, it goes and looks, it tells you what it found.

Ask it something you can check. An answer you cannot verify teaches you nothing about whether the tool is any good at this.

The word in the corner

Look at the bottom of the session. There is a mode indicator, and on a Pro, Max or Team plan in a terminal it probably says auto.

That matters more than it looks. In auto mode a second model reviews each action Claude wants to take and approves or blocks it, instead of stopping to ask you. It is a reasonable default for people who already know what they are doing and a bad default for the next two lessons, because the whole point of lesson 12 is watching a change before it happens.

Press Shift+Tab. It cycles: Manual, acceptEdits, plan, and, where they are available, bypassPermissions and auto. Stop on Manual.

Manual is the mode where Claude asks you before it edits a file, runs a command, or reaches the network. It is the slowest mode and it is the one to learn in. You can leave it later, and lesson 18 is about deciding when.

The five modes, in one line each, because you will meet all of them:

Mode	What it does	Worth knowing
Manual	Asks before nearly everything.	Its config value is default, which is confusing and worth knowing when you get to settings files.
acceptEdits	Stops asking about file edits, still asks about commands.
plan	Reads and explores but cannot edit.	Lesson 14.
auto	A classifier approves actions instead of you.
bypassPermissions	Asks about nothing.	For containers, not for your laptop.

Getting out, and staying out

• Esc interrupts Claude mid-answer. It keeps the work already done, so this is how you redirect rather than how you undo.
• Ctrl+C interrupts too; on an empty prompt, twice, it exits.
• /exit exits.
• claude --continue picks up the last conversation in this directory.

And one that will save you at some point: with the prompt empty, press Esc twice. That opens a menu to rewind the conversation and your files to an earlier point. It is not lesson 12’s undo, but it is the thing to reach for when a session has gone somewhere you did not want.

Your turn

In your stockroom clone, start a session, switch it to Manual with Shift+Tab, and ask:

Which file has the most lines in src, and how many?

Then check the answer yourself:

find src -name '*.ts' -o -name '*.js' | xargs wc -l | sort -n | tail -3

Check: Claude names src/reports/index.ts, and wc -l agrees with the number it gave you. If it named a different file or was more than a line or two out, it guessed instead of looking, and that is worth noticing on a question you can check in five seconds rather than on one you cannot.

Recap

Claude Code is a terminal program with read and write access to a directory and the ability to run commands there. It needs a paid plan, it installs in one line, and claude doctor is the thing to run when it misbehaves.

You have stockroom cloned, its 86 tests running, and nine of them failing on purpose. You have a session open in Manual mode, which is the mode where you see what it wants to do before it does it.

Next: the loop you will spend every session in. Ask, read the diff, and push back when the diff is wrong.