Claude Code: install, connect & start building

• A computer you control and can install software on.
• The ability to open a terminal, or the willingness to use the desktop app instead.

Two things can stop you before you start: an operating system that is too old, and an account that does not include Claude Code. Both are quicker to check now than to diagnose after a failed install.

The documentation lists the supported platforms as macOS 13.0 or later, Windows 10 1809 or later, Windows Server 2019 or later, Ubuntu 20.04 or later, Debian 10 or later, and Alpine Linux 3.19 or later. Hardware is 4 GB or more of RAM and an x64 or ARM64 processor. An internet connection is required, and the shell can be Bash, Zsh, PowerShell or CMD.

1. 1

   Step 1: Check your operating system version against that list.

   On a Mac, the Apple menu then About This Mac. On Windows, Settings then System then About.

2. 2

   Step 2: Check which Claude plan your account is on.

   The documentation states that Claude Code requires a Pro, Max, Team, Enterprise, or Console account, and that the free Claude.ai plan does not include Claude Code access.

3. 3

   Step 3: Decide which surface you want: the terminal, or the desktop app.

   The desktop app includes Claude Code, so you do not need to install the CLI separately. This guide follows the terminal, because it is the surface the documentation treats as the full-featured one and the one every later step assumes.

4. 4

   Step 4: Pick the folder you intend to work in, and write the path down.

   Not the desktop, and not your whole home directory. A single project folder with files you would not mind seeing changed.

You are not installing anything in this section. You are removing the two reasons the install would have failed.

Nothing to save. Note the folder path somewhere you can see it, because you will type it in section 3.

Before moving on, confirm all three:

1. Your operating system is at or above the listed minimum for your platform.
2. Your Claude account is on a plan that includes Claude Code.
3. You have chosen one specific folder, and it is not your entire home directory.

• Section 1 complete: a supported operating system and a plan that includes Claude Code.
• A terminal open. On a Mac that is Terminal; on Windows it is PowerShell or CMD.

The documentation calls the native install the recommended method, and gives a different one-line command for each platform. Use the one that matches where you are typing, not the one you saw first.

On Windows the two shells look similar and take different commands. Your prompt shows PS C:\ when you are in PowerShell and C:\ without the PS when you are in CMD.

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

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

brew install --cask claude-code

winget install Anthropic.ClaudeCode

claude --version

1. 1

   Step 1: Open your terminal and run the install command for your platform, copied exactly.

   You do not need to run as Administrator on Windows.

2. 2

   Step 2: Wait for the install to finish, then run claude --version.

   A working installation prints a version number such as 2.1.211 (Claude Code).

3. 3

   Step 3: If you want a fuller check, run claude doctor.

   It prints read-only installation and settings diagnostics without starting a session, including install health and any warnings with suggested fixes.

4. 4

   Step 4: On native Windows, consider installing Git for Windows.

   The documentation recommends it so Claude Code can use the Bash tool. Without it, Claude Code uses PowerShell as the shell tool instead. WSL setups do not need it.

Native installations update themselves in the background. Homebrew and WinGet installations do not, and are upgraded with their own commands when you choose to.

Nothing to save by hand. The installer places the command for you.

If claude --version worked, that result is the thing you are keeping from this section.

Run the version command and read the output:

1. claude --version prints a version number followed by (Claude Code).
2. The command did not report command not found.
3. Optionally, claude doctor reports no warnings you do not understand.

• Section 2 complete: claude --version prints a version.
• The folder path you wrote down in section 1.
• A browser you are signed in to with the Claude account you intend to use.

These two things happen together, and the order matters. You move into the folder first, then start Claude Code, because the directory you launch it from is the directory it can reach.

On first launch Claude Code opens a browser window for you to log in. When login completes, the terminal shows Login successful and prompts you to press Enter to continue.

cd your-project
claude

/login

/status

1. 1

   Step 1: In your terminal, change into the folder you chose, replacing your-project with your own path.

   If you are unsure you are in the right place, list the folder contents before you continue. Starting in the wrong directory is the single most common way a first session goes wrong.

2. 2

   Step 2: Run claude.

   Claude Code opens an interactive session in your terminal.

3. 3

   Step 3: Complete the login in the browser window that opens.

   If the browser does not open automatically, press c to copy the login URL to your clipboard and paste it into your browser yourself.

