Claude Code,
explained simply.

What is Claude Code?

Think of Claude Code as a coding partner that lives inside your project. Instead of copy-pasting snippets into a chat window, you point it at a real folder of real code and talk to it in plain English. It can read your files, write and change code across many files at once, run commands in your shell, run your tests, use git, and even talk to outside tools like Jira or Slack.

The key word is agentic: you describe a goal, and it plans the steps, does the work, checks the result, and iterates — pausing to ask you before anything risky. It is not autocomplete; it is closer to handing a task to a capable junior engineer who happens to type very fast.

Where it runs

One engine, many surfaces — the same CLAUDE.md files, settings, and connected tools follow you everywhere: the Terminal CLI, a VS Code / Cursor / JetBrains extension, a standalone Desktop app, and the web (including the Claude iOS app).

Installing Claude Code

Most surfaces need a paid Claude subscription or an Anthropic Console account. Pick your environment below.

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

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

cd your-project
claude

https://claude.ai/code

Your first session

Starting is just typing claude inside a project folder. From there it's a conversation. Here's the natural rhythm of a first sitting:

# 1. Get oriented — let it map the project for you
> What does this project do? Summarize the structure.

# 2. Understand one file before you touch it
> Read src/auth.py and explain it step by step.

# 3. Ask for a change in plain language
> Add input validation to the login endpoint and write a test for it.

# 4. Let it run the test and fix what breaks
> Run the tests and fix any failures.

# 5. Ship it
> Commit with a descriptive message and open a PR.

That is the loop: you describe what you want, Claude writes and runs, you review and iterate. You don't have to know the exact files, function names, or commands up front — describing the symptom or goal is usually enough.

How it actually thinks

Three ideas explain almost everything about getting good results.

The context window

Every turn, the entire conversation so far — your prompts, Claude's replies, every file it read, every command output — gets bundled and sent to the model together. That bundle is the context window, and it has a fixed size measured in tokens (roughly ¾ of a word). When it fills up with irrelevant history, quality drops and cost rises.

Why this matters in practice

• Start fresh for new tasks. Use /clear to reset the conversation while keeping your project instructions.
• Compact long sessions. /compact summarizes history so far and frees up room; you can tell it what to keep.
• Keep scope tight. One focused task per session beats one sprawling marathon.

CLAUDE.md — its long-term memory

A markdown file at your project root that Claude reads at the start of every session. Put your coding standards, architecture decisions, preferred libraries, and review checklists here once, and Claude follows them reliably without you repeating yourself. (Full details in Section 09.)

The everyday workflow

These are the jobs Claude Code is built to absorb. Expand any card for an example.

claude "write tests for the auth module, run them, and fix any failures"

claude "commit my changes with a descriptive message"

# Scan recent logs for anomalies
tail -200 app.log | claude -p "flag any anomalies"

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

Slash commands

Slash commands are typed inside a running session to control Claude's behavior. Type / to see the live list (plugins and skills add more). Type /help for everything available in your install. Here are the ones you'll reach for most — filter to find one fast.

# Create a reusable /optimize command
mkdir -p .claude/commands
echo "Analyze this code for performance issues:" > .claude/commands/optimize.md
# now type /optimize inside any session in this repo

CLI commands

These run in your shell to start or manage sessions (as opposed to slash commands, which run inside a session). Filter the table below.

The most useful CLI flags

Flags are passed when you launch and configure the session before it starts. There are dozens; these are the ones that earn their keep. Note claude --help doesn't list every flag.

CLAUDE.md & memory

This is the single highest-leverage thing you can set up. CLAUDE.md lives at your project root and is read at the start of every session. Write your conventions once; Claude honors them every time.

# Project: Powertrain Calibration Toolkit

## Conventions
- Language: Python 3.11; type hints required.
- Style: run `ruff format` before any commit.
- Tests: pytest; every new function needs a test.

## Architecture
- src/core/ holds pure logic (no I/O).
- Never edit generated files in build/.

## Review checklist
- No hard-coded calibration constants — pull from config/.
- Flag any change touching the FOC current loop.

Practical rules

• Keep it lean. It loads into every session, so don't paste your whole wiki. State the rules; link out to details.
• Generate a starter with /init, then prune it.
• Auto memory also accumulates as Claude works — build commands, debugging insights — and carries across sessions without you writing anything.

Permissions & safety

By default, Claude asks before doing anything consequential — editing a file, running a shell command. You control how much it asks via permission modes, cycled live with Shift+Tab or set at launch with --permission-mode.

Fine-grained rules

You can allow or deny specific tool calls with pattern syntax. For example, allow read-only git but block destructive commands:

