Claude Code Setup Guide: Install, Authenticate, and Complete a Safe First Task

Claude Code is most useful when it can inspect a real repository, make a bounded change, run the project’s own checks, and show you the diff. Installation is only the first step. A reliable setup also needs the right authentication route, a narrow initial permission posture, concise project instructions, and a verification loop.

This guide uses Anthropic’s official documentation as checked on August 9, 2026. Claude Code changes frequently, so confirm the installation and command references before applying them to a managed fleet.

Choose a supported surface and account path

Claude Code is available through the terminal, desktop application, IDE integrations, and web workflows. Start with the surface that matches where the repository and its toolchain already live. The terminal is the clearest baseline because file access, commands, working directory, and Git state are visible.

Authentication and API keys are not the same thing. Claude Code currently supports:

a Claude Pro or Max account;
Claude for Teams or Enterprise;
an invited Claude Console account;
Amazon Bedrock, Google Vertex AI, or Microsoft Foundry through the organization’s cloud credentials.

An individual subscription user normally signs in through the browser. Do not create or export an API key merely because an old setup guide says every user needs one. Cloud-provider installations use their provider configuration instead of the browser flow.

For an organization, decide the authentication path before distributing the client. It determines billing, credential storage, model availability, data handling, and which managed controls apply. Do not mix a personal subscription, a Console API account, and cloud-provider credentials in one rollout without documenting precedence and support ownership.

Install the current native client

Anthropic recommends the native installer. The current requirements include macOS 13 or later; supported Windows, Ubuntu, Debian, and Alpine releases; an x64 or ARM64 processor; at least 4 GB of RAM; and internet access. On native Windows, Git for Windows is recommended, while WSL 2 is the better choice when the project depends on a Linux toolchain or sandboxed command execution.

On macOS, Linux, or WSL:

curl -fsSL https://claude.ai/install.sh | bash

On Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

On Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Homebrew and WinGet are supported alternatives:

brew install --cask claude-code

winget install Anthropic.ClaudeCode

Native installations update in the background. Homebrew and WinGet installations require their package-manager upgrade commands. Choose one installation owner per machine. Multiple native, legacy npm, and package-manager binaries can make the version you launch differ from the version you believe you upgraded.

Verify the executable before opening a repository:

claude --version
claude doctor

claude --version proves which client runs. claude doctor performs a broader configuration check. If the command is missing, inspect the executable path and shell configuration; do not disable TLS validation or use sudo npm install -g as a shortcut around a broken installation.

Authenticate without exposing a credential

Run Claude Code from a terminal:

claude

The first launch opens a browser login. In WSL, SSH, or a container, the browser may show a code instead of reaching the local callback; paste that code into the terminal prompt. You can also use the explicit CLI commands:

claude auth login
claude auth status --text

Use claude auth login --console when the intended billing path is an invited Console account. Use the documented Bedrock, Vertex, or Foundry setup when the organization selected a cloud provider. To switch identities, log out and authenticate again:

claude auth logout

Check the active identity and provider with /status inside a session. Diagnose authentication by credential source and shell scope, not by printing a token. Never paste a secret into a prompt, commit it to .env, append it to a shared shell profile, or include it in a screenshot. If a secret is exposed, revoke or rotate it first and investigate second.

Start inside one clean repository

Claude Code’s working directory defines the project context and available files. Begin with a repository you can safely modify and inspect its state yourself:

cd path/to/project
git status --short
claude

If the working tree contains changes you do not own, do not ask Claude to clean or reset it. Either choose a clean worktree or constrain the task so existing work remains untouched.

Use a read-first prompt before requesting an edit:

Inspect this repository and explain:
1. the application entry points,
2. the build and test commands,
3. the files that define the requested behavior,
4. any existing uncommitted changes.
Do not edit files or run mutating commands.

Then choose a small task with an observable result. A good first task changes one behavior and has a focused test or deterministic check. Avoid “improve the project,” a framework migration, a production deployment, or a broad dependency update.

Use an explicit first-task contract

A useful task prompt contains five parts:

Goal:
Fix the registration form so an empty email shows the existing validation style.

Context:
The form is under src/features/registration. Use the current validation library.

Constraints:
- Do not change the API contract.
- Do not modify unrelated formatting.
- Preserve existing uncommitted work.

