Claude Code setup: install, auth, and first project

Claude Code setup means installing the CLI, authenticating, and configuring the first project so Claude can read your repo safely. This guide walks through native install on macOS, Linux, and Windows, then /init, CLAUDE.md, permissions, MCP, and a basic verification loop.

Updated July 2026 from Anthropic's Claude Code quickstart and setup docs. After install, keep the Claude Code cheat sheet open for commands, and read Claude Code best practices for workflows.

What you need before Claude Code setup

• A Claude subscription or Anthropic Console account.
• A terminal on macOS, Linux, WSL, or Windows.
• Git for Windows if you run Claude Code natively on Windows and want the Bash tool.
• A project directory you can open and modify.

Install Claude Code

Anthropic recommends the native installer. npm install is deprecated for Claude Code.

macOS, Linux, and WSL

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

Homebrew is also supported, but it does not auto-update:

brew install --cask claude-code

Windows

In PowerShell:

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

Or with WinGet:

winget install Anthropic.ClaudeCode

Confirm the binary is on your PATH:

claude --version

Authenticate and open your first project

1. Change into the project you want Claude to work on.
2. Run claude to start an interactive session.
3. Complete browser login when prompted.
4. Use /login later if you need to switch accounts.

cd your-project
claude

If install or auth fails, run /doctor inside a session or claude doctor from the shell and fix the reported PATH, auth, or config issues.

Initialize CLAUDE.md with /init

CLAUDE.md is the project memory Claude reads at the start of every session. Run /init to generate a starter file, then edit it so it includes build commands, test commands, code style, and hard constraints.

/init

Keep CLAUDE.md short and specific. Prefer runnable commands over long policy essays.

• How to install dependencies
• How to run tests, lint, and typecheck
• Preferred frameworks and patterns in this repo
• Files or directories Claude should avoid

Configure settings scopes and permissions

Claude Code settings can live at user, project, or local scopes. Start strict, then allow common safe tools as you trust the workflow.

1. Open /permissions.
2. Allow read-only tools and frequent safe commands.
3. Keep ask or deny on destructive shell commands, force-push, and production deploy scripts.
4. Revisit permissions after the first real feature, not before.

Project settings belong in the repo when the whole team shares the same rules. Local overrides stay on your machine for experiments.

Add one MCP server and one useful hook

MCP connects Claude Code to external tools and data. Start with one server you will use daily, not a long list. See Anthropic's MCP docs for server setup details.

1. Run /mcp and add the server you need.
2. Authenticate if the server requires it.
3. Confirm the tools appear and work on a small task.

Add one hook that protects quality, such as a Stop hook that runs tests or lint before Claude ends a turn. One reliable gate beats five noisy automations.

Verify the setup

Before you treat Claude Code as ready, run this checklist:

1. claude --version prints a version.
2. claude opens your project and can list files.
3. CLAUDE.md exists and mentions your real test command.
4. /permissions reflects your allow and ask rules.
5. Claude can run the test or build command and report the result.
6. /doctor reports a healthy install.

Common Claude Code setup errors

• command not found: claude — restart the shell, or fix PATH after native install.
• Auth loop or expired session — run /login and complete browser auth again.
• Windows missing Bash tools — install Git for Windows, or use WSL.
• Homebrew or WinGet feels stale — those channels do not auto-update; upgrade the package manually.
• Claude ignores project rules — put them in CLAUDE.md and keep the file concise.
• Permissions prompts every turn — allowlist the safe tools you use constantly.

What to do next

Once Claude Code is installed, use the Claude Code best practices guide for plan mode, verification, context management, and review. Keep the Claude Code cheat sheet open for slash commands while you work.