4. 4

   Step 4: If the browser shows a login code instead of returning you to the terminal, paste that code at the prompt that reads Paste code here if prompted.

   The documentation notes this happens when the browser cannot reach Claude Code's local callback server, which is common in WSL2, SSH sessions and containers.

5. 5

   Step 5: Run /status and read which account is signed in.

   Do this before any real work. If you have more than one Claude account, this is the moment to find out which one you actually attached.

Once logged in, your credentials are stored and you will not need to log in again for each session.

Above the prompt you will see the version, the current model, and the working directory. Read the working directory line and confirm it is the folder you meant.

Nothing to save. Claude Code stores the credential itself and reuses it in later sessions.

To detach the account later, run /logout at the Claude Code prompt.

You are connected when all three are true:

1. The terminal showed Login successful.
2. The working directory shown above the prompt is the folder you chose in section 1.
3. /status names the account and organization you meant to use.

• Section 3 complete: a live session in the right folder, signed in to the right account.

Your first instruction should be a question, not a change. You are testing two things at once: that Claude Code can actually see your project, and that you can read what it tells you well enough to catch it being wrong.

Claude Code reads your project files as needed, so you do not have to manually add context.

what does this project do?

explain the folder structure

/help

1. 1

   Step 1: Type what does this project do? and press Enter.

   Claude will analyze your files and provide a summary.

2. 2

   Step 2: Read the answer against what you already know about the folder.

   This is the actual test. You are not checking whether the answer sounds good; you are checking whether it describes your folder and not a generic project.

3. 3

   Step 3: Ask one follow-up you already know the answer to.

   Something like explain the folder structure. If you can catch a wrong answer here, you can catch one later when it matters.

4. 4

   Step 4: Type /help to see what commands are available in your session.

If the summary describes files you recognise, the connection between Claude Code, your account, and your folder is proven end to end. That is the whole purpose of this section.

If it describes something you do not recognise, stop here. Almost always it means the session is running in a different directory than you think.

Nothing to save. This section deliberately produces no artefact.

What you keep is the knowledge that the session sees your real project.

Read the answer, then confirm:

1. The summary names at least one file or folder you recognise by sight.
2. Nothing in your folder changed. Check the folder in your file browser if you want to see it for yourself.
3. You could tell whether the answer was right, rather than only whether it sounded confident.

• Section 4 complete: the session demonstrably sees your project.
• One small, low-stakes file you would not mind being wrong for ten minutes.

This is the section the whole guide exists for. Everything before it was setup; everything after it is optional. Keep the first edit small enough that you can check it by looking.

Before you ask for the change, know how to undo it. Claude Code automatically captures the state of your code before each user prompt, and you reopen those points with /rewind, or by pressing Esc twice when the prompt input is empty.

add a hello world function to the main file

/rewind

what files have I changed?

1. 1

   Step 1: Ask for one small change, in plain language.

   Claude Code finds the appropriate file and shows you the change. If it asks before making the change, select Yes to approve.

2. 2

   Step 2: Open the changed file yourself and read it.

   In your normal editor, or your file browser. Do not accept the session's own description of what it did as proof that it did it.

3. 3

   Step 3: Run /rewind and look at the menu without choosing anything yet.

   The menu lists each prompt you sent during the session. Seeing it once, before you need it, is the point of this step.

4. 4

   Step 4: Practise the undo: choose Restore code, then check the file again.

   The two code restore options appear only when the selected checkpoint has tracked file changes to revert. Restore code reverts file changes while keeping the conversation.

5. 5

   Step 5: Ask for the change again, and this time keep it.

   You now know the change is reversible, which is the only reason to be relaxed about the next hundred of them.

Know the limits of that undo before you rely on it. Checkpointing does not track files modified by bash commands, and it does not restore edits made by most subagents. Only direct file edits made through Claude's file editing tools are tracked.

The documentation is explicit that checkpoints are for quick, session-level recovery and are not a replacement for version control.

Claude Code writes the file for you. There is no separate save step for the edit itself.

If the change is one you want to keep beyond this session, section 6 covers committing it, which is the only durable save.

Do these in order, and do not skip the second one:

1. You opened the file outside Claude Code and saw the change with your own eyes.
2. You opened the /rewind menu and saw your prompts listed.
3. You restored the code once, confirmed the file went back, and then re-applied the change on purpose.

