Install and first-run checklist

What to understand

• Claude Code installs as a native binary with one command, and the command depends on your shell, not just your OS. macOS, Linux, and WSL use the curl install script (`curl -fsSL https://claude.ai/install.sh | bash`); Windows PowerShell uses `irm https://claude.ai/install.ps1 | iex`; Windows CMD has its own `install.cmd` one-liner. The classic giveaway error tells you which shell you're in: `The token '&&' is not a valid statement separator` means you're in PowerShell, not CMD; `'irm' is not recognized` means you're in CMD, not PowerShell. Your prompt also tells you, `PS C:\` is PowerShell, plain `C:\` is CMD.
• There is more than one supported install path, and the trade-off is auto-update versus control. The native installer (recommended) auto-updates silently in the background. Homebrew (`brew install --cask claude-code`, or `claude-code@latest` for the bleeding edge), WinGet (`winget install Anthropic.ClaudeCode`), and npm (`npm install -g @anthropic-ai/claude-code`, Node 18+) all work but do NOT auto-update, you upgrade them manually. For a first install on a personal machine, the native installer is the path of least friction.
• On native Windows, Git for Windows is the difference between the Bash tool and the PowerShell tool. Installing Git for Windows is optional but recommended: with it, Claude Code runs shell commands through Git Bash; without it, it falls back to a PowerShell tool. WSL 2 is the other route on Windows and is the only one that supports sandboxed command execution, choose WSL if your projects live in a Linux toolchain or you want the sandbox.
• You always verify before you trust. After install, `claude --version` confirms it's on PATH, and `claude doctor` runs a full health check. PATH, auth status, config, update status, and MCP servers. Running `claude doctor` immediately after install is the cheapest way to catch a broken PATH or a stale shell session before it confuses you mid-task.
• A session starts by changing into a project directory and running `claude`. On first use you authenticate through your browser with a Pro, Max, Team, Enterprise, or Console account, the free Claude.ai plan does NOT include Claude Code (this is the Lesson 3 access gate made real). Credentials are stored after the first login, so you don't repeat it each session, and you can re-authenticate or switch accounts later with `/login`.
• The first thing you do in any session is explore, not edit. Ask 'what does this project do?', 'explain the folder structure', 'where is the main entry point?', the agent reads files on its own, as needed, without you attaching anything. Reading is cheap, reversible, and teaches you how the agent reasons about your codebase before it can touch it.
• Claude Code asks permission before modifying files, and you control how much it can do with permission modes you cycle using Shift+Tab. Default mode asks before every file modification; there is also an Accept-edits mode, a read-only plan mode (stricter, no edits at all), and (on WSL) a sandboxed bypass mode. Keep it in default mode for the entire first session, the approval prompt exists precisely so you can say no after reading the diff.
• Essential session controls are slash commands: `/help` lists everything, `/clear` resets context, `/login` re-authenticates, `/config` opens settings, and `exit` or Ctrl+D leaves cleanly. Typing a bare `/` reveals all commands and installed skills, this is your in-session map.
• Codex has its own CLI for terminal workflows, and a critical default difference: in a git-tracked folder, Codex defaults to 'Auto' (workspace-write, it can edit and run commands in the working directory without asking), and only defaults to Read Only in non-version-controlled folders. Claude Code's default (ask-before-edit) mode and Codex's Read Only mode are the matching safe postures, but with Codex you must explicitly choose Read Only for a git repo's first run, because its out-of-the-box default in a repo is more permissive than Claude Code's.

Deeper dive

Step by step

1

Identify your shell, then run the matching install command

123

First confirm which shell you're in (your prompt shows `PS C:\` for PowerShell, plain `C:\` for CMD; macOS/Linux/WSL show a `$` or `%`). Then run the matching native install: macOS/Linux/WSL → `curl -fsSL https://claude.ai/install.sh | bash`; Windows PowerShell → `irm https://claude.ai/install.ps1 | iex`; Windows CMD → `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`. On native Windows, install Git for Windows first if you want the Bash tool instead of the PowerShell fallback. The installer should finish with an "installed to …" line, then verify properly in step 2.

HintIf you see `The token '&&' is not a valid statement separator`, you ran the CMD command in PowerShell, switch to the `irm … | iex` line. If you see `'irm' is not recognized`, you're in CMD, use the install.cmd line.

On this screen

1. 1What to notice. The Terminal/Tab in the docs holds the exact install command per shell, copy the one matching your prompt, not just your OS.
2. 2Why it matters. Native install auto-updates in the background; Homebrew/WinGet/npm do not and must be upgraded manually, pick native for the smoothest first install.
3. 3Windows detail. Git for Windows enables the Bash tool; without it Claude Code uses a PowerShell tool. WSL 2 is the only Windows path that supports the command sandbox.

