Getting started · Claude Code

A layman's guide to Claude Code setup.

Everything you need installed, in order, with the reason for each one. Budget an hour the first time. You will not need it again.

You are installing four things.

Knowing which is which makes the error messages readable later.

An account

With Anthropic. This is the part you pay for.

An editor

The window you work in. We use VS Code.

Claude Code

The agent itself.

A few small tools

What the agent uses to do real work.

You will not write any code. You copy a line, paste it, press Enter. If a line fails, the last section of this page has the fix.

Check this before you start

Claude Code needs a paid Claude plan. Pro, Max, Team, Enterprise or Console. The free tier does not include it, and you only find out when the login fails an hour in.

You also need macOS 13 or later, or Windows 10 version 1809 or later.

Why we tell beginners to install VS Code first.

Claude Code runs perfectly well in a bare terminal, and plenty of experienced developers use it that way. We do not recommend that if this is your first time, and the reason has nothing to do with the agent.

A terminal shows you nothing. It is a black rectangle with a blinking cursor. When Claude says it edited three files, a terminal gives you no way to see those files, no way to look at what changed, and no way to undo it. You are trusting an agent you cannot watch.

Visual Studio Code is a free, normal application. Your project appears as a folder in a sidebar. When Claude changes a file you see the change highlighted, line by line, and you can reject it. Copy and paste work with a mouse. The terminal lives in a panel at the bottom of the same window, so nothing is hidden behind another app.

There is also an official extension that puts Claude in a proper panel: you review its plan before it acts, you point at files by name, and past conversations stay in tabs. For a first-timer that difference is the difference between finishing and giving up.

The install, in order.

Do these top to bottom. Each step assumes the one above it worked. Commands go into the terminal, which after step 2 lives inside VS Code.

Install Visual Studio Code

Download it from code.visualstudio.com, open the file, and drag it into Applications on a Mac or run the installer on Windows. It is free and made by Microsoft. Open it once so it finishes setting itself up.

Then open its terminal: the menu is View, then Terminal. A panel appears at the bottom with a blinking cursor. That panel is where every command below goes.

Give your computer the basic build tools

On a Mac, one command installs the standard developer tools, including Git, which is how code is downloaded and versioned. A dialog will pop up; click Install and wait. It is a large download.

$ xcode-select --install

Then install Homebrew, which is how you install almost everything else on a Mac afterwards. It will ask for your password and explain what it is about to do.

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

At the end Homebrew prints two or three lines under a heading like Next steps. Those lines are not decoration. Copy and run them, or the brew command will not exist in new terminal windows. This is the single most common place a first install goes wrong.

On Windows, install Git for Windows and click Next through every screen. You do not need to learn Git. It is there so Claude Code can run ordinary commands.

Homebrew does not need you to install Ruby

Older advice says it does. Homebrew's installer is a plain shell script now and macOS already includes what it needs. If a context system asks for Ruby later, step 6 has the command; you do not need it to get this far.

Install Claude Code

On a Mac or Linux, paste this into the terminal panel and press Enter:

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

On Windows, use PowerShell. You are in PowerShell if the line starts with PS C:\, and in CMD if it does not.

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

Check that it worked. This should print a version number:

$ claude --version

If it says command not found, jump to the last section on this page. It is a one-line fix and it catches almost everybody.

Add the VS Code extension and sign in

In VS Code press Cmd+Shift+X on a Mac or Ctrl+Shift+X on Windows to open Extensions, search for Claude Code, and click Install. You need VS Code 1.94 or newer, which any fresh download will be.

Open the panel and sign in with your Claude account. A browser window opens; approve it and come back. No API key, no billing setup: the paid plan you already have is the login.

Cmd+Esc or Ctrl+Esc jumps between your files and Claude's prompt box. It is the shortcut you will use most.

Connect GitHub

GitHub is where the systems live and where your own work can be backed up. The command line tool for it is gh, and it handles the login for you so you never deal with keys or tokens.

$ brew install gh
$ gh auth login

Answer the prompts: GitHub.com, HTTPS, yes to authenticate Git, and Login with a web browser. It shows you an eight character code, opens a browser, and you paste the code in. On Windows install it from cli.github.com and then run gh auth login the same way.

Install a language, but only if a system asks

Some systems need a language installed, because that is what their scripts are written in. Each system's page says which. Install only what you are asked for.

$ brew install python
$ brew install node
$ brew install ruby

