Code & Local Build

A terminal is a text box that runs commands. That is the whole secret. Everything in this module exists because your agent works through that text box, and you cannot steer what you cannot read.

The last four modules were about what you ask for. This one is about where you ask it.

The terminal is a text box, not a test

The terminal is a window where you type commands instead of clicking. It is precise, scriptable, and identical on your laptop and on a server on the other side of the planet. Clicking is pointing at a menu; the terminal is speaking the language — slower to learn, far more you can say.

It matters now for one reason: AI coding agents work through it. When Claude Code installs a package or runs your tests, it runs the same commands you would, and shows you the output. If those lines are noise to you, every session is a black box and you are approving things you cannot judge.

Two facts make it stop being scary. A terminal does nothing until you press Enter. And when something fails, the failure text on your screen is the most useful thing in the room — not something to hide from.

Every command happens somewhere

A terminal is always standing inside one folder. That folder is the current directory, and most commands act on it. Most beginner confusion — “the command did nothing”, “file not found” — is really “I was standing in the wrong place”.

A path is the address of a folder or file. / separates the parts on macOS, Linux, WSL and Git Bash; \ separates them on native Windows. The same Claude Code binary lands at ~/.local/bin/claude on macOS and Linux, and at %USERPROFILE%\.local\bin\claude.exe on Windows — one file, two spellings (setup docs). ~ means your home folder. . means here. .. means one level up.

One rule to carry: always cd into your project folder before starting an agent. Start it in your home folder or on the Desktop instead, and every document and every other project you own is sitting inside its working directory. One project, one folder, one session.

Ten commands cover almost every tutorial

On Windows these work as written in Git Bash. PowerShell answers to most of them as well — touch is the usual miss. CMD does not. The Windows section below tells you which of the three you are looking at.

Two keys save more time than any command in that table: the Up arrow brings back what you last typed, and in a real terminal Tab completes a half-finished name.

pwd
cd qairu-event
ls
cat package.json
cp .env.example .env

Now do it, in a terminal that cannot hurt you.

node_modules is not your code

Almost nobody writes everything from scratch. A package manager downloads the libraries your project needs, and the libraries those need, at compatible versions, and records the exact versions in a lock file so every machine installs the same thing. For JavaScript that is npm, pnpm or bun; for Python, pip or uv. An app store for code blocks, instead of hunting for downloads by hand.

• package.json — what you asked for: the dependencies and the named commands (dev, build, test).
• the lock file — what you actually got, down to the exact version.
• node_modules/ — the downloaded code itself. Hundreds of folders. Nobody reads it.
• npm install — the command that turns the first two into the third.

node_modules never goes into git: it is enormous, and one command rebuilds it anywhere. The tools assume this. When Claude Code creates a git worktree it is a fresh checkout, so node_modules is simply not there and you reinstall it (worktrees). If an agent proposes committing that folder, say no.

localhost is your house, not the internet

npm run dev looks up dev in package.json and runs it. That starts a dev server: a small web server running on your own machine that serves your project to your own browser and reloads the page when you save a file.

It prints an address, usually something like http://localhost:3000. Another project — or a second server on the same machine — will print a different number. Read it off your own screen rather than memorising it: the port is just a door number on your own machine, and the terminal always tells you which door it opened.

Three habits:

1. Give the dev server its own terminal tab. It keeps running and keeps printing; it is not frozen.
2. Ctrl+C stops it. “Port already in use” almost always means you started a second one.
3. A blank page with no errors is still progress. Check the terminal output and the browser console before you tell the agent it is broken — paste both.

.env holds the keys, and it never leaves your laptop

Environment variables are named values that live outside your code and are handed to the program when it starts: API keys, a database address, settings like NODE_ENV=production. They keep secrets out of the repository and let the same code behave differently on your laptop and on the server. Locally they sit in a .env file that must be listed in .gitignore; on a host you paste them into the dashboard instead. The office keys stay with the security guard, not taped to the front door.

The rule has no exceptions, and it has one correct order:

And remember where secrets may not go at all: the frontend is the part that runs on the user’s device, and anyone can open the browser developer tools and read it. Keys belong on the backend or in the host’s dashboard.

“It works on my machine” is a diagnosis, not a joke

It means your machine has something the other machine does not. There are five usual candidates, and you can check all of them in two minutes.

• A missing environment variable. Your .env exists locally and nowhere else. Fix: add the variables in the host dashboard.
• An uncommitted file. It works because the file is on your disk, not because it is in the project. Fix: git status.
• Dependencies never installed. The other machine has package.json but no node_modules. Fix: run the install command.
• Capital letters. Windows treats Hero.astro and hero.astro as the same file. Most deploy servers run Linux and treat them as two different files, so an import that works locally fails in the build. Fix: match the filename exactly, character for character.
• A different version. A newer or older runtime than yours. Claude Code itself shows the pattern: the npm install route needs Node.js 22 or newer (setup docs).

Deploying is what turns this from an argument into a fact. Working on your machine is not done; deployed is done. Module 12.

If you are on Windows, read this part twice

Most of this course’s audience is on Windows; most tutorials are written by people who are not. You do not need Linux. Claude Code runs natively on Windows 10 1809 or newer with 4 GB of RAM or more, from PowerShell or CMD, and WSL is not required — WSL 2 only matters if you want Claude Code’s sandboxing, which native Windows does not support (setup docs).

Install Git for Windows anyway. With it, Claude Code uses Git Bash for its Bash tool; without it, it falls back to a PowerShell tool — and module 9 needs git regardless.

First, know which shell you are looking at.

Then read the error instead of retrying it.

All four come from the official setup and install troubleshooting pages. The PATH one is the most common. Here is the fix — then close the window and open a fresh one, because a running terminal never notices a PATH change:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Make the agent give you the tour

You do not have to learn a project’s layout by reading it. Ask — then check every answer yourself with the commands above. That is the point of this module: you can now audit what the agent tells you.

I am new to the terminal. In this project, do these four things and explain each one in two sentences:

1. Show me the folder structure, ignoring node_modules and .git.
2. Tell me the exact command that starts the dev server and the address it will print.
   Read this from package.json - do not guess.
3. Check whether .gitignore contains .env and node_modules. If either is missing, show me
   the line you would add before you add it.
4. List every environment variable this project reads, by name only. Never print a value.

Change nothing else. If you are unsure about something, say so instead of guessing.