Sign in with Google

How to Use Claude Code: A Practical Setup Guide

Install it, point it at a real repository, and build the habits that keep it useful.

intermediate10 min read
ai-toolsclaude-codeai-codingdeveloper-toolsterminal
Most first Claude Code sessions go badly the same way: install it, type "refactor the auth system," approve a wall of diffs you did not read, end up with a branch you no longer trust. Claude Code reads your actual repository and edits real files on your disk, which makes it far more capable than autocomplete and far easier to misuse. This guide covers the install, a first session in a safe order, and the four habits — durable context, small scope, read the diff, give it a way to verify — that decide whether it saves you an afternoon or costs you one.
iWhat you need
A terminal, a git repository you know reasonably well, and a Claude account on a paid plan — Pro, Max, Team, Enterprise, or Claude Console. The free claude.ai tier does not include Claude Code. You need macOS 13+, Windows 10 1809+, or Ubuntu 20.04 / Debian 10+, with 4 GB of RAM.
An autocomplete tool like GitHub Copilot predicts the next few lines at your cursor. Claude Code works one level up: it is an agent with tools. Given a request, it searches your project, reads the files it judges relevant, proposes edits, runs shell commands, and reads the output to decide what next. You never upload anything — it reads files on demand from the directory you launched it in.
That loop is the whole value and the whole risk. It can trace a bug across six files you have never opened. It can also rewrite something load-bearing because your request was ambiguous. Everything below is about keeping the first behavior and preventing the second.
The native installer is the recommended path and updates itself in the background. Run it from your normal shell; you do not need administrator rights.
macOS
$curl -fsSL https://claude.ai/install.sh | bash
That same command covers Linux and WSL. On Windows PowerShell, run irm https://claude.ai/install.ps1 | iex instead. If you prefer a package manager, brew install --cask claude-code works on macOS and winget install Anthropic.ClaudeCode on Windows — but neither auto-updates. There is also a global npm package, @anthropic-ai/claude-code, which needs Node.js 22 or later.

First run

  1. 1Confirm the install with `claude --version`. A working install prints a version number followed by (Claude Code).
  2. 2Change into a git repo you already understand, then run `claude` with no arguments. The directory you launch from is the directory it can read.
  3. 3On first launch it opens a browser to log in. If it does not open, press `c` to copy the login URL. If the browser shows a login code instead of redirecting back — normal in WSL, SSH, and containers — paste that code into the terminal prompt.
  4. 4Run `claude doctor` when something feels off. It prints read-only install and settings diagnostics without starting a session.
!Do not install it with sudo
If you use the npm route, never run sudo npm install -g. It creates permission problems that break auto-update later. If you have already hit permission errors, switch to the native installer instead of escalating.
The best first prompt is not a task, it is a question. Ask Claude Code to explain the codebase back to you, then check the answer against what you know. That tells you whether the tool has an accurate picture of the project, and shows you how it explores.
text
Give me a 5-bullet summary of what this codebase does
and where the entry point is.

Where is user session expiry handled? Just tell me the
files and functions — don't change anything yet.

Add a docstring to the function that validates signup
emails. Show me the diff.

Here's a failing test: [paste the full error output].
Investigate why it fails before proposing a fix.

Four opening prompts, in this order

If the summary is wrong, stop and find out why before you let it edit anything. Usually the cause is boring — a monorepo where you launched from the wrong directory, or real logic hidden behind generated code. Better to learn that from a summary than from a diff.
Every session starts with a fresh context window, so anything you explain in chat is gone tomorrow. A CLAUDE.md file at your project root is the fix — Claude Code loads it at the start of every session. Run /init once to generate a starting file from your codebase, then refine it with what it could not discover on its own.
markdown
# Project: billing-service

## Commands
- Install: `poetry install`
- Test: `poetry run pytest`
- Lint: `poetry run ruff check .`
- Run locally: `make dev` (needs Postgres on :5432)

## Layout
- HTTP handlers: `src/api/handlers/`
- Business logic: `src/domain/` — no DB calls here
- DB access: `src/repositories/` only

## Conventions
- 4-space indent, double quotes, 88-char lines
- Every new endpoint needs a test in `tests/api/`
- Money is stored in integer cents, never floats

## Gotchas
- `src/legacy/` is being deleted — don't fix bugs there
- Migrations are raw SQL in `migrations/`, not an ORM tool

A realistic starting CLAUDE.md — short, specific, verifiable

Notice what is in there: commands, layout, conventions that differ from tool defaults, and traps. Notice what is not: prose about the project's mission, or anything readable off the filesystem in five seconds. Add a line whenever you correct the same thing twice.
✓Keep it under 200 lines
CLAUDE.md is loaded in full into every session, so a long file both costs context and reduces how reliably instructions get followed. Run /context in a session to confirm which memory files actually loaded, and /memory to open and edit them.
Type / at the prompt to see everything available. A handful covers most work.