• Section 5 complete: one verified, reversible change.
• For the Git steps, a folder that is already a Git repository, or the willingness to make one.

Claude Code understands your entire codebase and can work across multiple files and tools to get things done. That is the capability worth having, and it is also the point at which session-level undo stops being enough.

Claude Code works directly with git: it stages changes, writes commit messages, creates branches, and opens pull requests. In practice this means you can ask for version control in the same plain language as everything else.

what files have I changed?

commit my changes with a descriptive message

create a new branch called feature/first-try

/init

1. 1

   Step 1: Ask what has changed, and read the answer before you commit anything.

2. 2

   Step 2: Ask for a branch before you attempt anything larger than a one-file edit.

   A branch is what lets a bad afternoon be discarded rather than unpicked.

3. 3

   Step 3: Ask Claude Code to commit, then check the result yourself.

   A commit is the first save in this guide that survives closing the terminal, deleting the session, and the checkpoint retention window.

4. 4

   Step 4: Once, and only once you have a project you keep returning to, run /init.

   It generates a starting CLAUDE.md by analyzing your codebase, with build commands, test instructions and conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.

CLAUDE.md is a markdown file in your project that Claude Code reads at the start of every session. Treat it as the place you write down what you would otherwise re-explain, and keep it short: the documentation targets under 200 lines per file, because longer files consume more context and reduce adherence.

That is as far as this guide takes CLAUDE.md. It is genuinely useful on the second project and mostly a distraction on the first.

The commit is the save. Everything before it is recoverable only for as long as the session's checkpoints survive.

Claude Code deletes a session's file snapshots in a retention sweep, by default about 30 days after the session last saved one.

Confirm the work is genuinely saved:

1. Your Git history shows the commit, checked outside Claude Code.
2. The commit message describes what actually changed.
3. If you ran /init, you have read the generated CLAUDE.md and corrected anything it got wrong about your project.

• Sections 1 to 6 complete, or at least section 5: you have seen the tool make a change.

This section is last because it is easier to understand once you have watched the tool work, and it is the most important section on the page. A permission mode sets which actions Claude can take in a session without asking you first.

You may not be in the mode you assume. On Pro, Max and Team plans the built-in starting permission mode is auto mode, in which a second model, the classifier, reviews actions instead of you. In Manual mode, Claude Code stops and asks you before most actions that edit files, run shell commands, or reach the network.

Shift+Tab

claude --permission-mode default

/permissions

claude --permission-mode plan

1. 1

   Step 1: Find out which mode your session is actually in, and switch modes with Shift+Tab.

   The mode that reviews every action is named Manual in the CLI. Its config value is default, which is why the flag reads --permission-mode default.

2. 2

   Step 2: For your first weeks, prefer Manual mode.

   In Manual mode the only thing that runs without asking is reading. File edits, shell commands and network access stop and ask you.

3. 3

   Step 3: Learn to read a permission prompt before you answer it.

   Read the actual command or file path in the prompt, not the sentence around it. Approving once is different from approving permanently: choosing Yes, and don't ask again saves a rule to .claude/settings.local.json at the root of the repository.

4. 4

   Step 4: Know how to stop it mid-action: press Esc.

   Esc interrupts Claude or closes a dialog. Ctrl+C interrupts a running operation or clears the input. Ctrl+D exits the session.

5. 5

   Step 5: Start a fresh session when the work changes.

   Use /clear to clear the conversation history. A session that has drifted across three unrelated tasks gives worse answers than a new one aimed at the task in front of you.

6. 6

   Step 6: Review what you have approved with /permissions.

   The dialog lists all permission rules and the settings.json file each rule comes from, so a rule you approved in a hurry three weeks ago is visible rather than invisible.

Refusing an action costs you nothing. If a prompt asks to run something you do not recognise, decline it and ask Claude in plain language what it was trying to do and why.

Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or CLAUDE.md shape what Claude tries to do, but they do not change what Claude Code allows.

To make every terminal session on your machine start in Manual mode, set permissions.defaultMode to "default" in ~/.claude/settings.json.

That is a deliberate, persistent choice, and it is the one this guide recommends for a first month.

You are in control when you can do all four:

1. You can say which permission mode your current session is in.
2. You can switch to Manual mode and see the prompts appear.
3. You have pressed Esc to stop Claude at least once, on purpose.
4. You have opened /permissions and read what is already approved.