claude --allowedTools "Bash(git log *)" "Bash(git diff *)" "Read" \
       --disallowedTools "Bash(rm *)"

Connecting tools with MCP

The Model Context Protocol (MCP) is an open standard for plugging AI tools into outside data sources. With MCP servers connected, Claude Code can read design docs in Google Drive, update Jira tickets, pull from Slack, or call your own internal tooling — all from inside a session.

# Add a GitHub MCP server, scoped to your user profile
claude mcp add github -s user \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token \
  -- npx -y @modelcontextprotocol/server-github

# Confirm it registered
claude mcp list

Inside a session, /mcp shows connected servers and their tools. Because settings are shared across surfaces, an MCP server you add once is available in the CLI, IDE, and desktop app alike.

Skills, hooks & subagents

Three mechanisms turn Claude Code from a smart assistant into a customized team member.

Skills

Package a repeatable workflow your team can share and invoke like a command — /review-pr, /deploy-staging. Skills bundle instructions (and optionally scripts) so everyone runs the process the same way.

Hooks

Run your own shell commands at specific points in Claude's workflow — event-driven automation. Common uses: auto-format after every file edit, run lint before a commit, or block a tool call that violates policy.

• PreToolUse — fires before Claude uses a tool (e.g. before writing a file).
• PostToolUse — fires after, e.g. to format what was just written.
• SessionStart / setup hooks — prepare the environment before work begins.

Subagents & agent teams

For big tasks, Claude can spawn focused subagents, each with its own context window, so the main session doesn't get bloated. Agent teams coordinate several full agents on different parts of a job. For fully custom orchestration, the Agent SDK lets you build your own agents on top of Claude Code's tools, with control over permissions and tool access.

Automation & CI

Because the CLI is scriptable, Claude Code slots into pipelines and schedules.

In CI/CD

Automate code review and issue triage with GitHub Actions or GitLab CI/CD, and get automatic review on every PR with GitHub Code Review. For non-interactive runs, generate a token with claude setup-token and call claude -p with guardrails:

# Translate new strings and open a PR — capped and bounded
claude -p "translate new strings into French and raise a PR" \
  --max-turns 6 --max-budget-usd 2.00 --output-format json

On a schedule

• Routines run on Anthropic-managed infrastructure, so they fire even when your computer is off — morning PR reviews, overnight CI-failure analysis, weekly dependency audits. Create with /schedule.
• Desktop scheduled tasks run on your machine with access to local files and tools.
• /loop repeats a prompt within a session for quick polling.

Working from anywhere

A session isn't tied to one screen. You can move work between environments as your context changes.

Best practices that compound

1. Invest in CLAUDE.md early. Five minutes writing conventions saves hours of correcting the same mistakes.
2. Be specific about goals. State the what and the why; let Claude figure out the how.
3. Use plan mode for anything big. Approve the plan before code is written.
4. Manage context deliberately. /clear between unrelated tasks; /compact when a session runs long; split very large jobs across focused sessions.
5. Let it run the feedback loop. Ask it to run tests and fix failures itself rather than reporting back to you each round.
6. Review diffs, don't rubber-stamp. Speed is the point; oversight is still yours.
7. Reach for worktrees (-w) for experimental refactors so your main branch stays clean.

Common gotchas

• Bloated context = worse answers. If quality drops mid-session, you've probably filled the window with irrelevant history. /clear or /compact.
• Homebrew/WinGet don't auto-update. Stale installs miss features and fixes — upgrade manually.
• Privacy. Claude Code sends code to Anthropic's API to work. Anthropic has stated that data from Claude Pro/Max subscriptions is not used to train models; for sensitive code, confirm your plan's terms and your org's policy.
• PowerShell vs CMD confusion on Windows. If irm isn't recognized you're in CMD; if && errors you're in PowerShell. Your prompt shows PS C:\ in PowerShell.
• Flags are one-shot. Most launch flags can't change mid-session — exceptions are /model and /permissions.

Keyboard shortcuts & the prompt line

This is where casual users and power users diverge. The terminal prompt is a full editing environment, and a handful of keys save minutes every session. Filter for the move you need.

Three prefixes that change everything

What you type at the start of the line decides how Claude Code reads it:

Multiline input

\ + Enter works in every terminal, and so does Ctrl+J. Shift+Enter is native in many terminals; in VS Code, Cursor, or Zed run /terminal-setup once to install the binding.

Power moves

The patterns that separate "I use Claude for code" from "Claude Code is my development environment." Several of these come straight from Anthropic's own team.

1 · Plan before you build

The most expensive mistake is letting Claude write code before you agree on what to build. A feature with 20 decision points — each 80% likely correct — fully succeeds only about 1% of the time. Planning collapses those into a reviewed spec where each call is already made.