2

Verify the install before you trust it

12

Run `claude --version` to confirm the binary is on your PATH, then run `claude doctor` for a full health check of PATH, auth, config, update status, and MCP servers. Read the doctor output, a green install here saves you from blaming the agent for a PATH problem later.

HintIf `claude` is 'command not found', open a fresh terminal so it picks up the updated PATH before assuming the install failed.

On this screen

1. 1What to notice. `claude doctor` is the one command that tells you whether install, PATH, and auth are all actually healthy, run it every time something feels off.
2. 2Two checks, two purposes. `claude --version` proves the binary is on PATH (the version line is the pass signal); `claude doctor` goes deeper, the OK lines for installation and auto-update are what 'healthy' looks like.

3

Open a throwaway project and authenticate via the browser

123

Change into a low-stakes directory, a fresh scratch repo (`git init` in an empty folder) or a copy of a real project, never production. Run `claude`. On first use a browser tab opens; complete login with your Claude Pro, Max, Team, Enterprise, or Console account. Do NOT paste an API key into the chat, the browser OAuth flow stores credentials for you.

HintThe free Claude.ai plan does not include Claude Code (Lesson 3's access gate), confirm you're on an eligible plan before you start, not mid-task.

On this screen

1. 1What to notice. You cd into the project folder and run `claude`; the welcome banner appears and the browser opens for login, credentials are stored, so you won't repeat this next session. The demo shows a real-looking project folder (~/projects/my-app); yours should be the scratch repo you just created.
2. 2Security. Auth happens in the browser; the long-lived secret never enters your shell history or the chat. Re-auth or switch accounts later with /login.
3. 3Blast radius. A scratch or copied project means the worst possible first-run mistake is deleting a throwaway folder, bound the risk before you grant any permission.

4

Lock default mode, the ask-before-every-edit mode

12

Press Shift+Tab to cycle permission modes and confirm you're in default mode, the mode that asks before every file modification, not Accept-edits and not any bypass mode. Plan mode is even stricter (no edits at all), but for this lesson you WANT the agent able to propose one edit in step 6, default keeps the approval prompt armed without blocking the exercise. Type `/help` to see the command list and confirm you can find `/clear`, `/login`, and `/config`. Type a bare `/` to reveal all commands and installed skills.

HintResist Accept-edits on your first session, you want to see and read every proposed action while you're still building trust in how the agent behaves.

On this screen

1. 1What to notice. Shift+Tab cycles the modes; default is the one that pauses on every write so you can review the diff first.
2. 2The footer names the mode. Each Shift+Tab press changes the footer label, default asks before edits and commands, acceptEdits auto-accepts, plan is read-only. Stop cycling when it reads default.

5

Run a fully read-only exploration

12

Paste the read-only first-contact prompt from this lesson as your opening message, then let it work. Read its answers and confirm it is only reading files, naming which file and why when it opens one, and not proposing any edits. Follow up with 'where is the main entry point?' if it didn't already cover it.

HintWatching a few complete read-and-answer cycles before any write is possible is how you calibrate the agent on YOUR code at zero risk.

On this screen

1. 1What to notice. A well-behaved read-only session explains and cites the files it reads, and never slips a code suggestion into the answer.
2. 2Files cited, no edits offered. A healthy read-only session looks like this, it names the files it reads (package.json, src/index.ts, README.md) and answers in prose without proposing a single change.

6

Approve exactly one tiny, reviewed, reversible change

12

Send the 'first reviewed change' prompt, ask for a single one-line comment at the top of the README explaining what the project is. When Claude Code shows the proposed diff and asks for approval, READ the diff line by line before approving. After it applies, ask 'what files have I changed?' and verify the answer matches the diff you approved.

HintReading the diff before approving is the single load-bearing habit of the whole course, the approval prompt exists so you can say no.

On this screen

1. 1What to notice. The diff is the contract: approve only what you can see and understand, and verify afterward that nothing extra changed.
2. 2This prompt is the gate. The demo shows a different edit (a hello-world function), but the UI is identical to what you'll see for your README line: the proposed diff, then 'Do you want to make this edit?', and No is always one of the answers.

7

Note the Codex CLI path and its different default

Visit developers.openai.com/codex and note the Codex CLI install paths: standalone (`curl -fsSL https://chatgpt.com/codex/install.sh | sh`), npm (`npm install -g @openai/codex`, use the scoped name, not the unrelated 2012 `codex` package), or Homebrew (`brew install --cask codex`). Authenticate with `codex` (Sign in with ChatGPT or an API key; `codex login --device-auth` for headless). Critically: in a git repo Codex defaults to Auto (workspace-write, it can edit and run without asking), so for a safe first run explicitly choose Read Only via `/approvals` or `--sandbox read-only`.

HintCodex's in-repo default (Auto) is more permissive than Claude Code's default mode, don't assume the same safety posture carries over; set Read Only yourself. And install the scoped `@openai/codex` package: the unscoped `codex` on npm is an unrelated 2012 project that produces confusing errors.

8

Close the session cleanly

1

Back in Claude Code, run `/clear` to reset context, then `exit` (or Ctrl+D) to end the session deliberately rather than just closing the window. This leaves a clean state and is the habit that prevents stale context bleeding into your next, real task. You know it worked when your next claude session opens with no memory of this one.

HintEnding on `/clear` + `exit`, not a closed window, is the same discipline as logging out of a shared machine: deliberate, clean, repeatable.

On this screen

1. 1Clear, then exit. /clear empties the conversation context (the 'CLAUDE.md still loaded' line refers to project standing instructions, covered in Lesson 6); exit ends the session cleanly, and the goodbye line shows claude -c / claude -r exist if you ever need to resume.

Production prompt examples

ROLE: You are a careful senior engineer onboarding to an unfamiliar codebase. For THIS entire reply, you are in strict read-only mode.

CONTEXT: This is my first session with you in this repository. I have not yet decided whether to let you make any changes. I want to understand the project before granting any write permission.

TASK: Explore and explain only. Do not propose, stage, or make any edits. Do not run shell commands, install anything, or touch git.

DO:
- Tell me in 3-5 sentences what this project does and who it is for.
- Describe the top-level folder structure and what each main directory is responsible for.
- Identify the main entry point and the single most important file to read first, with a one-line reason.
- Flag anything that looks risky to change (config, secrets, generated files, migrations).

DO NOT:
- Suggest a single code change.
- Read more files than you need; if you open something, say which file and why.

OUTPUT FORMAT:
1. What this project is (3-5 sentences).
2. Folder map (bullet per top-level dir).
3. Read-this-first file + reason.
4. Change-with-care list.

ROLE: Senior engineer making the smallest possible reversible change so I can practice reviewing a diff.

CONTEXT: We just finished a read-only exploration of this scratch repo. I now want to grant exactly ONE tiny change and review it before it is applied.

TASK: Add a single one-line comment at the very top of README.md that states, in plain language, what this project is. Change nothing else.

CONSTRAINTS:
- Show me the proposed change as a diff and WAIT for my approval before writing anything.
- Touch only README.md. Do not reformat the file, reorder lines, or alter any other content.
- Do not run git, do not commit, do not stage. I will handle version control.
- Keep your explanation to one sentence.

AFTER I APPROVE:
- Apply only the approved diff.
- Then tell me exactly which file(s) changed so I can verify.

Common mistakes to avoid

• Running the install command for the wrong shell, pasting the CMD `&&` line into PowerShell (or `irm` into CMD) and getting a confusing separator/'not recognized' error instead of an install.
• Doing your first run inside a production or important directory instead of a fresh scratch repo or a disposable copy.
• Pasting a raw API key into the agent's chat instead of using the browser OAuth flow (or an env var for headless), leaking a long-lived secret into context and logs.
• Enabling Accept-edits (or any bypass mode) on the first session, so changes happen before you've learned to read the diffs.
• Approving a proposed change without reading the diff, the approval prompt is there for review, not just to click through.
• Assuming Codex inherits Claude Code's cautious default, in a git repo Codex defaults to Auto (workspace-write), so it can edit and run without asking unless you set Read Only.
• Installing the unscoped `codex` npm package by mistake instead of `@openai/codex`, then chasing errors with no obvious cause.
• Skipping `claude doctor` after install and later blaming the agent for what is actually a PATH or stale-shell problem.

Source conflicts to review

• Claude Code install commands verified against the official code.claude.com/docs/en/setup page (June 2026). Install URLs and PATH locations occasionally change between major versions, re-copy from the docs Tabs rather than from memory or older blog posts.
• Codex CLI's official quickstart shows install + 'sign in' but does NOT teach a read-only-first discipline, and in a git repo the CLI defaults to Auto (workspace-write), not Read Only. The safe first-run posture in this lesson is the deliberate, recommended practice, not the out-of-the-box default. Verify the current default on the agent-approvals page before relying on it.
• The Node.js floor differs by tool and source: Claude Code's npm package documents Node 18+; third-party guides cite Node 22+ for Codex's npm path while OpenAI's quickstart does not state a version. Prefer the native/standalone installer (no Node dependency) on a first install, and check the npm page if you go the npm route.
• Codex's session-level command to change approval mode is documented as `/approvals` on the developer docs and `/permissions` in some write-ups, if one doesn't appear, type `/` to list the current commands for your installed version.