How to Use Claude Code: A Practical Tutorial for 2026

To use Claude Code, install it with one command, run claude inside a project folder, sign in with a Claude plan or a Console API key, and ask for what you want in plain English. Claude reads your code, edits files, runs commands and tests, and keeps going until the task is done or it needs you. This tutorial covers how to use Claude Code from install to daily work: the first session in a real repo, permission modes and plan mode, CLAUDE.md and other context, everyday workflows like bug fixes, tests and pull requests, headless runs in CI, and the Claude Code best practices Anthropic now recommends. Everything here was checked against the Claude Code docs in November 2026, and a lot changed this year: new sessions now start in auto mode, /cost is an alias for /usage, and "think hard" is no longer a magic phrase.

What Claude Code is and how the agent loop works

Claude Code is an agentic coding tool. Unlike an autocomplete plugin that sees one file, it works on your whole project through tools: it reads and searches files, edits code, runs shell commands, uses git, and fetches web pages. Anthropic's How Claude Code works page describes the loop in three phases: gather context, take action, verify results. Ask it to "fix the failing tests" and it will run the suite, read the errors, find the source files, edit them, and run the tests again, repeating until they pass.

You can interrupt at any point to add context or redirect. Each session can reach your project files, your terminal, your git state, your CLAUDE.md files and any extensions you configure. Sessions are saved locally under ~/.claude/projects/, which is what makes resuming and rewinding possible.

How to install Claude Code and sign in

The quickstart recommends the native installer, which 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

Other options from the setup page:

Method	Command	Auto-updates?
Native installer (recommended)	The curl or irm command above	Yes
Homebrew (stable channel)	brew install --cask claude-code	No, run brew upgrade claude-code
Homebrew (latest channel)	brew install --cask claude-code@latest	No
WinGet	winget install Anthropic.ClaudeCode	No, run winget upgrade Anthropic.ClaudeCode
npm	npm install -g @anthropic-ai/claude-code	Yes, needs Node.js 22+; never use sudo
apt, dnf, apk	See the setup docs	No, upgrade with your package manager

Open a new terminal and confirm with claude --version. If the shell says claude isn't found, the install directory isn't on your PATH yet; the install troubleshooting page has the fix. On native Windows, install Git for Windows so Claude can use its Bash tool; without it, Claude Code falls back to PowerShell.

Subscription or API key?

Run claude in any folder and it asks you to log in. You can use:

• A Claude plan (Pro, Max, Ultra, Team or Enterprise). Usage is included in the subscription, with plan limits. This is what the docs recommend.
• A Claude Console account. You pay per token from prepaid API credits. On first login a "Claude Code" workspace is created in the Console for cost tracking.
• Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, for enterprises that buy through a cloud provider.

For current plan prices and how far each tier goes, see Claude Code pricing. For per-token API rates, see Anthropic API pricing.

Use /login to switch accounts and /logout to sign out.

Claude Code tutorial: your first session in a real repo

Start in a project you know well, so you can judge the answers:

cd ~/code/my-app
claude

1. Ask questions before you change anything. Claude reads files as it needs them, so you don't have to paste code in:

what does this project do?
where is the main entry point?
explain the folder structure
how are API requests authenticated?

2. Generate a CLAUDE.md. Type /init. Claude analyzes the codebase and writes a starting file with build and test commands and the conventions it found. If one already exists, it suggests improvements instead of overwriting.

3. Make one small, specific change.

add input validation to the signup form: email must be valid, password at least 12 characters. show errors under each field. run the form tests after.

Claude finds the files, shows the diff, and runs the tests.

4. Use git through the conversation.

what files have I changed?
commit my changes with a descriptive message

5. Pick the session back up later. claude -c continues the most recent conversation in the current directory, and claude -r opens a picker of earlier ones. Name a long-running session with /rename oauth-migration and come back with claude --resume oauth-migration.

Type / to see available commands and skills. The full list, with examples, is in our Claude Code commands guide.

Permission modes and plan mode: how much Claude can do without asking

A permission mode sets which actions run without your approval. This is the part most tutorials now get wrong: with Claude Code v2.1.283 or later, interactive terminal and VS Code sessions start in auto mode, not in an approve-everything mode. In auto mode, a separate classifier model reviews actions before they run and blocks the ones you'd want a person to stop: curl | bash, production deploys and migrations, force pushes, sensitive data sent to outside endpoints, and actions that look driven by content Claude read rather than by you.

