Installation and First Run — Claude Code

Summary#

Claude Code is distributed as a single command-line binary published by Anthropic. The fastest path from “nothing installed” to “having a real conversation with the model about your repository” is three short steps: install the CLI, run claude once and sign in, then cd into a project and type what you want. Everything else — model picking, settings layers, IDE extensions — is optional polish on top of that loop.

This page exists because the first thirty minutes shape a lot. A bad first run (wrong directory, wrong model, surprise permission prompts) leaves people thinking the tool is fussy. A clean first run leaves you with a tool that fades into the background. The recipe below is the one that consistently produces the second outcome.

Why it matters#

The CLI is the canonical surface. The VS Code and JetBrains extensions, the desktop app, and claude.ai/code all wrap the same underlying agent loop and the same ~/.claude/ configuration directory. If you understand the CLI, you understand all of them. If you start in the IDE you tend to miss where settings live, where memory is written, and how to invoke the tool from a script later.

There are also three onboarding decisions that have outsized downstream effect:

Which model. Opus for hard reasoning, Sonnet for the daily driver, Haiku for cheap mechanical work. Pick the wrong default and your sessions feel either slow-and-expensive or shallow-and-wrong for the next month.
Where to put the user-global CLAUDE.md. Anything you write there is in the system prompt of every future session, on every project. It is the single highest-leverage paragraph in the whole tool.
Whether to opt into auto-update. Claude Code ships often. Pinning a version and forgetting about it is a slow tax in missed bug fixes; auto-update is the default for a reason.

Getting these three right at install time costs minutes. Getting them wrong and discovering it later costs a workday of cleanup.

How it works#

Install paths#

There are three first-class install paths. Pick the one that matches how your machine is normally provisioned.

macOS / Linux via the install script. curl -fsSL https://claude.ai/install.sh | sh drops the claude binary into ~/.local/bin and prints the post-install steps. This is the path Anthropic documents first and the one most engineers should take.
Homebrew on macOS. brew install anthropic/claude/claude is fine if you already keep all your tools under brew. The trade-off is that you depend on the brew tap being current; Anthropic’s own script ships updates faster.
npm. npm i -g @anthropic-ai/claude-code installs the CLI as a global npm package. Useful in containers and CI images that already have Node and don’t want a second package manager.

Windows is supported via WSL2 or a native installer; the WSL2 path is the one with the smoothest feature parity right now.

After install, claude --version should print a version string and which claude should point at a binary on your PATH. If both work, you’re done with the install step.

First run and auth#

Running claude for the first time launches an interactive TUI that walks through authentication. The two options are:

Sign in with Claude (recommended). Opens a browser to claude.ai and pairs your CLI session to your Anthropic account. Your usage is billed against your Claude Pro / Max / Team subscription. This is the path most individual engineers want.
API key. Paste an ANTHROPIC_API_KEY from the Anthropic Console. Usage is billed per-token against that key. This is the path for shared service accounts, CI, and any case where a subscription doesn’t apply.

The same first-run flow asks about telemetry preference, sets up the ~/.claude/ config directory, and lands you at a prompt. The TUI shows your model, your working directory, the active permission mode, and a small status bar — that’s the surface you’ll see for the rest of your time with the tool.

Picking a model#

Claude Code ships with three model tiers exposed via /model and the --model flag:

Opus — the strongest model in the family. Use for hard reasoning, multi-file refactors, dense research, and anything where being right matters more than being fast.
Sonnet — the balanced default. Faster than Opus, cheaper per token, strong enough for almost all day-to-day coding. Most sessions should run on Sonnet.
Haiku — the cheap, fast tier. Use for mechanical tasks: renaming, search-replace, simple lint fixes, anything where you’d be annoyed to spend Opus tokens.

The default for new installs is Sonnet. Override per session with /model opus, or set a global preference in ~/.claude/settings.json. Switching models mid-session is supported and the model swap takes effect on the next turn.

Your first conversation#

The canonical first run is: cd into a real repo (not a scratch directory), run claude, and ask a question that requires reading code. Three good first prompts:

“Read the top of this repo and give me a one-paragraph summary of what it does.”
“What are the entry points to this codebase?”
“Run the test suite and tell me which tests are slowest.”

Each one forces Claude to use a tool — Read, Grep, or Bash — which is the part of the experience that’s qualitatively different from a chat box. By the end of the first conversation you should have seen at least one tool call, at least one permission prompt (if you accepted defaults), and at least one model response that referenced specific files by path.

Variants and trade-offs#

CLI-first install — claude in your terminal as the daily driver. Lowest friction, fastest start-up, easiest to script and run headlessly later. The TUI is keyboard-native and stays out of your way. This is the path the rest of the workbook assumes.

IDE-first install — VS Code or JetBrains extension as the daily driver. Inline diffs, click-to-jump on file references, and visual diagnostics from the IDE. Heavier UI, but better for engineers who think visually or who already live in their editor.

The two are not mutually exclusive. Most engineers install both and pick whichever fits the task: CLI for headless work, scripts, and long sessions; IDE for tight review loops where seeing the diff inline matters. The configuration in ~/.claude/ is shared, so memory, permissions, and slash commands are consistent across surfaces.

On the auth dimension, the subscription path is almost always the right choice for an individual engineer — predictable monthly cost, no rate-limit surprises. The API-key path makes sense for shared automation (CI bots, scheduled agents) and for organisations that bill agent usage to a cost centre rather than a person. Mixing is fine: subscription locally, API key in CI.

The auto-update toggle defaults to on. Turning it off only makes sense for tightly controlled environments where you want to pin a version to a known-good build for a sprint. The trade-off is that you miss bug fixes and tool improvements that ship weekly.

When this is asked in interviews#

Almost never directly. Onboarding a tool isn’t a hiring signal. But the adjacent question shows up often:

“Walk me through how you’d evaluate a new agentic coding tool for your team.” The right answer covers install footprint, auth model, where data goes, model choice, and how it fits the existing dev environment. Knowing Claude Code’s install path lets you compare cleanly against Cursor, Aider, or an internal tool.
“How would you roll this out to a 50-person engineering org?” The interesting answer talks about pre-seeded CLAUDE.md files in major repos, a shared user-global config snippet, the auth model the company picks, and a short internal guide for the first run. The install step is the smallest piece of that rollout.
Developer-tooling / platform loops — the interviewer may ask about the differences between the CLI, IDE, and SDK install paths, and which one to expose to which user. The right framing is “same agent, different surface, shared config.”

Where it doesn’t come up: any role that isn’t itself about developer tools, and any team that has standardised on a different agentic CLI.

The single most useful first action after install

Open ~/.claude/CLAUDE.md in your editor and add three lines: your name, your role, and one collaboration preference (e.g. “prefer terse responses, no trailing summaries”). That file becomes part of the system prompt of every future session, on every project, for as long as you use the tool. Three lines you write once, paid back on every conversation.