The machine

The text of a program, written by a person or an agent and saved in ordinary files. It is a precise set of instructions. The computer does what the text says, which is not always what its author meant.

Source code is what an agent hands you and what you answer for. It can read perfectly sensibly and still be wrong, so you judge it by what it does when it runs, not by how confident it sounds.

A set of instructions a computer can carry out. Your browser is a program, and so is the agent you talk to. A program sits in a file doing nothing until something starts it.

What an agent can really do is start programs: ones that run tests, ones that install things, ones that delete. Each does exactly what it does, whatever the agent intended, so a command deserves more of your attention than a sentence.

A file is a named chunk of data kept on a computer. A folder, also called a directory, is a named container for files and other folders, so everything on the machine forms one big tree.

A code project is only a folder of files, and nearly everything an agent does is read, change, create or delete them. It can touch dozens in a minute, so you need to know the tree well enough to notice when it strays outside the job.

A program for opening and changing plain text files, made for code. It colours the text so the structure stands out, shows the project's folders down one side, and marks some mistakes as you type. VS Code is a common one.

You need somewhere to read what an agent wrote that isn't the agent's own account of it. Open the file it says it changed and you are looking at the thing itself, in the same folders it is working in.

The CPU is the part that carries out instructions, one tiny step at a time, very fast. Memory, or RAM, is the quick short-term space where a running program keeps its instructions and the values it is working on.

Agents test on small examples, so they often write code that loads a whole file into memory because that worked on the sample. At real size it runs out and gets killed. You will notice it as a loud fan, a crash, or a process that vanished.

Long-term storage, where files stay when the power goes off. It is much slower than memory. A program that only keeps data in memory loses it when it stops, crashes or the machine restarts.

An agent reaches for whatever makes the demo work, and that can be a list in memory. It passes every test. Then your first restart wipes all your users. So always ask where each piece of data lives.

One running copy of a program, with its own private memory and an ID number called a PID. Start a program twice and you have two processes that know nothing about each other. Each runs until it finishes or something stops it.

Agents start servers and leave them running, then start them again. The leftovers keep hold of resources and go on serving old code, so you can lose an hour debugging a change that isn't even the thing running.

A window where you control a computer by typing instead of clicking, and it answers in text. It looks old-fashioned, but nearly every tool a programmer uses can be driven from it.

Text is what an agent reads and writes, so the terminal is its natural home: commands go in, results come out. Anything you can do here, it can do. Reading its session is how you find out what it really did.

The program inside the terminal that reads your line, works out what you mean, starts the right programs and shows you the result. Common ones are bash and zsh. It can also join programs together, and that is most of its power.

An agent's command goes to a shell first, with all its rules, and a stray space or a * means something to it. Those rules are why one wrong character can delete the wrong thing, and why a short line can do far more than it appears to.

One line you give the shell: the name of a program, then flags that change how it behaves, then arguments saying what to work on. In rm -r build, rm is the program, -r is a flag and build is the argument. Spaces separate the pieces.

When an agent asks permission to run something, the command is what you are approving. Read it left to right: which program, which flags, which targets. Slow down for -f or --force, and for a * among the targets.

The written address of a file or folder. An absolute path starts from the top, as in /home/you/notes.txt, and means the same everywhere. A relative path, as in src/cart.js, starts from where you are. .. means the folder above and ~ means your home folder.

A relative path is right from one place only, and agents get lost in big projects. No such file or directory often means a correct path from the wrong folder. And an absolute path that works on your machine, an agent's favourite shortcut, works nowhere else.

The folder a shell is standing in right now. Relative paths start from here. pwd prints it and cd changes it. Every process has its own, so a cd inside a script doesn't move the shell you started it from.

A lot of agent trouble is the right command in the wrong folder: things installed at the wrong level of a project, or the wrong folder deleted. Agent tools also differ on whether a cd sticks between commands, so have it print where it is.

A named setting a process carries with it, such as TZ=Europe/London for its time zone. A program can read it without it being in the code, and passes a copy to any program it starts. A child can't change its parent's copy.

This is how the same code uses a practice database on your laptop and the real one in production, the live copy that real users rely on. It is also where secrets such as passwords belong. And it is a trap for agents: "I set it" may mean it was set in a shell that has already ended.

An environment variable holding a list of folders. When you type a program's name, the shell looks through those folders in order and runs the first match. If none has it, you get command not found, even when the program is on the machine.

Command not found is what an agent often meets straight after installing something, and the usual cause is a folder missing from this list. It also explains a command running the wrong version: another copy sits earlier in the list.

The number a program hands back when it ends. 0 means it went fine, and anything else means it didn't. You rarely see it, but the shell keeps the latest one in $?. Automatic checks in software rest on this.

An agent, or any automatic check, decides whether to carry on from this number, not from the words on screen. A program can print success and exit 1, or print nothing and exit 0. When you want proof that something passed, ask for the code.

Three channels every process starts with. Stdin is what comes in. Stdout is its results. Stderr is for errors and remarks. On screen, stdout and stderr look alike, but they are separate and can each be sent somewhere different.

An agent reads these the way you read a screen. The split lets a program pass clean results onward while its complaints still reach someone. Agent hooks, scripts that run at set moments in an agent's work (chapter 6), speak this too: they get their data on stdin and answer on stdout or stderr.

