Claude · 07 · Part 4

Installation and First Steps

This is where the guide becomes hands-on. You will install Claude Code, sign in, create the Java/Spring Boot project that carries through the rest of the series, and have a first conversation about it. Commands come from Anthropic's setup documentation; the project and its outputs were built and run on this machine while writing the page.

Install routes

Learning project

Exercises

Map · 01 World of AI · 02 AI in Dev · 03 Coding Agents · 04 Ecosystem · 05 Anthropic & Claude · 06 Claude Code · 07 Installation · 08 Prompting · 09 Real Projects · 10 Capabilities · 11 Workflows · 12 Your Environment · 13 Security · 14 Future · 15 Prompt Library · 16 Recipes · 17 Reading Output · 18 First Skill · 19 Skill Pack · 20 First Subagent · 21 Agent Teams · 22 Hooks Lab · 23 MCP Lab · 24 Plugins · 25 Headless CI · 26 Capstone · 27 Cheat Sheet

Information current as of: 2026-10-30 — installation details change often; re-check Source 1 before relying on them.

Chapter One · Before You Begin

Prerequisites

Claude Code's setup page lists these requirements (Source 1):

Item	Requirement
Operating system	macOS 13.0+; Windows 10 1809+ or Windows Server 2019+; Ubuntu 20.04+; Debian 10+; Alpine Linux 3.19+
Hardware	4 GB+ RAM; x64 or ARM64 processor
Network	An internet connection is required
Shell	Bash, Zsh, PowerShell or CMD
Location	A country on Anthropic's supported-countries list
Account	A Pro, Max, Team or Enterprise plan, a Claude Console account, or a supported cloud provider. The free claude.ai plan does not include Claude Code.

For this guide's project you also need a JDK (Java 21 is used here) and Git. Maven is optional because the project ships a Maven wrapper.

Chapter Two · Installation

Pick an Install Route

Install routes and whether they update themselves

macOS, Linux and WSL (recommended)

Native installer — from the setup docs · not run here: Claude Code was already installed

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

Windows

PowerShell

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

CMD

$ curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

If you see The token '&&' is not a valid statement separator you are in PowerShell, not CMD; if irm is not recognised you are in CMD, not PowerShell.

Package managers

Route	Command	Updates
Homebrew	`brew install --cask claude-code` (stable channel; `claude-code@latest` for the latest)	Manual: `brew upgrade claude-code`
WinGet	`winget install Anthropic.ClaudeCode`	Manual: `winget upgrade Anthropic.ClaudeCode`
apt, dnf, apk	Signed repositories; the docs give key-verification steps for each	Through your system upgrade workflow
npm	`npm install -g @anthropic-ai/claude-code` (Node.js 22+; never with `sudo`)	`npm install -g @anthropic-ai/claude-code@latest`

Windows: native or WSL?

Option	Needs	Sandboxing	When
Native Windows	Nothing; Git for Windows optional	Not supported	Windows-native projects and tools
WSL 2	WSL 2 enabled	Supported	Linux toolchains or sandboxed command execution
WSL 1	WSL 1 enabled	Not supported	If WSL 2 is unavailable

Without Git for Windows, Claude Code runs shell commands through PowerShell; with it, through Git Bash (Source 1). Since this guide uses Bash and Maven examples, WSL 2 is the smoothest Windows route.

Verify the installation

$ claude --version

Actual output · executed 2026-10-30 · Linux

2.1.314 (Claude Code)

The docs say a working install prints a version number followed by (Claude Code). If your shell says claude is not found, the install directory is not on your PATH. The docs also offer claude doctor for read-only install and settings diagnostics; it was not run for this page.

Chapter Three · Authentication

Subscription or API: How You Pay and Sign In

Run claude and follow the browser prompts. The accepted account types are (Source 2):