Mode	What runs without asking	Best for
auto	Everything, with classifier safety checks	Default for interactive sessions; long tasks
default (Manual)	Reads only	Sensitive work, unfamiliar code
acceptEdits	Reads, file edits, common filesystem commands (mkdir, mv, cp)	Iterating on code you review as you go
plan	Reads, plus classifier-approved commands when auto mode is available	Exploring and designing before any edit
dontAsk	Reads and pre-approved tools; everything else is denied	Locked-down CI and scripts
bypassPermissions	Everything	Disposable containers and VMs only

Press Shift+Tab to cycle modes during a session; the status bar shows the active one, such as ⏸ plan mode on. To start in a specific mode, pass it as a flag:

claude --permission-mode manual   # "manual" is an alias for "default"
claude --permission-mode plan

If auto mode blocks something three times in a row (or twenty times in total), it pauses and goes back to asking you. Blocked actions show under Recently blocked in /permissions, where you can approve a retry.

Plan mode

Plan mode tells Claude to research and propose changes without editing your source. Enter it with Shift+Tab, or prefix one prompt with /plan:

/plan migrate session storage from cookies to Redis. list every file that changes and how you'll test it.

When the plan is ready you choose Yes, and use auto mode, Yes, manually approve edits, or No, keep planning. Press Ctrl+G to open the plan in your editor and change it before Claude starts. Plan mode pays off when a change touches many files, when you don't know the code, or when you want to agree on an approach before any tokens go into implementation.

Permission rules

Modes set the baseline; rules in settings.json refine it. Deny rules hold in every mode, including auto and bypassPermissions. This is the example from Anthropic's best-practices page, saved as .claude/settings.json (shared with your team through git):

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

Personal rules go in ~/.claude/settings.json (all projects) or .claude/settings.local.json (this project, not committed). For an OS-level limit on files and network, turn on /sandbox.

How to give Claude Code context: CLAUDE.md, @-mentions and images

Claude reads your repo well. What it can't see is what was never written down: a deploy process in someone's head, the env var integration tests need, a team decision.

CLAUDE.md

CLAUDE.md is a markdown file Claude loads at the start of every session. Where you put it decides who it applies to (memory docs):