• Press Shift+Tab twice for plan mode (or launch with --permission-mode plan). Claude reads and proposes but edits nothing until you approve.
• Iterate with the guard phrase: "address all notes, don't implement yet." Without "don't implement yet," Claude starts coding immediately.
• Plans persist across context resets, so ending a session doesn't lose the planning work.
• Skip the plan when you could describe the exact diff in one sentence — over-planning trivial changes wastes time too.

2 · Paste the error, don't describe it

Describing a bug in words is slow — you watch Claude guess and correct. Paste the raw stack trace, CI output, or Slack thread directly and say "fix." Claude traces it through your codebase far faster than it can interrogate your paraphrase.

3 · Protect your context window

• /clear between tasks. A clean session with a sharp prompt beats a messy three-hour one; sessions degrade as old context drowns out new instructions. The five seconds to clear and re-prompt saves you 30 minutes of diminishing returns.
• Delegate exploration to subagents. Reading a big codebase fills context with file dumps — a subagent does the reading and only the findings return. One task per subagent keeps the main thread clean.
• The task list survives compaction, so Claude stays organized on long jobs. Share one across sessions with CLAUDE_CODE_TASK_LIST_ID=my-proj claude.

4 · /btw — side questions that don't pollute context

Ask a quick question without adding to the conversation. /btw sees the full session but has no tools, answers once in a dismissible overlay, and never enters history — and it even runs while Claude is working. Press f to fork the answer into a real session with full tool access.

/btw what was the name of that config file again?

It's the mirror image of a subagent: /btw knows everything but can't act; a subagent can act but starts blank.

5 · Rewind instead of starting over

Claude Code checkpoints every file edit automatically. Double-tap Esc to open the rewind menu and roll back — restore code only (keeping the conversation) for trial-and-error refactoring, or roll back both code and chat together.

6 · Run many sessions in parallel with worktrees

Launch an isolated git worktree so parallel sessions never collide on the same branch:

claude -w feature-auth

Anthropic's team runs 10–15 sessions at once this way — terminal tabs, the web, and a phone. Add .claude/worktrees/ to your .gitignore so they don't show up as untracked files.

7 · The self-improvement loop

The golden rule from Claude Code's creator: whenever Claude does something wrong, add a line to CLAUDE.md so it never repeats. Keep the file lean — about 100 focused lines beat 1,000 of filler — and check it into git so the whole team benefits. Treat it as a living document, updated weekly.

8 · Show, don't tell

Pasting a real example of existing code alongside your request noticeably improves output. Claude works better from a concrete reference than an abstract description — building a webhook handler? Show it one you already have.

9 · Vim mode & external editor

Prefer modal editing? Turn on vim mode in /config → Editor mode for full NORMAL / INSERT / VISUAL motions, text objects, and operators right in the prompt. For very long instructions, Ctrl+G drops you into your real editor instead.

10 · Images & screenshots

Paste a screenshot of a broken UI, a design mockup, or an error dialog straight into the prompt with Ctrl+V. Claude reads it as an [Image #N] you can reference — perfect for design-to-code and visual debugging.

Config, env vars & model tricks

Diagnose & configure

• /config — interactive settings: vim mode, session recap, theme, prompt suggestions, and more.
• /doctor — surfaces keybinding warnings and config problems in one place; the fastest way to find why a shortcut isn't firing.
• claude --debug "api,mcp" — see what's happening under the hood, including hook execution.
• Custom keybindings live in ~/.claude/keybindings.json — remap any shortcut, and chain multi-key chords with a space, e.g. ctrl+k ctrl+s.

Model selection

Switch mid-session with /model (or Alt+P). On Max, Team, and Enterprise plans some models offer a 1M-token window — request it explicitly with /model opus[1m] or /model sonnet[1m]. If you're worried about quality at large context sizes, start smaller and work up.

Environment variables worth knowing

Settings files & precedence

Settings load from user, project, and local scopes (control which with --setting-sources). A project-level .claude/settings.json is the place for team-shared config — for example a shared plansDirectory so everyone's plans land in the same spot after they clone the repo.

References

Claude Code ships updates frequently. When in doubt, these official sources are the source of truth.

• code.claude.com/docs — Overview
• Quickstart — your first real task, end to end.
• CLI reference — every command and flag.
• Memory & CLAUDE.md
• MCP integration
• Permission modes
• Interactive mode — shortcuts, vim, shell mode, /btw, task list.
• Checkpointing — rewind edits and restore states.
• Subagents & worktrees
• Common workflows & best practices
• Agent SDK — build custom agents.
• llms.txt — full machine-readable docs index.
• npm package