Claude Code Setup Guide: From Install to First Autonomous Task

#Claude Code Setup Guide: From Install to First Autonomous Task

Claude Code is Anthropic's agentic coding tool that lives in your terminal, reads your codebase, edits files, runs commands, and handles git workflows through plain-English requests instead of copy-pasting between a chat window and your editor. Getting from a fresh install to genuinely autonomous work — the kind where you describe a feature and walk away while Claude plans, writes, tests, and commits it — takes about fifteen minutes if you follow the steps in order and skip none of the configuration that actually matters.

Most setup guides stop at 'run claude and start typing.' That gets you a working chat session, not an autonomous one. This guide covers the full path: installing correctly for your platform, verifying the install actually worked, understanding which account type you need, the permission-mode system that determines how much Claude can do without asking, the CLAUDE.md file that turns Claude from a generic assistant into one that understands your specific codebase, connecting external tools through MCP, and finally, running a task genuinely hands-off from start to finish.

#What Claude Code Actually Is, Before You Install It

Claude Code isn't a chat window bolted onto your editor, and it isn't an autocomplete engine. It's an agentic loop: Claude reads relevant files, decides what tools to call, executes them, reads the results, and repeats until the task is done or it needs your input.

That loop is what makes 'autonomous' a meaningful word here rather than marketing language. A single request like 'add input validation to the registration form' triggers Claude to locate the relevant file, read the surrounding code for context, write the validation logic, and, depending on your permission settings, run the test suite to confirm nothing broke — all without you switching windows to paste code back and forth. Claude Code runs primarily in your terminal, but the same underlying agent is also available in a desktop app, a VS Code extension, JetBrains IDEs, Slack, and headless in CI/CD pipelines through GitHub Actions and GitLab. This guide focuses on the terminal CLI, since it's the foundation every other surface builds on.

#Step 1: Confirm Your System Meets the Requirements

Before installing anything, check that your machine actually qualifies. Claude Code runs on macOS 13.0 or later, Windows 10 build 1809+ (or Windows Server 2019+), Ubuntu 20.04+, Debian 10+, and Alpine Linux 3.19+, and needs at least 4GB of RAM on an x64 or ARM64 processor plus a working internet connection. Your shell needs to be Bash, Zsh, PowerShell, or CMD — all common defaults, so this rarely trips anyone up. The one requirement worth double-checking in advance is availability: Claude Code is only available in Anthropic's supported countries, so if you're setting this up somewhere with regional restrictions, confirm access before spending time on the rest of this guide.

• macOS: version 13.0 or later, any Apple Silicon or Intel Mac
• Windows: 10 build 1809+ or Windows Server 2019+, running natively or inside WSL
• Linux: Ubuntu 20.04+, Debian 10+, or Alpine Linux 3.19+ (Alpine needs a few extra packages, covered below)
• Hardware: 4GB+ RAM, x64 or ARM64 processor, and an active internet connection
• If you plan to install via npm specifically: Node.js 22 or later as of the current release — the native installers below don't need Node.js at all

#Step 2: Install Claude Code for Your Platform

Anthropic ships several install paths, and which one you pick affects how updates behave later, so it's worth choosing deliberately rather than grabbing whichever command shows up first in a search result.

The native installer is the recommended default because it auto-updates in the background, keeping you on the latest version without any manual steps. On macOS, Linux, or WSL, run curl -fsSL https://claude.ai/install.sh | bash in your terminal. On native Windows using PowerShell, run irm https://claude.ai/install.ps1 | iex. On native Windows using CMD, run curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd. If you get an error about '&&' not being a valid statement separator, you're actually in PowerShell and need the PowerShell command instead; if you see 'irm is not recognized,' you're in CMD and need the CMD command. Your prompt tells you which one you're in: PowerShell shows PS C:\ and CMD shows just C:\ without the PS prefix.

Beyond the native installer, Homebrew users can run brew install --cask claude-code, which offers two casks: the plain claude-code cask tracks a stable release channel about a week behind the newest build, while claude-code@latest tracks new releases immediately. Windows users comfortable with WinGet can run winget install Anthropic.ClaudeCode. Debian, Fedora, RHEL, and Alpine users can install through their native package managers (apt, dnf, or apk) using Anthropic's signed repositories, though this requires a few extra setup steps to register the repository and verify the signing key first. Whichever method you choose except the native installer, note that updates won't happen automatically — you'll need to run the upgrade command for your specific package manager periodically.