File	Scope	Shared?
~/.claude/CLAUDE.md	You, in every project	No
./CLAUDE.md or ./.claude/CLAUDE.md	This project	Yes, commit it
./CLAUDE.local.md	You, in this project	No, add it to .gitignore
Managed policy file (e.g. /etc/claude-code/CLAUDE.md on Linux)	Everyone in the organization	Set by IT
.claude/rules/*.md with a paths: filter	Only when Claude works on matching files	Yes

If your repo already has an AGENTS.md for other coding agents and no CLAUDE.md, Claude Code reads the AGENTS.md. A CLAUDE.md can pull in other files with @path imports, such as See @README for an overview.

Keep it short. The docs recommend under 200 lines, and Anthropic's own example is tiny:

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

The test for each line: could Claude find this by reading the code, and would it actually look? If both answers are yes, leave it out. Don't describe your folder layout; Claude reads it. Run /context all to confirm the file loaded, and /doctor prompt-audit to flag stale or contradictory instructions. For more real files to copy, see our CLAUDE.md examples.

Claude also keeps auto memory, notes it writes about your preferences and corrections. Manage both with /memory.

@-mentions, images and piped input

• Files: type @ and a path, as in explain the logic in @src/utils/auth.js. The file's contents go straight into the message. @src/components gives a directory listing.
• Images: drag a screenshot into the window, paste with Ctrl+V (Alt+V on Windows and WSL), or give a path. Mockups, error screenshots and diagrams all work.
• Command output: pipe it in from your shell: cat error.log | claude -p "what's going on here".

Everyday workflows: explore, plan, code, commit

The rhythm for most tasks: explore, plan anything non-trivial, implement against a check Claude can run, then commit. Prompts below come from the common workflows guide.

Fix a bug

Give the symptom, where to look, and what "fixed" means. Compare the vague and specific versions Anthropic uses:

Instead of	Try
"fix the login bug"	"users report login fails after the session times out. look at token refresh in src/auth/, write a failing test that reproduces it, then fix it"
"add a calendar widget"	"follow the pattern in HotDogWidget.php and build a calendar widget that lets you pick a month and page between years. no new libraries"

Include the command that reproduces the error. For a bug in code you didn't write, try /effort high.

Write tests

find functions in NotificationsService.swift that are not covered by tests
add tests for the notification service
add test cases for edge conditions in the notification service
run the new tests and fix any failures

Claude matches your existing test framework and style. A failing test is also the best "definition of done" for any change.

Open a pull request

With the GitHub CLI (gh) installed and signed in, just ask: create a pr for my changes. Then refine: enhance the PR description with more context about the security improvements. Claude Code links the session to the PR, so claude --from-pr 1234 finds it again later. Before you merge, run /code-review for a review from a fresh subagent that never saw how the code was written, or /security-review to check the branch diff for vulnerabilities.

Steer and undo

• Esc stops Claude mid-action and keeps the work so far.
• Esc twice on an empty prompt, or /rewind, opens the rewind menu to roll back code, conversation, or both to an earlier prompt.
• /clear starts over. After two failed corrections, clear and write one better prompt that includes what you learned.
• /btw asks a side question without adding it to the conversation.

To run several tasks at once without edits colliding, start each in its own git worktree with claude -w feature-auth.

Run Claude Code headless with claude -p and in CI

claude -p "prompt" (print mode) runs once and exits. That's how Claude Code goes into scripts, git hooks and CI (headless docs). Since v2.1.302, a -p run with no permission mode set starts in Manual mode, so any action that needs approval is denied unless you allow it. Pre-approve exactly what the job needs:

# Review staged changes and commit, with only git allowed
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

# Parse the result in a script
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Pipe in data
cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

The space in Bash(git diff *) matters: it is prefix matching, and Bash(git diff*) would also match git diff-index.

Flags worth knowing for unattended runs, all confirmed in the CLI reference:

Flag	What it does
--allowedTools "Read,Edit,Bash(npm test)"	Pre-approves listed tools
--permission-mode dontAsk	Denies anything not pre-approved, never prompts
--permission-mode auto	Lets the classifier review actions instead
--max-turns 20	Caps agentic turns
--max-budget-usd 5.00	Stops once estimated spend hits the cap
--output-format json / stream-json	One result object, or streamed events (with --verbose)
--json-schema '<schema>'	Returns validated data in structured_output
--bare	Skips hooks, skills, plugins, MCP and CLAUDE.md for reproducible runs

Anthropic's best-practices page shows this loop for a mechanical migration. Try it on three files first, fix the prompt, then run the rest:

for file in $(cat files.txt); do
  claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
    --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 20
done

GitHub Actions

The fastest setup is /install-github-app inside Claude Code: it installs the Claude GitHub App, saves your key as a repository secret, and opens a PR with the workflow. Or add this to .github/workflows/claude.yml yourself (GitHub Actions docs):

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Now @claude fix the TypeError in the user dashboard component in an issue or PR comment starts a run. To bill a Claude subscription instead of the API, generate a token with claude setup-token and replace the key line with claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}. Add a prompt: input to run on a schedule or any other event. GitLab has its own CI/CD integration.

Where Claude Code runs: terminal, IDE, desktop and web

Every surface runs the same engine, so your CLAUDE.md, settings and MCP servers carry over (overview).

Surface	How to get it	Good for
Terminal CLI	The installer above	Full feature set, scripting, any editor
VS Code	The Claude Code extension	Inline diffs, @-mentions, plan review in the editor
JetBrains IDEs	Claude Code plugin from the JetBrains Marketplace (needs the CLI)	IntelliJ, PyCharm, WebStorm users
Desktop app	Download for macOS or Windows, open the Code tab	Visual diffs, several sessions side by side; paid plan required
Web	claude.ai/code, also in the iOS and Android apps	Long tasks in the cloud, repos you don't have locally
Slack, GitHub Actions, GitLab	Integrations	Turning bug reports and comments into PRs

/desktop hands a terminal session to the desktop app, and claude --teleport pulls a cloud session into your terminal. Still choosing a tool? See our AI coding agents comparison.

Extend it: MCP servers, skills, hooks and subagents

These four features fit Claude Code to your stack.

Feature	What it is	Where it lives	Use it for
MCP servers	Connectors to outside systems	.mcp.json (project), ~/.claude.json (local and user)	Jira, Notion, databases, Sentry
Skills	Reusable procedures Claude loads when relevant	.claude/skills/<name>/SKILL.md	Release steps, runbooks, team know-how
Hooks	Your scripts at fixed points in the loop	hooks in settings.json	Rules that must always (or never) happen
Subagents	Separate Claude instances with their own context and tools	.claude/agents/<name>.md	Parallel work, independent review

MCP. Add a remote server from your shell, then manage it with /mcp in a session:

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --scope project --transport http <name> <url>   # shared via .mcp.json

If a system has a good CLI (gh, aws), Claude can use that with less context. Browse servers in the MCP server directory, or by app, for example MCP servers for GitHub.

Skills hold procedures Claude can't infer, like your release steps. Claude sees only each skill's name and description until it needs one. Add disable-model-invocation: true so a risky skill runs only when you type its name, like /release. Find ready-made skills in the agent skills directory.

Hooks turn a guideline into a guarantee. This .claude/settings.json hook from Anthropic's docs runs Prettier after every edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\"" }
        ]
      }
    ]
  }
}

Subagents run side tasks in their own context. A custom reviewer with tools: Read, Grep, Glob can read but never edit.

Go deeper in the sibling guides: Claude Code hooks, Claude Code subagents, CLAUDE.md examples and the Claude Code commands reference. Plugins bundle all four, and /plugin installs them.

Claude Code best practices from Anthropic's own guide

Anthropic rewrote its best practices page for current models. Defaults now handle most work; setup pays off for what Claude can't see or must never get wrong. These Claude Code best practices matter most.

1. Tell Claude what it can't see. Name the file, describe the symptom, say what "fixed" looks like. Hand over what you have: @ a file, paste a screenshot, pipe a log. When you don't know what you want yet, ask Claude to interview you: Interview me until you could write the spec, then write it to SPEC.md. Then build from SPEC.md in a fresh session.

2. Give Claude a check to run. Claude stops when work looks done. A test, a typecheck, a build exit code, or a screenshot to compare turns "looks done" into "is done". Put the command in CLAUDE.md, and ask for evidence: the command it ran and the output. To have Claude Code enforce the check, use a Stop hook. Exit code 2 sends Claude back to work with the error output:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

3. Enforce rules that can't have exceptions. CLAUDE.md is guidance; Claude may decide a line doesn't apply. "Never read .env" belongs in a deny rule, "always format" in a hook. If you keep adding IMPORTANT to a line and Claude still misses it, that line belongs in a hook.

4. Use effort, not magic words. "think hard" and "be thorough" are ordinary prompt text now. The real control is /effort (low, medium, high, xhigh, max). The default is medium on Opus 5.5. Put ultrathink in a single prompt for one deep turn. One phrase that still helps is "be ambitious", when you want edge cases and follow-on work included.

5. Get an independent review. /code-review, a read-only reviewer subagent, or a second session reviewing @src/file.ts catches what the writer's own reasoning hides. Ask it to skip style, or you'll get busywork.

How to manage cost and context in Claude Code

Every request sends the whole conversation, so a session that piled up three unrelated tasks pays for all three on every turn of the fourth. The prompt cache discounts repeated context: it lasts about an hour on a subscription and five minutes on an API key.

• /usage shows session cost, plan limits and activity. /cost and /stats are aliases. On a paid plan it breaks usage down by skill, subagent, plugin and MCP server. The dollar figure is a local estimate at list price; subscribers are billed by plan, not by that number.
• /clear between unrelated tasks. It's free, and /clear oauth-migration labels the old session so you can /resume it.
• /compact summarizes the conversation to free space. Give it a focus: /compact keep the API changes and the test commands. Auto-compaction already runs as the window fills.
• /model switches models. The default Opus 5.5 handles most coding; Sonnet costs less on routine work, and Haiku suits simple subagent jobs (model: haiku in the subagent file).
• Turn off MCP servers you aren't using in /mcp, since connected servers add their tool names and instructions to context.

To estimate how many tokens a file or prompt will use, try the token counter.

FAQ

Is Claude Code free to use?

No. You need a paid Claude plan (Pro, Max, Ultra, Team or Enterprise), a Claude Console account with prepaid API credits, or access through Bedrock, Google Cloud or Microsoft Foundry. See Claude Code pricing for current plan prices.

How do I start Claude Code in a project?

Open a terminal, cd into the project folder, and run claude. Claude Code works on the directory you start it in and its subfolders. Run /init first to create a CLAUDE.md for the project.

Can I use Claude Code in VS Code?

Yes. Install the Claude Code extension for inline diffs, @-mentions and plan review inside the editor. JetBrains IDEs have a plugin too, and it uses the CLI you install separately.

Is Claude Code safe to let run commands?

Interactive sessions start in auto mode, where a classifier blocks risky actions like production deploys, force pushes and piping scripts from the internet into a shell. For hard guarantees, add deny rules in .claude/settings.json, turn on /sandbox, and keep bypassPermissions for disposable containers.

How do I make Claude Code remember my project rules?

Put them in CLAUDE.md at the project root and commit it. Keep it under 200 lines and limit it to what Claude can't learn from the code: exact test commands, gotchas, team decisions. Personal preferences go in ~/.claude/CLAUDE.md or a gitignored CLAUDE.local.md.

How do I reduce Claude Code token usage?

Run /clear between unrelated tasks, /compact long sessions with a focus, turn off unused MCP servers, and use Sonnet or a lower /effort for routine work. Check /usage to see where tokens went.