Account	How you sign in	Billing basis
Claude Pro or Max	Your claude.ai account in the browser	Subscription
Claude for Teams or Enterprise	The claude.ai account your admin invited	Seat plan, optional usage credits (Source 3)
Claude Console	Console credentials; a "Claude Code" workspace is created for cost tracking	API tokens
Cloud provider	Environment variables for Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry; no browser login	Your cloud bill

The API key trap. If ANTHROPIC_API_KEY is set in your environment and you approve it when asked, Claude Code uses the key, not your subscription. That fails if the key belongs to a disabled or expired organisation. /status shows which credential is active; unset ANTHROPIC_API_KEY falls back to the subscription (Source 2).

Credentials on disk. On macOS they go in the Keychain; on Linux in ~/.claude/.credentials.json with mode 0600 (Source 2).
Two accounts. Give each its own CLAUDE_CONFIG_DIR; the docs show an alias such as claude-work.
Cost. Claude Code charges by API token consumption on API plans; subscriptions are priced separately. Section 5 of Chapter 5 and Source 3 cover the numbers.
Not covered here: current subscription prices were not retrieved for this page; see Anthropic's pricing page.

Chapter Four · Where You Work

Terminal and IDE Setup

Terminal. Any terminal that runs Bash, Zsh, PowerShell or CMD works. New to terminals? The docs link a terminal guide. Start Claude in a project directory: starting it in your home directory is allowed, but trust acceptance is then held only for that session and the prompt reappears each launch (Source 4).
VS Code. The extension needs VS Code 1.94.0 or later and an Anthropic account (a paid plan or Console). It bundles its own copy of the CLI for its panel, but it does not put claude on your PATH: install the standalone CLI for use in the integrated terminal (Source 5).
JetBrains (IntelliJ IDEA and others). A marketplace plugin adds interactive diffs and selection sharing; it requires the Claude Code CLI to be installed separately (Source 1).
Desktop and web. A desktop app (Linux version in beta) and claude.ai/code exist; this guide uses the CLI because its commands are easy to copy and script.

All surfaces share one engine, so the CLAUDE.md, settings and MCP servers you set up later work in each (Chapter 6).

Chapter Five · The Learning Project

Create "bookshelf", a Spring Boot REST App

Every example from here on uses one small application, bookshelf: a book-catalogue REST API. This chapter creates version 1 (an in-memory list). Chapter 9 grows it into a JPA-backed service, and Chapter 10 adds a Claude Code setup around it.

How the learning project grows

Generate it with Spring Initializr

Prerequisites: JDK 21, curl, unzip. Network access to start.spring.io

$ curl -s https://start.spring.io/starter.zip \
  -d type=maven-project -d language=java -d bootVersion=4.1.2.RELEASE \
  -d baseDir=bookshelf -d groupId=com.example -d artifactId=bookshelf \
  -d name=bookshelf -d packageName=com.example.bookshelf \
  -d javaVersion=21 -d dependencies=web -o bookshelf.zip
$ unzip -q bookshelf.zip && cd bookshelf

A real snag, kept on purpose. The generated pom.xml named the parent version 4.1.2.RELEASE, but Maven Central publishes it as 4.1.2. The first build failed with Non-resolvable parent POM … Could not find artifact org.springframework.boot:spring-boot-starter-parent:pom:4.1.2.RELEASE. Changing the version to 4.1.2 fixed it. Generated files are input to verify, not truth — a theme of Chapter 9.

The v1 code

src/main/java/com/example/bookshelf/BookController.java

package com.example.bookshelf;

import java.util.List;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/books")
public class BookController {

  private final BookService service;

  public BookController(BookService service) {
      this.service = service;
  }

  @GetMapping
  public List<Book> list() {
      return service.findAll();
  }
}

Book.java, BookService.java and the test (expand)

Book.java

package com.example.bookshelf;

public record Book(long id, String title, String author, int year) {
}

BookService.java

package com.example.bookshelf;

import java.util.List;
import org.springframework.stereotype.Service;

@Service
public class BookService {