• Native installer (recommended): auto-updates in the background, no manual maintenance required
• Homebrew: brew install --cask claude-code, requires brew upgrade claude-code manually to update
• WinGet: winget install Anthropic.ClaudeCode, requires winget upgrade manually to update
• npm: npm install -g @anthropic-ai/claude-code, requires Node.js 22+ and npm install -g @anthropic-ai/claude-code@latest to update (avoid npm update -g, which won't reliably grab the newest release)
• apt/dnf/apk: available for Debian, Fedora, RHEL, and Alpine through Anthropic's signed package repositories, useful for server and CI environments already standardized on a Linux package manager

On native Windows specifically, installing Git for Windows first is recommended but optional — it gives Claude Code access to Git Bash so it can use the same Bash tool available on macOS and Linux. Without Git for Windows, Claude Code falls back to a PowerShell-based tool instead, which works fine for most tasks but behaves slightly differently for certain shell operations. WSL setups don't need Git for Windows at all, since they already run a real Linux shell.

#Step 3: Verify the Install Actually Worked

Don't skip this step just because the install command finished without visible errors. Run claude --version in your terminal — a working installation prints a version number followed by (Claude Code), something like 2.1.211 (Claude Code). If you instead get command not found or a similar error, the binary either didn't land on your PATH or the install genuinely failed partway through, and troubleshooting that now is far less frustrating than discovering it mid-task later. For a deeper check beyond the version number, run claude doctor, which prints read-only diagnostics covering install health, any settings-file validation errors, and specific suggested fixes for anything it finds — without starting an actual session.

#Step 4: Log In With the Right Account Type

Claude Code requires a Pro, Max, Team, Enterprise, or Console account — the free Claude.ai plan does not include Claude Code access, which trips up more first-time users than any technical setup step in this guide.

Start an interactive session by running claude in your project directory, and on first use you'll be prompted to log in through your browser. A Claude Pro, Max, Team, or Enterprise subscription is the recommended option for most individual developers and small teams. A Claude Console account works too, and is billed through pre-paid API credits rather than a flat subscription; on first login with a Console account, Claude Code automatically creates a dedicated 'Claude Code' workspace for centralized cost tracking. Larger organizations can also authenticate through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry if that's already how they manage cloud AI spend, or through a self-hosted gateway if their organization runs one. If you've already set the ANTHROPIC_API_KEY environment variable before running claude, it skips the browser login entirely and just asks you to approve the key instead. Once you've logged in the first time, your credentials are stored locally and you won't need to repeat this step; to switch accounts or re-authenticate later, type /login inside a running session.

#Step 5: Start Your First Session and Ask Real Questions

Navigate to an actual project directory before starting Claude Code — cd /path/to/your/project, then run claude. You'll see the prompt with the current version, active model, and working directory displayed above it. Resist the urge to immediately ask for a code change; start by asking Claude to explain what it's looking at instead. Try what does this project do?, what technologies does this project use?, or where is the main entry point?. Claude Code reads your project files as needed to answer these, so you don't need to manually paste in any context — that's the entire point of running inside your actual codebase instead of a generic chat window. You can also ask Claude directly about its own capabilities, which is a genuinely useful habit early on: questions like what can Claude Code do? or can Claude Code work with Docker? get you accurate, current answers instead of guessing from outdated blog posts.

#Step 6: Make Your First Change and Understand Permission Modes

Try something small and low-stakes for your first real edit, like add a hello world function to the main file. What happens next depends entirely on which permission mode your session is running in, and understanding that system now saves real confusion later.

In your very first session after installing, Claude Code asks before every change regardless of plan, so you'll see an approval prompt — select Yes to let it proceed. After that first session, the built-in starting permission mode differs by plan: on Pro, Max, and Team plans, interactive terminal sessions default to auto mode, where a classifier reviews Claude's actions in place of you asking for each one manually, and Claude edits most files and runs most commands without an explicit prompt. On other plans, the default is a manual mode where you approve each action individually. Either way, you're never locked into the starting mode — press Shift+Tab at any point during a session to cycle through permission modes on the fly, tightening control before a risky operation or loosening it once you trust what Claude's doing on a given task.

#Step 7: Write a CLAUDE.md File So Claude Understands Your Project

A CLAUDE.md file at your project root is the single highest-leverage setup step most developers skip, and it's the difference between Claude re-guessing your conventions every session and Claude simply knowing them.

This is a plain Markdown file Claude Code automatically loads at the start of a session, and it's where you put anything you'd otherwise have to repeat in every conversation: which package manager the project uses, testing conventions, code style rules, which directories are safe to modify versus which are generated and off-limits, and any project-specific terminology or architecture decisions that aren't obvious from the code alone. You can create one manually, or ask Claude Code to generate a starting draft by exploring your codebase first, which tends to catch conventions you'd forget to write down yourself. For larger codebases, you can layer multiple CLAUDE.md files at different directory levels rather than maintaining one enormous file, and teams can deploy a shared CLAUDE.md across an entire organization so every developer's Claude Code session starts from the same baseline understanding of house style and constraints.

#Step 8: Connect External Tools Through MCP (Optional But Worth Doing Early)

The Model Context Protocol lets Claude Code reach beyond your local filesystem to read your team's Jira tickets, query a database directly, pull design files from Figma, or update documents in Google Drive, all through the same conversational interface you're already using for code. Adding a server is usually a single command — running claude with the appropriate mcp add flag and a server's connection details registers it, and Claude Code verifies the connection before you start relying on it. Servers can be scoped locally to just your current project, shared with your whole team through a checked-in configuration file, or set at the user level so they're available across every project you work in. This step is genuinely optional for a first session, but if your workflow regularly involves checking a ticket tracker or querying a database alongside writing code, setting up the relevant MCP server now saves you from manually copy-pasting that context into every future session.

#Step 9: Run Your First Genuinely Autonomous Task

Everything up to this point has been interactive — you're in the loop for every step. A genuinely autonomous task is different: you hand off a well-scoped piece of work and Claude plans, executes, verifies, and reports back with minimal or zero interruption.

The simplest version of this is a one-off, non-interactive query: run claude -p "query" from your terminal, and Claude executes the request and exits, which is exactly the pattern you'd use inside a script or a CI pipeline rather than an interactive session. For a task with more steps, describe the full scope up front rather than issuing instructions one at a time — something like fix the bug where users can submit empty registration forms: add validation, write a test for it, and commit the change with a descriptive message gives Claude enough scope to plan the whole sequence, implement it, verify it against your test suite, and hand you a finished commit rather than a half-done edit waiting on your next instruction. This works best in auto mode, where Claude isn't stopping to ask permission for every intermediate step, and it's worth deliberately practicing on a low-stakes task first — a documentation update or a small refactor — before trusting a genuinely autonomous run on something touching production code.

• Scope the task fully in your first message rather than issuing it step by step — autonomy works best when Claude has the complete picture upfront, not a drip-fed sequence of instructions
• Ask for verification as part of the task itself — 'and run the tests to confirm' turns a blind autonomous edit into one that checks its own work before finishing
• Start with something reversible — a new branch, a docs update, a test file — before letting an autonomous run touch anything you'd hate to redo by hand
• Use claude -c to continue your most recent conversation in the current directory, or claude -r to resume a specific previous conversation, so a multi-step autonomous task can pick back up exactly where it left off
• Watch the first full run closely even in auto mode — you're building intuition for what Claude does unprompted, which makes every subsequent autonomous task easier to scope well

#Common First-Week Mistakes Worth Avoiding

The most common early mistake is treating Claude Code like a search-and-paste chatbot — describing a problem in a single vague sentence instead of giving it the specific context a colleague would need. 'Fix the login bug' produces a much weaker result than 'fix the login bug where users see a blank screen after entering wrong credentials,' because the second version tells Claude exactly what to look for instead of making it guess. The second common mistake is skipping CLAUDE.md entirely and re-explaining project conventions in every session, which wastes both your time and context budget that could otherwise go toward the actual task. The third is jumping straight to a large, vague autonomous task before running a handful of small interactive ones first — you'll get much better autonomous results once you've seen how Claude approaches your specific codebase on lower-stakes work.

#Quick Reference: Commands Worth Memorizing

A handful of commands cover the overwhelming majority of daily use, and memorizing them now is faster than looking each one up the first time you need it mid-task.

• claude — start an interactive session in the current directory
• claude "task" — start an interactive session with an initial prompt already queued
• claude -p "query" — run a single one-off query non-interactively, then exit; the pattern for scripts and CI
• claude -c — continue your most recent conversation in the current directory
• claude -r — resume a specific previous conversation from a picker
• /clear — clear conversation history inside a running session without exiting
• /help — list available commands inside a running session
• /login — switch accounts or re-authenticate inside a running session
• claude doctor — print read-only installation and configuration diagnostics without starting a session
• claude --version — confirm your installed version

#You're Set Up. Now Build the Habit

Everything above gets you from an empty terminal to a working, genuinely autonomous Claude Code setup, but the setup itself isn't where the real gains show up.

The developers who get the most out of Claude Code aren't the ones with the most exotic MCP integrations or the longest CLAUDE.md file — they're the ones who treat it like a capable but literal-minded colleague: specific requests over vague ones, real project context over assumed context, small trusted tasks before large autonomous ones, and a habit of asking Claude to verify its own work rather than assuming success. Install correctly, write a CLAUDE.md that actually reflects how your team works, understand what permission mode you're running in before you need to care, and the jump from 'chat window that edits files' to 'agent I can hand a real task to and walk away from' happens faster than most new setup guides suggest.