On Windows, download the installer from python.org, nodejs.org or rubyinstaller.org. During setup, tick any box that mentions PATH. That one checkbox saves you the next step.

Not sure what you need? Clone the system, open it in VS Code, start Claude and ask what do I need installed to run this? It reads the repo and tells you.

If the terminal says a command is not found

This is the step that catches almost everyone, and it does not mean the install failed.

Your computer keeps a list of folders to look in when you type a command. That list is called your PATH. If a program lands somewhere the list does not cover, the terminal says command not found even though the program is sitting right there on your disk. Installing something and telling the terminal where it went are two separate jobs, and installers do not always do the second one.

The easy way. Open Claude in the VS Code terminal and say it plainly:

I installed node but the terminal says command not found. Fix my PATH.

It can read your shell settings, work out where the program went, and add the right line. This is a perfectly respectable way to do it, and it is faster than the manual route.

The manual way, on a Mac. Add the folder to the file your terminal reads at startup, then reload it. Replace the path if the installer told you a different one:

$ echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

Anything an installer prints under a heading like Next steps is usually this exact fix. Homebrew prints it, and skipping it is the single most common reason a first setup stalls. Scroll back up in the terminal and run those lines.

To check it worked, ask the program to tell you its version. Any answer means the terminal has found it:

$ node --version

Settings worth changing on day one.

These are the small frustrations that make people quit in week one. All of them are one setting. In VS Code, open settings with Cmd+, or Ctrl+, and paste the setting name into the search box.

Selecting text with the mouse does something strange

In VS Code's terminal, dragging can select a rectangular block of characters, which makes copying a whole error message maddening. Turn on terminal.integrated.macOptionClickForcesSelection and Option+click gives you ordinary line selection again.

Enter sends before you have finished typing

Run /terminal-setup once inside Claude Code. It teaches VS Code that Shift+Enter means a new line. Ctrl+J also works everywhere with no setup.

Option key shortcuts do nothing on a Mac

Set terminal.integrated.macOptionIsMeta to true. Terminals do not pass the Option key through by default.

You walk away and miss when it finishes

VS Code's terminal does not raise desktop notifications. Add "preferredNotifChannel": "terminal_bell" to ~/.claude/settings.json and you get a sound instead.

Pasting something long loses characters

A real limitation of VS Code's terminal on very large pastes. Save the text to a file and ask Claude to read the file. This is better practice anyway, because Claude can refer back to the file later in the conversation.

Backspace deletes a whole word (Windows)

Some Windows terminals send the wrong signal. Set the environment variable CLAUDE_CODE_BS_AS_CTRL_BACKSPACE to 0.

The screen flickers while it works

Run /tui fullscreen. It switches to a steadier way of drawing the screen and remembers the choice.

The five things to know before your first session.

Esc stops it

If Claude is doing something you did not want, press Escape. It stops immediately and nothing is lost.

It asks before it changes anything

Creating or editing a file needs your approval. Read what it is about to do. Approving without reading is how people get surprised.

Describe the outcome you want

Say what you want to end up with. You do not need to know how it should be done, and guessing at the method usually produces worse results than saying nothing.

Start it inside the folder you care about

Claude reads the project you open it in. Opening the wrong folder is the most common reason it seems to know nothing about your work.

/help lists everything

Type it any time. /clear starts a fresh conversation, which is worth doing when you change task.

When something goes wrong.

Four errors account for most first installs. None of them means you did anything wrong.

command not found: claude

The installer worked; your terminal does not know where it put things. On a Mac run the two lines below, then close the terminal panel and open a new one.

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

brew: command not found

You skipped the Next steps lines Homebrew printed at the end of its install. Scroll back up in the terminal, find them, and run them.

'irm' is not recognized

You are in CMD on Windows. Close it, press Win+X, and choose Windows PowerShell or Terminal.

Claude Code is not part of the free tier. Check the plan on your Anthropic account before troubleshooting anything else.

Anything else

Run claude doctor. It checks the installation and settings and prints what is wrong with suggested fixes, without starting a session.

One habit worth forming immediately

When something breaks, paste the error into Claude and ask what it means. It can read your files, check your setup and usually fix it. The agent you just installed is also the best help desk you have for installing it.

Install steps here were checked against Anthropic's documentation on 21 August 2026. Claude Code ships often, so if a command has changed, the official setup page is the source of truth.

Set up and nowhere to point it? Start with a system.

Browse the catalog What is a context system?