Non-goals:
- No redesign.
- No dependency upgrades.

Validation:
- Add or update a focused test.
- Run the focused test and existing type check.
- Show the final git diff and summarize residual risk.

Ask Claude to inspect and plan before editing when the repository or risk is unfamiliar. Permission modes can support that workflow, but a mode is not a substitute for scope. Review every proposed command and write until you understand what the client, repository, and task require.

After the edit, independently inspect the evidence:

git status --short
git diff --check
git diff

Run the repository’s own focused and required checks. A confident summary is not test evidence. Also verify that tests were not weakened, unrelated files did not change, and generated output or lockfiles changed only when the task requires them.

Write a concise project `CLAUDE.md`

Claude Code loads CLAUDE.md as project instructions. A project file can live at ./CLAUDE.md or ./.claude/CLAUDE.md and is normally committed for the team. CLAUDE.local.md is for personal project notes and should stay ignored.

Use /init to create a starting proposal, then review it. The file should contain information Claude cannot reliably infer on every session:

# Project instructions

## Commands

- Install: `npm ci`
- Focused tests: `npm test -- --run path/to/test`
- Required checks: `npm run lint && npm run check && npm test -- --run`

## Architecture boundaries

- Server code lives under `src/server`.
- Browser components must not import database modules.
- Public API changes require a versioned migration note.

## Workflow

- Preserve user-owned work.
- Add a failing regression test before a bug fix.
- Show `git diff --check` and required check output before completion.

## Security

- Never print or commit credentials.
- Stop before deployment, payment, deletion, or access changes.

Keep always-loaded instructions short and specific. Anthropic recommends targeting fewer than 200 lines because project instructions consume context and long files can reduce adherence. Move path-specific rules closer to the relevant code and put detailed, task-triggered procedures in skills.

CLAUDE.md is behavioral context, not a hard security boundary. Enforce tool denial, sandboxing, network policy, authentication constraints, and managed organization policy through settings. If the repository already uses AGENTS.md, a small CLAUDE.md can import it with @AGENTS.md and add only Claude-specific details.

Add the minimum harness in stages

Claude Code extensions have distinct jobs:

Mechanism	Use it for
`CLAUDE.md`	Always-relevant project conventions and commands
Skills	On-demand procedures, references, scripts, and templates
Hooks	Deterministic actions at lifecycle events
MCP	Connections to external tools and data under explicit trust
Subagents	Isolated context and delegated investigation

Do not add every mechanism on day one. Start with project commands, architecture boundaries, and one verified task. Add a skill when a procedure repeats. Add a hook when a deterministic action must occur at a specific event. Add MCP only when the repository needs an external capability and the server, credentials, tool descriptions, and outputs have been reviewed. Add subagents or worktrees when tasks are genuinely independent and their write ownership is clear.

Learn the small set of controls you can verify

Inside interactive mode:

Ctrl+C cancels current input or generation.
Esc interrupts the response or tool call while preserving completed work.
Shift+Tab cycles enabled permission modes.
/help shows commands available in the installed version.
/status shows the active account and configuration state.
/memory shows loaded instruction and memory files.
/usage shows the current session or plan usage view.
/clear starts a fresh conversation; claude -c continues the recent project conversation and claude -r opens resume selection.

Terminal shortcuts vary by platform and configuration. Use the installed client’s /help and official interactive-mode reference instead of copying an old shortcut table.

Avoid the common first-week failures

The most common setup problems are workflow problems rather than installation failures:

Starting from a vague outcome with no acceptance criteria.
Letting one task mix investigation, migration, refactoring, and deployment.
Granting broad command or filesystem authority to avoid prompts.
Loading a long handbook into every session instead of using concise rules and skills.
Trusting generated tests without seeing them fail on the original defect.
Allowing the model to edit a dirty working tree without identifying ownership.
Committing with a broad staging command that hides unrelated files.
Treating the final response as evidence that the build or deployment passed.

Claude Code has finite context, can choose an incorrect approach, and can run in an environment that differs from CI or production. It also changes over time. Pin critical automation behavior, keep human review at consequential boundaries, and require external validation proportional to the change.

A practical completion checklist

Once this baseline works, deepen only the part the workflow needs: permissions and security, context, models, and cost, Git and parallel workflows, hooks, MCP, and automation, or the Claude Code comparison guide.