BUILD · PHASE 04 · LESSON 28

Install, First Run, Verify

Presence is not correctness. Verify that it runs, not that the binary exists.

Type: Build
Prerequisites: Lesson 27 (What Claude Code Is)
Time: ~20 minutes

Learning Objectives

By the end of this lesson, you can:

Install Claude Code on your machine using the official method for your platform.
Launch Claude Code from a terminal and exit it cleanly.
Verify the install is real: the tool launches, reads a file, and answers one instruction.
Re-run the Phase 00 setup-check script and read its verdict on the claude entry.
Update or uninstall Claude Code using the same three-command lifecycle.

The Problem

You run the install command. The terminal prints a path. You type claude and it runs. So it's working.

Or so you think.

This is the failure mode Phase 00 warned about: a shim on PATH that prints a version number and exits. The binary exists. The tool does not work. You cannot tell the difference from the outside until you ask the tool to do something.

Lesson 5 told the same story with a different tool. The fix is the same fix: do not trust that the install command succeeded. Trust the use of the tool.

The Concept

Three commands. One per platform for install. One for verify. One for update.

# macOS / Linux / WSL: the official install command from the docs
# Windows (native): the official install command for Windows from the docs
# pick the one for YOUR machine

The principle, restated: The reframe: presence is not correctness. A successful install is one where you can ask the tool to do one thing and it does it. Not one where the binary exists.

The verification step matters because it is the only way to tell a working install from a shim.

Build It

Numbered. End each step with a check.

Step 1 — Install. Run the install command for your OS from the official source. The command is one line. Do not improvise it. Do not copy a blog post. Do not follow a Stack Overflow answer. Use the official docs page for your platform.

Check: the install prints a success line. If it printed an error, fix that first. Do not proceed.

Step 2 — Launch once. Open a terminal in any directory. Type the launch command. Wait for the prompt.

claude

You should see Claude Code's interface. If you see "command not found," the install failed or the binary is not on your PATH. Stop and fix this before going further.

To leave: type /exit and press Enter. (Slash commands are covered properly in Lesson 30. For now, just know /exit exists.)

Check: you exited cleanly back to your shell prompt.

Step 3 — Read a file from a directory. From inside a project directory you trust, launch Claude Code and ask it to read one specific file. Pick a file you know exists.

claude
> Read the file README.md and tell me the first line.

A working install answers. A shim, even a clever one, does not.

Check: the tool returned the first line of the file. If it did not, the install is not real. Go back to Step 1.

Step 4 — Re-run setup-check.sh. From your project root (the same place you ran it in Phase 00), run:

./scripts/setup-check.sh

Look at the line for claude. After a real install, the entry should report ok — your script's "real binary" marker, the one that distinguishes it from the MISS or shim state from Phase 00.

Check: the claude line is no longer flagged as missing or shim.

Step 5 — Know the lifecycle commands. You do not need to run update or uninstall now. Just know they exist. The table below has them.

Use It

Action	Command	Notes
Install	the official command for your platform from the docs	One line. Pick the one for YOUR OS.
Update	the official update command for your platform	Run when a new version ships.
Uninstall	the official uninstall command for your platform	Reversible. You can reinstall.
Exit a session	`/exit`	From inside Claude Code.
Check the install	`./scripts/setup-check.sh`	From your project root. The `claude` line should not read `MISS`.

Exercises

Exercise 1 — Install and launch. Run the install command for your platform. Launch Claude Code. Exit with /exit.

Pass: you end back at your shell prompt with no error message in the transcript.

Exercise 2 — Verify it actually reads a file. From a directory that contains a file you know (e.g. README.md), launch Claude Code and ask it to read the file and report one fact about it.

Pass: the tool reports a fact that matches the file's actual content. A shim cannot do this.

Exercise 3 — Confirm via setup-check.sh. Run ./scripts/setup-check.sh from your project root.

Pass: the claude entry reports ok (or your script's equivalent of "real binary"). It must not report MISS or shim.

Key Terms

Installed. What people say: "the install command finished without an error." What it actually means: the binary exists and it can read a file and it responds to an instruction. The first alone is not enough.

PATH. What people say: "it's on PATH, so it works." What it actually means: the shell can find a file by that name. That file might be a working binary, an old binary, or a shim. PATH is a lookup mechanism, not a correctness guarantee.

Verification. What people say: "I checked it runs." What it actually means: you asked the tool to do a task it cannot fake. For Claude Code the floor is: read a file you named and report something true about it.

Shim. What people say: "a placeholder for the real thing." What it actually means here: a script or binary on PATH that imitates the real tool enough to fool a presence check. The Phase 00 setup-check.sh was written to catch exactly this.

What this lesson skipped

Custom configuration (model selection, paid plans, default settings) — Lesson 29. The full introduction to slash commands beyond /exit — Lesson 30. The first real "give Claude a goal and let it work" session — Lesson 31.

Check yourself

4 questions. Answer before you reveal — recognising the right option is not the same as being able to produce it.

claude --version prints a version number, but when you ask Claude Code to read README.md it cannot. What is going on, and what do you do?
1. The install succeeded — the version printed, so start working
2. Presence is not correctness: a shim is imitating the tool well enough to pass a version check. Verify by asking it to read a named file and report a true fact; if it cannot, reinstall from the official source
3. The file must not exist — check the path
4. The model is offline — wait and retry
Show answer

B. Presence is not correctness: a shim is imitating the tool well enough to pass a version check. Verify by asking it to read a named file and report a true fact; if it cannot, reinstall from the official source

The install command printing a number only proves something is on PATH, not that the real tool works. Option A is the trap the lesson exists to break: it trusts presence over use. Option C blames the fixture when the real signal is that reading a file you named is the check a shim cannot pass. Option D guesses at a cause the evidence does not support.
Your Phase 00 setup-check reports claude: shim. What does that mean?
1. The binary is missing from PATH entirely
2. A file named claude is on PATH and imitates the tool well enough to fool a presence check, but is not the real tool
3. The installed version is out of date
4. The check script is broken
Show answer

B. A file named claude is on PATH and imitates the tool well enough to fool a presence check, but is not the real tool

A shim is a stand-in that passes a presence check, which is exactly why the script distinguishes it from a real binary. Option A is the tempting confusion: MISS means absent; shim means present and imitating. Option C confuses an out-of-date install with a fake one. Option D blames the messenger instead of the report it carries.
Which check actually proves a Claude Code install is real rather than a shim?
1. claude --version prints a version number
2. which claude (or where claude) finds a file
3. Ask it to read a file you named and report a fact that matches the file's contents
4. The tool launches and shows a prompt
Show answer

C. Ask it to read a file you named and report a fact that matches the file's contents

Reading a file you named and reporting a true fact is a task a shim cannot fake, which is what makes it verification. Options A, B, and D are all presence checks: a version string, a PATH hit, and a prompt on screen can each be produced by something that is not the real tool. Option B is the most tempting of the three because it looks like a real lookup, but a lookup is still not correctness.
A blog post gives a one-line install command for Claude Code that differs from the official docs page. What do you do?
1. Run the blog command — one-liners are usually the same
2. Use the official command for your platform from the docs; do not improvise
3. Run both and keep whichever prints a version
4. Skip the install and use the browser version instead
Show answer

B. Use the official command for your platform from the docs; do not improvise

The install command is one line and you take it from the official source, because a third-party variant is how you end up with an old binary or, worse, a shim. Option A is tempting because the difference usually looks cosmetic. Option C decides by a presence check, which is the exact test the lesson says is not enough. Option D abandons the terminal shape the whole phase is about.