How to Use Claude Code: A Practical Tutorial From Install to Productive

How to Use Claude Code: A Practical Tutorial From Install to Productive

Most Claude Code tutorials stop at "type a prompt and watch it work." That gets you through the first ten minutes. It does not get you to the point where the tool saves you real time, because that depends on a handful of habits: giving it a project file to read, checking its plan before it edits, and knowing which commands keep a long session healthy.

I have used Claude Code daily since it launched in 2025, on side products and client work. This is the tutorial I would hand to a developer who has never opened it. Everything here is checked against the official docs on October 23, 2026, and I mark the places where behavior changes by plan or install method.

How to Use Claude Code: The Short Answer

To use Claude Code, install it with the native installer (curl -fsSL https://claude.ai/install.sh | bash on macOS, Linux and WSL), run claude in a project folder, and sign in with a paid Claude plan or Console account. Describe a task in plain English, review each proposed edit, and approve what looks right.

The rest of this post expands each step: the install options per operating system, what to type in your first session, how permissions work, and which settings are worth changing early.

What Claude Code Is (and What It Is Not)

Claude Code is Anthropic's agentic coding tool. It reads your codebase, edits files, runs commands and works with git. It started as a terminal CLI and now also runs in VS Code, JetBrains IDEs, a desktop app and the browser. All of those surfaces use the same engine, so your CLAUDE.md files, settings and MCP servers carry across them.

The terminal is where I spend most of my time, so this guide follows the terminal path. If you prefer a graphical interface, the desktop app includes Claude Code and does not need the CLI installed separately. The VS Code extension also installs into Cursor.

It is not an autocomplete tool. It does not suggest the next line as you type. You give it a task, it explores the repo, proposes changes, and you decide what lands. If you are still choosing between tools, my Claude Code vs Cursor vs GitHub Copilot comparison covers where each one wins.

How to Install Claude Code

The official docs recommend the native installer. It needs no Node.js, and it auto-updates in the background.

A few details that save you a debugging session:

• PowerShell vs CMD. The two Windows commands are not interchangeable. If you see The token '&&' is not a valid statement separator, you ran the CMD command in PowerShell. If you see 'irm' is not recognized, you ran the PowerShell command in CMD. Your prompt shows PS C:\ in PowerShell.
• Git for Windows. It is recommended on native Windows so Claude Code can use the Bash tool. Without it, Claude Code uses PowerShell as its shell tool. WSL setups do not need it.
• Homebrew has two casks. claude-code tracks the stable channel, usually about a week behind. claude-code@latest gets releases as soon as they ship. Upgrade with brew upgrade claude-code or brew upgrade claude-code@latest.
• npm needs Node.js 22 or later. The package installs the same native binary as the standalone installer. Never use sudo npm install -g, since it causes permission problems. To upgrade, run npm install -g @anthropic-ai/claude-code@latest.
• Linux package managers. apt, dnf and apk repositories exist for Debian and Ubuntu, Fedora and RHEL, and Alpine. They do not auto-update through Claude Code.
• Requirements. macOS 13.0 or later, Windows 10 1809 or later, Ubuntu 20.04 or later, Debian 10 or later, or Alpine 3.19 or later, with 4 GB of RAM or more.

The install command prints no progress while it downloads. When it finishes, open a new terminal and check it worked:

claude --version

If your shell says claude is not found, the install directory is not on your PATH yet. For a deeper check, claude doctor prints installation and settings diagnostics without starting a session.

To update by hand, run claude update. Native installs also update themselves on startup and periodically while running.

Log In and Pick a Plan

Run claude in any folder and it prompts you to sign in through your browser. Credentials are stored, so you only do this once. To switch accounts later, type /login inside a session.

You need one of these accounts:

• A Claude Pro, Max, Team or Enterprise subscription
• A Claude Console account (API access with pre-paid credits)
• Access through a supported cloud provider: Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry

The free claude.ai plan does not include Claude Code. That is the single most common reason a first login fails.

Prices I confirmed on claude.com/pricing today: Pro is $20 per month billed monthly, or $17 per month billed annually. Max starts at $100 per month. Team standard seats are $25 per seat per month billed monthly, or $20 billed annually. Enterprise is $20 per seat per month billed annually with a 20-seat minimum, plus usage at API rates. Pricing changes often, so check the page before you commit.

Subscription plans use a rolling usage window rather than a per-token bill. If you want to understand where usage goes before you hit a limit, I wrote about it in the AI agent token cost guide.

Claude Code Tutorial: Your First Session in a Real Repo

Open a terminal in a project and start Claude Code:

cd path/to/your/project
claude

The prompt shows the version, the current model and the working directory. You do not need to feed it files. It reads what it needs as it goes.

Start by asking questions

Do not start by asking it to change anything. Ask it to explain the project first. These come straight from the quickstart and they work:

what does this project do?

explain the folder structure

where is the main entry point?

This does two jobs. You learn whether it understood the codebase, and you find gaps in your own docs. If its summary is wrong, a change request would have gone wrong too.

Then make a small change

Pick something low risk, like adding a function or a test:

add a unit test for the parseDate helper, then run it

Claude Code finds the file, shows you the proposed change, and asks before applying it. Read the diff. If it looks right, approve it. If it does not, tell it what is wrong in plain language and it revises.

Be specific. The quickstart gives a good example: instead of "fix the bug," try "fix the login bug where users see a blank screen after entering wrong credentials." The more concrete the symptom and the expected result, the fewer rounds you spend.

Use git through the conversation

It works with git directly, so these prompts are fine:

what files have I changed?

commit my changes with a descriptive message

I still read the commit message before it goes in, and I only let it push when I ask for that explicitly.

Press Shift+Tab to change how much it asks

The session's permission mode sets which actions run without asking. Shift+Tab cycles through the modes mid-session. The next two sections cover the two that matter most when you are starting out: plan mode and the default manual mode.

Plan Mode: Review the Approach Before Any Edits

Plan mode is the habit I would build first. In plan mode, Claude reads files and writes a plan but does not edit your source until you approve the plan.

Three ways to enter it:

• Press Shift+Tab until the status bar shows plan mode.
• Type /plan at the prompt, optionally followed by a description, such as /plan fix the auth bug.
• Start a session in it with claude --permission-mode plan.

Press Shift+Tab again to leave without approving.

Use it when the change touches more than a couple of files, when you do not fully know the codebase, or when the first idea might be the wrong one. Reading a plan takes a minute. Unwinding a wrong 12-file edit takes much longer. For one-line fixes, skip it.

Write a CLAUDE.md So It Knows Your Project

Every session starts with a fresh context window. CLAUDE.md is how you carry instructions across sessions: build commands, test commands, conventions, things not to touch. Claude reads it at the start of every conversation.

The fastest way to create one:

/init

/init analyzes your codebase and generates a starting CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting. The docs also document an interactive variant: set the CLAUDE_CODE_NEW_INIT environment variable to 1 before running /init, and it asks which artifacts to set up (CLAUDE.md files, skills and hooks).

Where CLAUDE.md files live

Files in the directory tree above your working directory are loaded at launch. Files in subdirectories load on demand when Claude works with files there.

What to put in it

Treat it as a short onboarding note for a new teammate:

# Project notes

## Commands
- Install: bun install
- Test: bun test
- Lint: bun run lint

## Conventions
- TypeScript strict mode, no `any`
- Named exports only
- Server code lives in /lib, UI in /components

## Do not
- Edit generated files in /generated
- Commit .env files

Two rules from the docs are worth following. First, keep it under about 200 lines per file, since longer files consume more context and reduce how well instructions are followed. Second, be specific: "run bun test before finishing" beats "make sure things work."

You can also import other files with @path/to/file syntax, for example See @README for project overview and @package.json for npm commands. Imports organize a long file, but they do not reduce how much context it uses.

One more thing to know: CLAUDE.md is context, not enforcement. Claude treats it as guidance. If something must never happen, use a hook or a permission deny rule instead, which I cover in the level-up section below.

Claude Code also keeps its own notes, called auto memory, based on corrections and preferences it picks up. You can view and toggle it with /memory. If your repo already has an AGENTS.md for other tools, Claude Code can read that when there is no CLAUDE.md.

Slash Commands Worth Learning First

Type / to see everything available, and keep typing to filter. A slash command only works at the start of your message. These are the ones I use all the time, all from the official commands reference:

Two of these deserve a note. /clear is the one to reach for when you switch tasks. Old context from a finished task makes the next one worse and costs you usage. /compact is for when you want to keep going in the same task but the conversation has grown long.

/rewind is the safety net. If a round of edits went the wrong way, you can roll the conversation and the code back to an earlier point instead of untangling it by hand.

Choose and Switch Models

Claude Code uses model aliases. The ones the docs list: default, best, fable, sonnet, opus, haiku, opusplan, plus sonnet[1m] and opus[1m] for a 1M-token context window.

On the Anthropic API, opus resolves to Opus 5.5, sonnet to Sonnet 5.5 and haiku to Haiku 5.5. On Pro, Max, Team and Enterprise, the default is Opus 5.5. Fable is not the default on any plan, so you have to select it.

Two ways to switch:

/model sonnet

claude --model opus

With no argument, /model opens a picker. In the picker, Enter saves your choice as the default for new sessions, and s switches for the current session only. You can also set a model key in a settings file or the ANTHROPIC_MODEL environment variable.

opusplan is a handy one for beginners. It uses Opus while you are in plan mode, then switches to Sonnet for the edits.

My rough rule: use the strongest model for planning, debugging and cross-file changes, and a faster one for small, well-defined edits. That is my experience, not a benchmark. If you want to see how the options compare on cost, my Claude Code vs Codex comparison has the plan-level numbers side by side.

There is also an effort setting. /effort accepts low, medium, high, xhigh and max, and the available levels depend on the model. Leave it alone until you have a reason to change it.

Permissions: What Claude Code Can Do Without Asking

The default mode is called Manual in the interface and default in config. Reads run freely. Edits, shell commands and network access ask for approval. Writes to protected paths such as .git, .claude, .bashrc and .mcp.json always prompt in this mode.

Here are the six modes, from the permission modes docs:

As a beginner, stay on default and plan. Move to acceptEdits once you trust it on a task you are reviewing anyway.

You can pre-approve specific commands so you stop getting asked about the safe ones. Rules live in a settings file under permissions.allow:

{
  "permissions": {
    "allow": ["Bash(npm test)"]
  }
}

Deny rules block in every mode, including bypassPermissions. Run /permissions to see and edit your rules in an interactive dialog.

Do not reach for --dangerously-skip-permissions to get rid of prompts. If the problem is prompt fatigue, look at auto mode and a tight allow list first. I go through the flag, the access ladder and a least-privilege settings.json in my coding agent permissions guide.

Headless Mode: claude -p for Scripts and Pipes

Everything so far is interactive. Claude Code also runs non-interactively with -p (print mode). It answers once and exits, which makes it easy to use in scripts and pipes:

claude -p "explain what this function does"

cat logs.txt | claude -p "summarize the errors in this log"

git diff main --name-only | claude -p "review these changed files for security issues"

A few documented flags that matter for scripts:

• --output-format accepts text, json or stream-json.
• --max-turns limits the number of agentic turns and exits with an error when it hits the limit.
• --allowedTools lists tools that run without prompting, for example "Bash(git log *)" "Read".
• --max-budget-usd stops the run once estimated spend reaches the cap. The docs note it is a client-side estimate that can differ from your bill.
• claude -c -p "query" continues the most recent conversation non-interactively.

In print mode with no permission mode set, calls that need approval are denied unless you allow them. So give a headless run the specific tools it needs with --allowedTools, and do not rely on a prompt that nobody will answer.

Other shell commands from the CLI reference that you will use early: claude "task" starts a session with an initial prompt, claude -c continues the most recent conversation in the current directory, and claude -r opens the picker to resume an older one.

Level Up: Skills, Hooks, Subagents, MCP and More

Once the basics feel natural, these are the features that turn Claude Code from a helpful assistant into part of your workflow. I have a dedicated guide for each, so I will keep this section to what each one is for.

• Skills package a repeatable workflow into a SKILL.md file you can invoke as a slash command. Good for things you ask for the same way every time, like a release checklist. See how to write a Claude Code skill.
• Hooks run shell commands before or after Claude Code actions, such as formatting after every edit. They are also the reliable way to block an action, since CLAUDE.md is only guidance. See my Claude Code hooks guide.
• Subagents are separate Claude instances with their own context and instructions, useful for side tasks like code review or searching a large codebase without filling your main conversation. See the subagents guide.
• MCP (Model Context Protocol) connects Claude Code to outside tools and data, such as issue trackers and databases. You manage servers with claude mcp and /mcp. See the MCP developer guide.
• Status line puts useful session info, like the model and context use, at the bottom of the terminal. See the status line guide.
• Git worktrees let you run several sessions on separate branches without them stepping on each other. Claude Code supports this directly with claude --worktree (short form -w). See my git worktree guide.
• Permissions are worth a second pass once you are comfortable. See the least-privilege guide.

Add these one at a time. Each one is useful on its own, and stacking five new features in a week makes it hard to tell what helped.

Common Mistakes (and How to Avoid Them)

These are the mistakes that cost the most time and usage.

Vague prompts. "Fix the tests" gives it too much room. Name the failing test, the error and what the right behavior is.

Skipping the read-only warm-up. If you ask for a change in an unfamiliar repo, you are betting the model guessed the architecture right. Ask it to explain the relevant area first, or use plan mode.

Never clearing context. One long session across five unrelated tasks gets worse as it fills up, and it costs usage. Run /clear between tasks. Use /compact when you are mid-task and the history is long.

Approving edits without reading them. The approval prompt exists so you can catch mistakes. A diff you did not read is a diff you own anyway.

Giant tasks in one prompt. "Rebuild the whole auth system" is a project, not a prompt. Break it into steps, and ideally plan first. The quickstart recommends this too: step-by-step instructions work better for complex work.

A bloated or missing CLAUDE.md. No file means it rediscovers your test command every session. A 600-line file means it follows less of it. Aim for short and specific.

Treating CLAUDE.md as a guardrail. It is guidance. Things that must not happen belong in deny rules or hooks.

Reaching for bypass mode. If the fix for annoying prompts is switching off every safety check, you have picked the wrong fix. Use an allow list or auto mode.

Using it on the wrong plan. If you plan to use it all day, test on a lower tier first, then move up if you hit limits. Check /usage to see where you stand.

Tips That Make the Daily Loop Faster

• Describe the outcome, not the implementation, then refine.
• Ask it to run the tests and fix what fails, so the loop closes in one prompt.
• Use claude -c to pick up where you left off, and /rename to name sessions you want to find later.
• Run /diff before you commit. Seeing the full change at once catches things the individual diffs hid.
• Commit a lean project CLAUDE.md. It is one of the cheapest ways to improve a whole team's sessions.

Frequently Asked

How do I install Claude Code? Use the native installer. On macOS, Linux and WSL, run curl -fsSL https://claude.ai/install.sh | bash. On Windows PowerShell, run irm https://claude.ai/install.ps1 | iex. You can also use Homebrew (brew install --cask claude-code), WinGet (winget install Anthropic.ClaudeCode) or npm (npm install -g @anthropic-ai/claude-code, Node.js 22 or later). Verify with claude --version.

Is Claude Code free? No. The free claude.ai plan does not include it. You need a Pro, Max, Team or Enterprise subscription, a Claude Console account billed at API rates, or access through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. Pro is $20 per month billed monthly or $17 per month billed annually.

What is the difference between Claude Code and Claude in the browser? Claude in the browser chats with you about code. Claude Code runs on your machine, reads your repo, edits files and runs commands, with your approval. It also has a web version at claude.ai/code that runs tasks in the cloud.

What does /init do in Claude Code? It analyzes your codebase and generates a starting CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting the file.

How do I switch models in Claude Code? Type /model sonnet (or opus, haiku, fable) inside a session, run /model alone for a picker, or start with claude --model opus. You can also set a model key in settings or the ANTHROPIC_MODEL environment variable.

How do I run Claude Code in a script or CI? Use print mode: claude -p "your task". Add --output-format json for structured output, --max-turns to cap the loop, and --allowedTools to pre-approve the tools the job needs. Use claude setup-token to generate a long-lived token for CI.

How do I stop Claude Code from asking permission for everything? Add allow rules for the safe commands you run all the time, such as Bash(npm test), under permissions.allow in a settings file, or switch to acceptEdits mode for edit-heavy work. Try auto mode before bypassPermissions. Details are in my permissions guide.

Is Claude Code better than Cursor? It depends on the work. Claude Code is stronger on large multi-file tasks and autonomous runs, and Cursor is better for editor-first work. The full breakdown is in my Claude Code vs Cursor vs GitHub Copilot comparison.

Sources: code.claude.com/docs (overview, quickstart, advanced setup, CLI reference, commands, memory, permission modes, model configuration) and claude.com/pricing, all checked October 23, 2026.