  private final List<Book> books = List.of(
          new Book(1, "Clean Code", "Robert C. Martin", 2008),
          new Book(2, "Effective Java", "Joshua Bloch", 2018),
          new Book(3, "Refactoring", "Martin Fowler", 2018));

  public List<Book> findAll() {
      return books;
  }
}

BookControllerTest.java

@WebMvcTest(BookController.class)
@Import(BookService.class)
class BookControllerTest {

  @Autowired
  MockMvc mvc;

  @Test
  void listReturnsAllBooks() throws Exception {
      mvc.perform(get("/api/books"))
              .andExpect(status().isOk())
              .andExpect(jsonPath("$.length()").value(3))
              .andExpect(jsonPath("$[0].title").value("Clean Code"));
  }
}

Build, test and run it

$ ./mvnw -B test

Actual output (excerpt) · executed 2026-10-30 · Spring Boot 4.1.2, Java 21.0.2, Maven 3.10.0 via wrapper

 :: Spring Boot ::                (v4.1.2)
...
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 3.886 s -- in com.example.bookshelf.BookControllerTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

$ ./mvnw -B spring-boot:run &
$ curl -i localhost:8080/api/books

Actual output (excerpt) · app started in 2.167 s

HTTP/1.1 200
Content-Type: application/json
Content-Length: 209

[{"id":1,"title":"Clean Code","author":"Robert C. Martin","year":2008},{"id":2,"title":"Effective Java","author":"Joshua Bloch","year":2018},{"id":3,"title":"Refactoring","author":"Martin Fowler","year":2018}]

What happened: the wrapper downloaded its own Maven, Maven compiled the app and ran the one test, and Spring Boot started an embedded Tomcat on port 8080 serving the list as JSON. You now have something an agent can read, run and change.

Put it under Git now. git init -b main && git add -A && git commit -m "Initial bookshelf". Chapter 6 explained that checkpoints cover only the current session's file edits; Git is your durable undo.

Chapter Six · The First Session

Start Claude Code and Ask About the Repository

Not executed for this page: starting a session needs a signed-in account

$ cd bookshelf
$ claude

On first use Claude Code prompts you to log in. Afterwards the prompt appears with the version, current model and working directory shown above it (Source 6). Type /help for commands or /resume to continue an earlier conversation.

Anatomy of a session (schematic, not a screenshot)

Questions that cost nothing and change nothing

The quickstart recommends beginning with read-only questions (Source 6). Use the project's own vocabulary:

Typed into the session prompt

what does this project do?
what technologies does this project use?
where is the main entry point?
explain the folder structure
how does a request to GET /api/books reach the service?

Claude reads project files as needed, so you do not need to attach anything (Source 6). The docs also let you ask Claude about its own capabilities, for example "how do I create custom skills in Claude Code?", and it answers from current documentation.

Illustrative — written for this guide, not captured from a real session

> what does this project do?

(Claude searches the project, reads pom.xml and the Java sources)

bookshelf is a Spring Boot 4.1 web application on Java 21. It exposes one
endpoint, GET /api/books, handled by BookController, which delegates to
BookService. The service returns a fixed in-memory list of three books.
There is one controller test using MockMvc.

Treat any such answer as a claim to check. A good habit from Chapter 2: ask for the files it based the answer on, and open one.

A first change, with the safety on

The quickstart's first edit is deliberately small: ask for a change, and approve the proposed edit when asked. Press Shift+Tab to change the permission mode (Source 6). For now stay in Manual mode, where edits and commands prompt you, and read each prompt (Chapter 6 lists the modes).

A small, checkable first task

add a GET /api/books/{id} endpoint that returns one book, or 404 if the id does not exist.
follow the existing controller style, add a test, and run ./mvnw -B test when you are done.

That prompt already uses three ideas from Chapter 8: a precise goal, a style to follow, and a check Claude can run.

Chapter Seven · Basic Commands

What to Type, and Where

Shell command	What it does
`claude`	Start interactive mode
`claude "task"`	Start with an initial prompt
`claude -p "query"`	Run one query, print the answer, exit
`claude -c`	Continue the most recent conversation in this directory
`claude -r`	Pick a previous conversation to resume