The short list

  1. 1/init — generate or improve the project's CLAUDE.md. Run once per repo.
  2. 2/clear — fresh conversation, empty context. Use it between unrelated tasks; stale context makes answers worse.
  3. 3/compact — summarize a long conversation to free up context without resetting.
  4. 4/context — show what is filling your context window, including which memory files loaded.
  5. 5/plan — plan mode: Claude explores and proposes but does not edit your source files.
  6. 6/diff — interactive viewer for uncommitted changes and per-turn diffs.
  7. 7/permissions — set standing approval rules for commands and tools.
  8. 8/model — switch models. Stronger for gnarly debugging, faster for mechanical edits.
Claude Code asks before it modifies a file or runs a shell command; read-only actions in your working directory do not prompt. When it proposes an edit you get the diff and three choices: approve this one, approve all edits for the session, or reject with feedback. That third option is the underused good one — rejecting with a reason usually produces a correct second attempt. Shift+Tab cycles permission modes, and each gives up something.

The modes

  1. 1Default — prompts for every edit and every shell command that is not a known read-only one.
  2. 2Plan — explores and reasons but will not touch source files. The right mode for anything unscoped.
  3. 3acceptEdits — auto-approves file edits and routine filesystem commands in your working directory. Fine for a tightly scoped task.
  4. 4auto — auto-approves tool calls with background safety checks that the action matches what you asked for.
  5. 5bypassPermissions — skips prompts almost entirely. Only inside a container or VM.
✗Auto-approving is not the same as reading
Approving all edits for a session is a reasonable convenience. Skipping the review afterward is not. Run /diff — or plain git diff — before committing anything an agent wrote. If you cannot explain a hunk, you are not done reviewing.
Claude Code does worst on requests that are sweeping and unverifiable. "Clean up the codebase" has no definition of done, so it invents one. The fix is not a longer prompt — it is a smaller task plus a way for the agent to tell whether it succeeded.
text
WEAK
Refactor the payments module to be cleaner and add tests.

STRONG
In src/domain/payments.py, extract the currency conversion
logic out of charge() into its own function. Behavior must
not change. Then run `poetry run pytest tests/payments/`
and keep iterating until it passes. Show me the diff before
you touch anything else.

The same intent, scoped two ways

The strong version names one file, states the invariant, and hands over a command that produces a pass or fail. That last part matters most: an agent with a test command can catch its own mistakes, and an agent without one is guessing. If a task has no verification path — a design decision, an ambiguous product question — decide it yourself and hand over the mechanical part.
✓One task, one conversation
Finish a task, review the diff, commit, then /clear. Conversations that wander across three unrelated problems degrade noticeably.
There is an official VS Code extension and a JetBrains plugin, plus a desktop app if you would rather not live in a terminal. The practical gain is diff review: changes land in your editor's native diff view instead of scrolling past in the terminal. If your editor is not set up yet, How to Set Up VS Code covers the base install.

Symptom, cause, fix

  1. 1`claude: command not found` right after installing. The install directory is not on your PATH yet. Open a new terminal window — most shells read PATH only at startup.
  2. 2It says you need a subscription. You are on the free claude.ai tier, which excludes Claude Code. Upgrade, or authenticate against a Claude Console account.
  3. 3It authenticated as the wrong account. ANTHROPIC_API_KEY is set in your environment, and an approved API key outranks your subscription login. Run `unset ANTHROPIC_API_KEY`, then check `/status`.
  4. 4It ignores a rule in your CLAUDE.md. Run `/context` and confirm the file loaded. If it did, the rule is too vague — "use 2-space indentation" gets followed, "format code properly" does not.
  5. 5It keeps editing files you did not mean to touch. Your request was broader than you thought. Switch to `/plan`, get an explicit plan, then approve one step at a time.
  6. 6Answers got worse partway through a long session. The context window is full of a previous task. Run `/compact`, or `/clear` and restate the problem cleanly.
  7. 7It broke something and tests still pass. Your tests do not cover that path — information about your test suite, not just the agent.
Most problems people blame on the agent are prompting problems, so How to Write Better AI Prompts is the highest-leverage thing to read next. If you would rather work in an editor than a terminal, How to Use Cursor, the AI Code Editor covers the same agentic loop with graphical diff review. Since an agent will be creating commits for you, How to Use Git is worth being solid on rather than approximately comfortable with. For the broader skill of working alongside these tools, the Leveraging AI roadmap sequences prompting, verification, and agentic workflows in the order they build on each other.