Build the floor before you ask Claude Code to build anything else
This part defines the vocabulary, teaches the first Bash commands, and gets Git, VS Code, and Claude Code installed with the current official guidance checked on April 6, 2026.
What Claude Code is
Claude Code is an AI coding tool that lives in your terminal. You give it instructions inside a project folder. It can read files, suggest edits, run commands, and help with Git. The important part is not that it can act. The important part is that you stay in charge of what action is allowed.
Read and act in a repo
Claude Code can inspect your files, explain them, propose edits, run shell commands, and help you review or create changes.
Not a judgment replacement
It can generate a plausible wrong answer. The most dangerous mistakes are not obvious syntax failures. They are confident, tidy, incorrect logic or bad decisions.
Supervise the loop
Pick the folder, frame the task, inspect the plan, approve carefully, review the diff, and keep Git checkpoints.
Do not treat Claude Code like an autonomous expert you can safely leave unsupervised. Treat it like a very fast teammate that still needs context, guardrails, and review.
If you can explain the difference between "Claude Code can make changes" and "Claude Code should be allowed to make changes," you are ready for the terminal fundamentals in Chapter 2.
Terminal, shell, Bash, files, and paths
To use Claude Code safely, you need to understand where you are, what program is reading your commands, and what a path points to. This is the minimum mental model.
Terminal vs shell vs Bash
Terminal: the window where you type text commands.
Shell: the program inside the terminal that reads those commands.
Bash: one specific shell. Many tutorials use Bash syntax, which is why learning a few Bash basics pays off quickly.
zsh: another shell, common on macOS. For the beginner commands in this guide, Bash and zsh feel almost the same.
PowerShell: a different shell, common on Windows. You can still use Claude Code there, but if you want the Unix-style command-line habits that most coding tutorials use, WSL plus Bash is a better fit.
The first commands you need
pwd
Shows your current working directory. In plain English: "Where am I right now?" You should see a path, such as /Users/alice or /home/alice.
ls
Lists the files and folders in the current directory. In plain English: "What is here?" You should see names like Desktop, Downloads, or project folders.
cd
Changes your location. cd Desktop moves into a folder named Desktop. cd .. moves up one level. cd ~ returns to your home folder. The ~ symbol is shorthand for home.
mkdir
Creates a new directory. If you run mkdir practice-folder, then ls, you should see practice-folder in the list.
What the dot in code . means
The dot means "the current directory." If you are standing in ~/projects/claude-code-playground and run code ., VS Code opens that exact folder.
Confidence check
Install the basics
This chapter gets your machine ready. We will install Git, configure it once, install VS Code, and then install Claude Code using the current recommended path from the official docs checked on April 6, 2026.
As of April 6, 2026, Anthropic's official docs recommend the native Claude Code installer. The older npm installation path is deprecated. This guide follows the current official path, not older tutorials.
Good default path
Use Terminal.app or iTerm2. Git may already be available through Apple's command line tools.
Ubuntu and Debian are easiest
Use your system terminal. The commands in this guide match the official Debian and Ubuntu style closely.
Choose your route deliberately
If you want Unix-style Bash habits, choose WSL plus Ubuntu. If you want fewer moving parts, native Windows plus Git for Windows also works.
Step 1: Git
Git tracks your project history. It is the safety net around AI edits. Without Git, you have no clean before-and-after record and no trustworthy change review.
| OS | Recommended move | Command or path |
|---|---|---|
| macOS | Run the version check first. If macOS prompts for command line tools, accept it. | git --version |
| Ubuntu / Debian | Install from apt. | sudo apt updatesudo apt install git |
| Windows | Install Git for Windows. Anthropic's docs explicitly require it for Claude Code on Windows. | git-scm.com/download/win |
| WSL | Open Ubuntu and install Git inside Linux too. | sudo apt updatesudo apt install git |
Step 2: Configure Git once
What this does:
user.nametells Git whose commits these are.user.emailadds your email to commit metadata.init.defaultBranch mainmakes new repositories start onmain.git config --listlets you verify the values actually stuck.
Step 3: VS Code
Install VS Code from the official download page. Then make sure the code command works in your terminal. That matters because we will use code . to open the current folder.
Add code to PATH
Open VS Code, press Cmd + Shift + P, run Shell Command: Install 'code' command in PATH, then restart Terminal.
CLI test
Run code --version. If you see a version number, the command is ready.
Step 4: Homebrew (macOS only)
A package manager for macOS. It lets you install developer tools with simple terminal commands instead of hunting for download links.
Linux users: your system's apt package manager serves the same purpose. Windows users: package management is handled through different tools.
Step 5: Node.js and npm
A runtime that lets you run JavaScript outside a browser. Many developer tools are built with it.
Some MCP servers, code formatters, and development tools require Node.js. While Claude Code's native installer doesn't need it, having Node available opens up more tools.
| OS | Install command |
|---|---|
| macOS | brew install node |
| Ubuntu / Debian | sudo apt install nodejs npm |
| Windows | Download from nodejs.org or winget install OpenJS.NodeJS.LTS |
Step 6: Python and pip
One of the most popular programming languages. Many AI tools, scripts, and utilities are written in Python.
| OS | Install command |
|---|---|
| macOS | brew install python (or may already be available as python3) |
| Ubuntu / Debian | sudo apt install python3 python3-pip |
| Windows | Download from python.org or winget install Python.Python.3.12 |
On some systems, use python and pip instead of python3 and pip3.
Step 7: Claude Code
Use the official native installer path that Anthropic recommends as of April 6, 2026.
What if Windows asks about WSL?
If you want the Bash-based workflow used in most coding tutorials, use WSL 2 plus Ubuntu. Microsoft's current install command is wsl --install from PowerShell run as Administrator, followed by a restart and first-time Ubuntu setup.
Step 8: Verification checklist
Login, verification, and first health check
Installation and account access are not the same thing. First make sure the command exists. Then confirm Claude Code can actually start and authenticate with an eligible account.
Run claude --version
If the installation worked, you should see a version number. If the terminal says claude: command not found, the install did not finish correctly or your terminal needs to be restarted.
Run claude doctor
This checks installation health and helps catch common environment problems. It is the fastest way to confirm the command is not just present, but basically healthy.
Launch Claude Code
Run claude. Follow the login prompts. If you need to switch accounts later, use /login inside Claude Code.
As of April 6, 2026, having access to the free Claude website experience is not the same thing as having Claude Code access. The official docs indicate Claude Code access comes through eligible paid Claude.ai plans, funded Anthropic Console usage, or supported enterprise and provider setups.
Command works
claude --version returns a version and claude doctor does not show a fatal setup issue.
Login completes
The app authenticates and returns you to a usable prompt inside Claude Code.
Entitlement confusion
The command exists, but login fails because the account type or billing setup is not eligible.
claude: command not found
Close the terminal fully, open a fresh terminal, and try claude --version again. If it still fails, rerun the official installer for your OS.
PowerShell says && is invalid
You used the Windows Command Prompt installer command inside PowerShell. Use the PowerShell command instead: irm https://claude.ai/install.ps1 | iex.
Claude Code starts, but authentication still fails
That usually means your account setup is the issue, not the binary install. Re-check which Claude or Console plan you have and whether billing is active where required.