Inside a session	What it does
`/help`	Show available commands
`/clear`	Clear conversation history
`/resume`	Continue a previous conversation
`/status`	Show which credential and settings are active
`/exit` or `Ctrl+D` twice	Leave Claude Code
`/` then Tab	Browse commands and skills; Tab completes
`@path`	Include a file's contents in your message
`Shift+Tab`	Cycle permission modes
`Esc`	Interrupt Claude and steer

The first table is from the quickstart (Source 6) and was cross-checked against this machine's claude --help in Chapter 6. /status comes from the authentication docs (Source 2); the complete command list is in Anthropic's commands and CLI references.

Chapter Eight · Common Mistakes

Installing and Starting Out

1 · Installing with sudo npm. The docs warn against it: permission problems and security risk, and a sudo install cannot auto-update. Prefer the native installer.

2 · Two installs fighting. An npm install, a Homebrew cask and the native installer can all put a claude on your PATH. If the version surprises you, check for a second installation.

3 · An old ANTHROPIC_API_KEY overriding your login. Check /status before assuming your plan is being used.

4 · Starting in the wrong folder. Claude Code works relative to the directory you start it in. Start in the project root so CLAUDE.md, settings and Git state are the right ones.

5 · Approving every prompt on autopilot. Manual mode only protects you if you read what you approve; the security page says you are responsible for reviewing proposed code and commands.

6 · Starting without Git. Without commits, a bad edit has no durable undo. Initialise the repository first.

Chapter Nine · Summary

Key Takeaways, Exercises and Sources

∑ Installation and first steps — what to remember

Use the native installer unless you have a reason not to; package-manager installs need manual updates.
Verify with claude --version, and check /status to see which credential is in use.
The free claude.ai plan does not include Claude Code; use a paid plan, a Console account or a cloud provider.
Generated projects need checking. The Initializr pom needed a one-line fix before it would build.
Start with read-only questions, stay in Manual mode at first, and keep the project in Git.

Exercises

Exercise 1 Beginner

Install Claude Code, run claude --version, and start a session in an empty temporary folder. Ask it "what can Claude Code do?" and note which of the capabilities from Chapter 6 it mentions. Do not modify any files.

Learning outcome: complete install, sign-in and a first read-only session.

Exercise 2 Intermediate

Generate the bookshelf project, build it with ./mvnw -B test, and start a Claude Code session in it. Ask for the folder structure and the request path for GET /api/books, then open the files it named and verify each claim.

Learning outcome: check an agent's description of code against the code itself.

Exercise 3 Advanced

Set up two separate configuration directories (CLAUDE_CONFIG_DIR) with shell aliases, one for work and one for personal use. Use /status in each to confirm the credential, and write down which credential wins if ANTHROPIC_API_KEY is also set.

Learning outcome: understand credential precedence before it causes a surprise.

Sources (read on 2026-10-30; paraphrased, at most one short quote per source)

Anthropic, Advanced setup and Claude Code overview — requirements, install commands, update behaviour, Windows options, JetBrains plugin.
Anthropic, Authentication — accounts, login, API-key precedence, credential storage, multiple accounts.
Anthropic, Manage costs effectively — billing basis and usage tracking.
Anthropic, Security — workspace trust and the home-directory note; user responsibility.
Anthropic, VS Code extension — version requirement, bundled CLI, PATH note.
Anthropic, Quickstart — first session, example prompts, essential commands, permission-mode shortcut.

Executed on this machine, 2026-10-30: claude --version (2.1.314); Spring Initializr project generation; ./mvnw -B test and spring-boot:run with Spring Boot 4.1.2, OpenJDK 21.0.2 (Temurin), Maven 3.10.0 (wrapper); a curl against the running app. Not executed: the installers, claude doctor, and any Claude Code session. The session transcript above is labelled illustrative.

LearningTree

07 · Installation and First Steps | Claude Guide