Sending a stream somewhere other than the screen. > writes stdout to a file, replacing what was there, and >> adds to the end. 2> does the same for stderr. 2>&1 sends stderr wherever stdout is going. /dev/null throws away whatever reaches it.

Agent commands are full of this. 2>&1 is there so errors get captured too. > /dev/null 2>&1 means nobody will see anything, including failures. Read the end of a long command first, because that is where output gets hidden.

The | character. It feeds one program's stdout into the next program's stdin, so small tools combine: grep ERROR app.log | sort | uniq -c finds lines, sorts them and counts repeats. By default, the whole line reports only the last program's exit code.

It is how an agent reads without drowning: tail keeps only the last lines, so a long test run costs it far less to read. But bun test | tail -20 reports how tail went, so failing tests look fine unless a setting called pipefail is on. An agent can fool itself this way, and so can you.

Rules saying who may read, write and run each file. ls -l shows them as -rwxr-xr--: three letters for the owner, three for a group, three for everyone else. chmod changes them. root, the administrator account, ignores most of them.

A script an agent writes can't run until it is marked executable, so Permission denied usually calls for chmod +x, not sudo. Be wary when an agent reaches for sudo or chmod 777. They don't fix the problem. They remove the protection that reported it.

A strict, made-up notation for writing instructions. Python, JavaScript, TypeScript, Go and Rust are all programming languages. Each has exact rules, so a missing bracket is not a typo to read past. It is a program that won't run.

An agent can write any of them, so you choose by how cheaply its mistakes get caught. A language with strict checks gives an agent an automatic no. If you don't say which language, the agent will pick, and you will own that choice.

A program that reads all your source code and translates it into a form a machine can run. If anything is broken, it refuses and produces nothing. Go, Rust and C are compiled. TypeScript's compiler, tsc, checks each value is the right kind and writes JavaScript.

A compiler is a free no. It arrives in seconds, before anything has run, in a form an agent can read and fix, so a compile step is one of the cheapest checks you can put in an agent's way.

An interpreter runs source code directly, working through it as it goes, so many problems only appear when reached. A runtime is what a program needs around it while running. Python, Node.js and Bun are examples. The line with compilers is blurry.

With no compile step, code that never ran is code nothing has checked. An agent can show you a working demo while a misspelt name waits on a path through the code it never took. So running the script once proves that one path. Tests have to go down the others.

A program that downloads code other people have published, from a public store called a registry, and keeps track of what you use. npm, pnpm and Bun do this for JavaScript, and pip and uv for Python. You run it in the terminal like anything else.

An install puts strangers' code on your machine, and some package managers let it run scripts as it installs. An agent types install as easily as ls, and it can name a package that doesn't exist, which an attacker could then register.

Code your project relies on but didn't write. The ones you name, in a file called package.json for JavaScript, are direct. They have dependencies of their own, and those have theirs, so these transitive ones are usually most of what you install, into a folder called node_modules.

Each one is code you now run without having read it, from people you don't know. Agents add them readily, because that solves today's problem. The cost arrives later, as updates, size and exposure. So ask for a reason each time.

A file the package manager writes, recording the exact version of every dependency it installed and a fingerprint of its contents. It means everyone, and every automated run, installs the same code. Don't write it by hand, but do keep it in the project.

Without one, an unchanged project can install different code next week and break for no visible reason. Agents change it in passing, so look at what changed: a one-package request shouldn't rewrite most of the file. And make automated runs refuse a mismatch.

A text file of commands that run in order, so what you would type by hand happens the same way every time. Projects also give short ones names in package.json, which is what bun run check means. A shell script has to be told to stop at a failure.

Scripts are how a fix outlives a working session: an agent runs the same check you did, or the same deploy (putting new code live for users), without improvising. But a plain shell script carries on after a failure and reports only its last line, so without set -e it can't really say no.

The program that runs the machine: it shares out the CPU and memory, keeps files on the disk, and starts and stops processes. macOS, Linux and Windows are operating systems. Programs ask it for everything, so a program built for one often won't run on another.

Your agent may run on a Mac while the code ships to Linux, and the two differ in small ways that pass on your laptop and then fail on a server. Agents write commands for one system out of habit, so tell yours what the target is.

Computers store everything as bits, each one 0 or 1. Eight bits make a byte, which can hold 256 different values. Text, pictures and programs are all runs of bytes, and only the reader decides what they mean.

Agents and people both read text far more easily than anything else, and neither of you can readily check a compiled program. So you review and keep the source, and build the rest from it.

The rule for turning characters into bytes and back. UTF-8 is the usual one today: English letters take one byte, é takes two and 日 takes three. Read with the wrong rule, the same bytes come out as garbage, such as café for café.

Agents tend to test with plain English, so these bugs wait for your first customer called José. Bytes and characters also differ, so a limit of 100 bytes can cut a character in half. Ask for a test with accents in it.

A coding agent is a program you install and then start in a terminal, from inside a project's folder. It reads and changes what is there and runs commands, usually asking you first. A project is only a folder, so a new empty one will do.

From here on, the course assumes you have one, because its drills, the exercises at the end of each chapter, happen on your machine and not on this page. Start it in a folder holding nothing you would miss, and read each command before you approve it.