Install Claude Code

Claude Code is the agent you'll use for nearly every hands-on exercise. You run it in an empty folder and paste the exercise prompt in, and many exercise projects also call it from code as claude -p when they need a model. Both run on your Claude subscription, so you don't need an API key for them.

Before you start

• A paid Claude plan: Pro, Max or Ultra on your personal claude.ai account. The free plan doesn't include Claude Code.
• OS: macOS 13+, Windows 10 1809+, Ubuntu 20.04+, Debian 10+ or Alpine 3.19+, with 4 GB of RAM or more.
• Windows: you can run Claude Code natively or inside WSL. Native Windows works without extra software. If you install Git for Windows, Claude Code uses Git Bash for shell commands; without it, it uses PowerShell.

1. Install Claude Code

Use the native installer. It updates itself in the background.

macOS, Linux, WSL

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

Windows PowerShell

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

Windows CMD

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

The installer shows no progress while it downloads. When it finishes, open a new terminal window and check the install:

claude --version

If you'd rather use Homebrew, run brew install --cask claude-code. That cask follows the stable channel and doesn't update itself, so run brew upgrade claude-code from time to time.

2. Sign in with your subscription

Start Claude Code in any folder:

mkdir claude-sandbox && cd claude-sandbox
claude

A browser window opens. Sign in with your claude.ai account and approve access. The terminal shows Login successful. If the browser doesn't open, press c to copy the login URL and paste it into a browser yourself.

You can also sign in from the shell without starting a session, and check which credential is active:

claude auth login
claude auth status --text

3. Run a first session

Inside the session, type a request in plain English:

Create a file hello.py that prints the current date, then run it.

Claude Code shows each file edit and shell command and asks for permission before running it. Useful commands inside a session:

For exercises, start each one in a fresh, empty folder so earlier files don't confuse it.

4. Use Claude Code headless with claude -p

-p (or --print) runs one prompt non-interactively, prints the answer and exits. It reads stdin too:

claude -p "Explain what a context window is in two sentences."
cat notes.txt | claude -p "Summarise these notes as five bullets."

JSON output

--output-format json returns one JSON object. The answer is in result, and there's also session_id, usage and an estimated total_cost_usd. On a subscription that figure is only an estimate; you aren't billed per call.

claude -p "Name three sorting algorithms." --output-format json | jq -r '.result'

Structured output with a schema

Add --json-schema with a JSON Schema, and the validated object comes back in structured_output:

claude -p "Extract the people and dates from: Ada met Charles on 5 June 1833." \
  --output-format json \
  --json-schema '{"type":"object","properties":{"people":{"type":"array","items":{"type":"string"}},"dates":{"type":"array","items":{"type":"string"}}},"required":["people","dates"]}' \
  | jq '.structured_output'

If Claude can't produce valid output, for example because it declined, the response has no structured_output field. Check that it's there before you use it.

Controlling tools

In a -p run nobody can answer a permission prompt, so any tool call that needs approval is denied. Two flags control this:

• --tools "Read,Grep" limits which built-in tools exist at all. --tools "" turns them all off, which makes claude -p a pure text-in, text-out model call.
• --allowedTools "Read,Edit,Bash(npm test *)" lets the listed tools run without asking. Rules use permission syntax: Bash(git diff *) allows any command starting with git diff.

Other flags exercises use: --model sonnet (aliases sonnet, opus, haiku), --max-turns 3, --append-system-prompt "…" and --no-session-persistence.

Calling it from code

Exercise projects run claude -p as a subprocess and parse the JSON:

import json, subprocess
 
def ask(prompt: str) -> str:
    out = subprocess.run(
        ["claude", "-p", prompt, "--output-format", "json", "--tools", ""],
        capture_output=True, text=True, check=True,
    )
    return json.loads(out.stdout)["result"]
 
print(ask("Reply with the single word: ready"))

Passing arguments as a list avoids shell quoting, which matters for JSON schemas on Windows.

Check it works

claude -p "Reply with the single word: ready" --output-format json | jq -r '.result'

Expected output:

ready

Without jq, drop the pipe and look for "result":"ready" in the JSON.

Troubleshooting

claude: command not found after installing. Open a new terminal. If it still fails, the install directory (~/.local/bin on macOS and Linux) isn't on your PATH; claude doctor and the install troubleshooting page show the fix.

'irm' is not recognized or The token '&&' is not a valid statement separator. You ran the PowerShell command in CMD, or the other way round. Use the command for the shell you're in.

claude -p says you're not logged in, or charges show up on an API or OpenRouter account. Run claude auth status. If authMethod is api_key, or /status inside a session shows an OpenRouter or Ollama base URL, unset ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, then run claude auth login.

A -p run stops without doing the work. A tool it needed was denied. Add it to --allowedTools, or run the task interactively once to see which permission it asks for.

Going further

• MCP servers in Claude Code
• OpenRouter or a local model? for exercises whose code calls a model API directly
• Point Claude Code at a local model