Claude Code: The Complete Guide (Setup, Commands, Workflows, and What Actually Breaks)

What Claude Code Actually Is

Claude Code is a command-line tool. You install it, type claude in your terminal, and you're talking to an AI agent that can read your files, edit them, run shell commands, and use git — all inside your actual project, not a sandbox.

That's the part people get wrong first. It's not a chatbot you copy-paste code into. It's not an autocomplete plugin like GitHub Copilot that finishes your current line. It has IDE integrations (VS Code, JetBrains), but the IDE plugin is a window into the same agent — not the product itself. The product is the agent.

The mental model that actually works: think of it like a junior engineer who has terminal access to your machine, can read your whole codebase, and will do exactly what you ask — including things you didn't mean to ask for. You give it a task in plain English. It goes and looks at your files to understand context. It writes or edits code. It runs your tests. It checks the output. If something fails, it tries again. Then it can commit the changes with git, using a message it writes itself.

This is different from autocomplete in a concrete way: autocomplete predicts the next few tokens based on what you're typing right now. Claude Code takes a goal — "add rate limiting to the login endpoint" — and works through multiple steps to get there, checking its own work along the way. You're not writing code faster. You're delegating a chunk of work and reviewing the result.

That power cuts both ways, and I'll get into where it breaks later in this guide — things like running the wrong command, editing more files than you expected, or confidently doing the wrong thing fast. None of that is a reason to avoid it. It's a reason to set it up correctly and understand what it can and can't be trusted to do unsupervised.

The rest of this guide covers install, first session, the commands and workflows that make it useful day-to-day, and — just as important — what actually goes wrong in practice and how to avoid it.

Installing Claude Code on macOS, Linux, and Windows

Claude Code runs on Node.js, so the install is the same core command everywhere: npm install -g @anthropic-ai/claude-code. The differences are mostly in how you get npm set up correctly and how you avoid permission errors.

macOS

1. Install Node.js 18 or later. The easiest way is brew install node if you have Homebrew. Check your version with node -v.
2. Run npm install -g @anthropic-ai/claude-code.
3. Run claude from any project folder to launch it.

The most common macOS error is a permissions failure on the global npm directory — something like EACCES: permission denied. This happens because npm's default global install location often requires root. Don't fix it with sudo npm install -g; that creates permission headaches later. Instead, either use a Node version manager like nvm (which installs Node in your home directory, no sudo needed) or reconfigure npm's global prefix to a folder you own. nvm is the simpler fix if you're starting fresh.

Linux

Same command, same Node requirement. Most distros ship an old Node version in their default package manager, so don't install Node via apt install nodejs unless you've added the NodeSource repository for a current version — otherwise you'll hit version errors when Claude Code checks for Node 18+. Using nvm here avoids the whole problem and is what I'd recommend regardless of distro.

Windows: three paths, and why one is clearly better

Windows is where install guides get messy, because there are three legitimate ways to run Claude Code, and they behave differently.

• WSL (Windows Subsystem for Linux): Install WSL, install Node inside your Linux distro (Ubuntu is the default), then run the same npm install command as Linux. This is the smoothest path, and it's what most guides — including this one — recommend. Claude Code was built with Unix-style tooling in mind (bash, standard file paths, git), and WSL gives you that environment natively. File edits, shell commands, and git operations all behave the way the tool expects.
• PowerShell + Git for Windows: You can run Claude Code directly on native Windows if you install Node for Windows and Git for Windows (which provides a bash-compatible shell). This works, but you'll hit more friction: path formatting differences (backslashes vs forward slashes), occasional issues with how shell commands get interpreted, and some tools behaving slightly differently than their Linux equivalents.
• Winget: You can use winget install OpenJS.NodeJS to get Node quickly, then run the same npm command. This is really just a faster way to get Node onto native Windows — it doesn't change the underlying trade-off versus WSL.

If you're on Windows and don't already have a reason to avoid WSL, use it. It's a 10-minute setup (wsl --install from an admin PowerShell prompt, then restart), and it removes an entire category of path- and shell-related bugs before they happen.

Common install errors, quickly

• "command not found: claude" after install — usually a PATH issue. npm's global bin folder isn't in your shell's PATH. Run npm config get prefix to find where global packages install, then add that folder's bin subdirectory to your PATH.
• Node version too old — Claude Code needs Node 18+. Check with node -v before you install, not after you hit an error.
• Permission denied on install — covered above. Use nvm, don't use sudo.

Logging In and Your First Session

After install, run claude in your terminal and it'll walk you through authentication. You've got two options:

• Claude Pro or Max subscription: log in with your Anthropic account. This is the simpler route if you're already a subscriber, and usage is bundled into your existing plan.
• API key: generate one from the Anthropic Console and paste it in when prompted. This is billed separately, per token, and is the better option if you want usage-based pricing or you're setting this up for a team with its own billing.

Neither is objectively "correct" — it depends on whether you want flat-rate access bundled with a subscription you already pay for, or metered usage you can track precisely. If you're just trying Claude Code out for the first time, the subscription route has less setup friction.

Once you're logged in, cd into an existing project and run claude again. This starts an interactive session scoped to that folder. A good first move, before you ask it to change anything, is to have it explain what it's looking at. Try:

Explain the structure of this codebase. What are the main directories, what does each one do, and where would I look if I wanted to add a new API endpoint?

Here's what actually happens: Claude Code doesn't have your codebase memorized. It reads it, live, using its own file-browsing tools — listing directories, opening key files like package.json or README.md, checking your routing or config files. You'll see it narrate this as it goes: which files it's opening and why. Then it gives you a summary in plain English — something like "this is an Express app, routes live in src/routes, each file maps to one resource, middleware is in src/middleware, and new endpoints typically get registered in src/routes/index.js." This first exercise is worth doing even on a codebase you already know well. It tells you two things fast: whether Claude Code's read of your project matches reality, and how it likes to explore an unfamiliar structure — which is exactly the skill it'll use later when you ask it to actually change something.

How Claude Code Reads and Edits Your Codebase

Claude Code doesn't load your entire repo into memory before it starts working. It can't — even a medium-sized codebase has more text in it than fits in a single context window, and a large one has orders of magnitude more. Instead, it explores the way a new engineer would: open a few files, form a guess, open a few more files to check the guess, keep going until it's confident enough to act.

This matters because it explains both the tool's strengths and its most common failure mode. The strength: it doesn't need you to hand-feed it files. You can ask it to add a feature and it'll go find the relevant code itself, the same way it explored your structure in the first exercise above. The failure mode: if your codebase is large, inconsistently organized, or the relevant code is spread across a dozen files with no obvious naming pattern, Claude Code can burn a lot of its context window just searching — and it can settle on an incomplete picture without realizing it's incomplete. You'll see this as edits that technically work but miss a related file it never opened, like a type definition or a second place a function is called.

The fix isn't a bigger context window. It's giving the model a map before it starts wandering.

CLAUDE.md: persistent memory for your project

A CLAUDE.md file, sitting in your project root, gets read automatically at the start of every session in that folder. Think of it as the onboarding doc you'd give a new hire — except this one gets read every single time, so it's worth being specific rather than general.

A weak CLAUDE.md says something like "this is a React app, please write clean code." That tells the model nothing it couldn't guess from package.json. A useful one names the decisions that aren't visible from the code alone:

# Project conventions

- State management: Zustand, not Redux. Don't suggest Redux.
- API calls go through src/lib/api-client.ts — never call fetch() directly in components.
- Tests use Vitest. Test files live next to the code they test, as *.test.ts.
- We use named exports only. No default exports, anywhere.
- Run `npm run typecheck` after any change to src/types/.
- Do not modify files in src/generated/ — they're auto-generated from the schema.

Every line in that example is something Claude Code could eventually figure out by reading enough files — but "eventually" costs context and time, and sometimes it guesses wrong before it gets there. A good CLAUDE.md front-loads the conventions that aren't obvious from any single file, especially the negative ones: what not to do, what looks reasonable but is actually wrong for this codebase.

Keep it short. A 500-line CLAUDE.md defeats the purpose — it's competing for the same context budget as the code itself. Aim for the handful of rules that would actually save you a correction if you didn't write them down. You can generate a starting draft automatically; more on that in the /init command below.

Essential Commands and Keyboard Shortcuts

Claude Code has more shortcuts than you need to memorize. Most guides list all of them, which mostly teaches you to skim past the ones that matter. Here's the small set you'll actually reach for daily.

Action	Shortcut / Command	Why you'll use it
Interrupt a running response	Esc	Claude's heading down the wrong path — stop it before it finishes editing files you didn't want touched.
Undo the last edit	Type undo or use /rewind	It made a change that broke something. Roll back without leaving the session or touching git yourself.
Multi-line input	Shift+Enter	Paste in a stack trace or write a multi-paragraph instruction without submitting each line.
Switch models mid-session	/model	Drop to a faster/cheaper model for a simple rename, or up to a stronger one for a hard refactor — no need to restart.
Resume a previous session	claude --continue or claude --resume	Pick up exactly where you left off, with prior context intact, instead of re-explaining the task.
Show current session cost/usage	/cost	If you're on API billing, this tells you what a session is actually costing before you're surprised by a bill.

A couple of these deserve a second's more explanation. Esc is the one you'll use the most — not because Claude Code is often wrong, but because it's often fast, and it's cheaper to stop and redirect after two sentences of a bad plan than to wait for a full response and then undo. Get in the habit of watching the first line or two of what it's about to do, not just the final result.

claude --resume matters more than it looks like on paper. Long sessions build up real context — decisions you made, things you told it not to do. Restarting from scratch throws all of that away. If you're stepping away for lunch or picking a task back up tomorrow, resume instead of starting fresh.

Everything else — customizing key bindings, the full flag list for claude at startup, verbose logging modes — is in the official docs and worth a look once, not worth memorizing now.

Slash Commands Worth Knowing

Slash commands are shortcuts you type inside a session, and a few of them solve problems you'll hit in your first week.

/clear wipes the conversation entirely and starts over with zero context. Use this when you're switching to a completely unrelated task — you just finished debugging the auth flow and now you want to write a new component, and you don't want the model still half-thinking about auth.

/compact summarizes the conversation so far into a shorter form and keeps working from that summary, instead of throwing it away. Use this when you're still on the same task but the conversation has gotten long — you've been going back and forth for 45 minutes on the same feature, and you're worried about hitting the context limit before you're done. /compact keeps the important decisions ("we chose Zustand, we're not touching the generated files") and drops the noise (every intermediate file read).

The confusion between the two comes down to one question: do I still need this context, or don't I? If you're starting something new, clear it. If you're still deep in the same problem and just running low on room, compact it. Using /clear when you meant /compact is the more expensive mistake — you'll find yourself re-explaining decisions you already made.

A few others worth having in your pocket:

• /init — scans your project and generates a starting CLAUDE.md for you. It's not going to know your unwritten conventions, but it's a faster starting point than a blank file, and it's the easiest way to get one in place on day one.
• /review — asks Claude Code to review code (often a git diff) with a critical eye, rather than just implementing something. Genuinely useful before you open a pull request — it catches a different class of issue than it catches while writing the code in the first place, because "does this work" and "is this a good idea" are different questions.
• /permissions — lets you view and adjust what Claude Code is allowed to do without asking first (running commands, editing files outside the project, etc.). Worth checking once so you know what you've granted, especially if you loosened defaults earlier to move faster.
• Custom slash commands — you can define your own by adding a markdown file to a .claude/commands/ folder in your project. If you find yourself typing the same multi-paragraph instruction every week — "run the linter, fix anything it flags, then run the tests" — save it as a command and call it with one word instead.

None of these are exotic. They're the difference between using Claude Code as a chat window that happens to edit files, and using it as a tool that fits into how you actually work.

Making Code Changes Safely

Claude Code doesn't edit your files invisibly. When it wants to make a change, it proposes a diff — the same red-and-green, line-by-line view you'd see in a code review — and by default it stops and asks before applying it. You see exactly what's about to change before it changes.

There are three permission modes worth knowing:

• Ask (default) — Claude proposes each edit and waits for you to approve it. Slowest, safest. Good for anything you don't fully trust yet, or any file that would be painful to get wrong.
• Auto-accept edits — Claude applies file edits without stopping to ask, but still asks before running commands (installing packages, deleting files, hitting the network). This is the mode most people land on day-to-day, because approving every single line change gets tedious fast, but you still want a checkpoint before anything leaves your filesystem.
• Plan mode — Claude reads your code and writes out what it intends to do, in plain language, before touching anything. No edits happen until you approve the plan. This is worth turning on for anything bigger than a one-file fix, because it's much cheaper to fix a bad plan than a bad diff across six files.

Here's what the flow looks like in practice. Say you ask: "Add a rate limiter to the /api/upload endpoint — max 10 requests per minute per user." In ask mode, Claude Code reads the relevant files, then shows you a diff: a new middleware file, an import added to the route, maybe a config value. You read it the way you'd read a coworker's pull request — not line-by-line syntax-checking, but asking "does this do what I asked, and does it touch anything I didn't expect?" If it added a dependency you didn't want, or touched a file unrelated to uploads, that's your moment to say no and redirect.

The honest trade-off: auto-accept mode is genuinely faster, and most of the time the edits are fine. But "most of the time" is doing real work in that sentence. I've had auto-accept apply a change that quietly broke an unrelated test because it touched a shared utility function. Nothing catastrophic — the test suite caught it — but it's a reminder that "fine most of the time" isn't the same as "safe to stop reading." Skim every diff. It takes ten seconds and it's the cheapest insurance you have.

Using Git Through Claude Code

Claude Code can stage changes, write commit messages, create branches, and open pull requests — all from inside the same session where it wrote the code. You don't have to switch to a terminal or GitHub's UI to close the loop.

Here's what turning a GitHub issue into a PR actually looks like, end to end.

Say you've got an issue: "Users can submit the signup form with an empty email field." You paste the issue text into Claude Code and say:

Fix this issue. Create a new branch, make the fix, write tests for it, then commit and open a PR.

Claude Code creates a branch (something like fix/empty-email-validation), finds the signup form component and its validation logic, adds the check, writes a couple of test cases (empty string, whitespace-only string), runs the test suite, and — once it passes — stages the changes and writes a commit message. A decent one looks like:

Add email field validation on signup form

Empty and whitespace-only email values were passing client-side validation. Adds a non-empty check and two test cases covering blank and whitespace-only input.

Then it opens the PR, using the commit message as a starting point for the PR description, often adding a short "how to test this" section. You get a link back in your session.

This is genuinely convenient — the kind of task that used to eat 20 minutes of context-switching between editor, terminal, and browser now happens without leaving the chat. But the trade-off is real: convenient doesn't mean unsupervised. You still need to read the diff before it goes out, the same way you'd read your own diff before pushing it. A commit message can sound confident and still describe a fix that's slightly off — Claude Code doesn't know your team's edge cases, your on-call history with that code path, or whether "empty string" and "null" are handled the same way three functions upstream. I've caught PRs that fixed the exact bug in the issue while missing a related case one function away, because the model was solving the ticket as written, not the actual shape of the bug.

The rule of thumb: let it handle the mechanical parts — branch naming, commit formatting, PR boilerplate — but read the diff like you'd read a teammate's PR, not like you're rubber-stamping your own.

Real Workflows: Onboarding, Refactors, and Debugging

Onboarding to an unfamiliar codebase

The old way to get oriented in a new codebase is to click through folders and guess. A faster start:

Give me an overview of this codebase: main entry points, how the folders are organized, what the core data models are, and anything that looks unusual or non-standard compared to a typical project of this type.

Claude Code will read through the structure and give you a working map — not perfect, but enough to know where to look next. Then get specific:

Trace what happens when a user submits the checkout form, from the frontend click through to the database write.

This second prompt is the more useful one. A folder overview tells you what exists. Tracing a real user action tells you how the pieces actually connect — which is usually what you need in your first week, when someone asks you to fix something in a flow you've never touched.

A multi-file refactor

Refactors are where vague prompts cause the most damage, because "clean this up" means something different to you than it does to the model. Be specific about scope and constraints:

Refactor the payment processing module to use the Strategy pattern instead of the current if/else chain for payment providers. Keep the public function signatures in payment.ts unchanged — other files import from it and I don't want to touch those call sites. Show me the plan before making changes.

Note two things doing real work here: the constraint ("keep signatures unchanged") and the request for a plan before edits. Without the constraint, I've seen refactors ripple outward into files that didn't need to change, just because the model found a "cleaner" shape for something upstream. Without the plan step, you find out about scope creep after it's already touched eight files instead of before.

Debugging a failing test

This is the workflow where letting Claude Code run commands earns its keep, because debugging is inherently iterative — run, read the error, adjust, run again — and that loop is tedious to do by hand.

The test in checkout.test.ts called "applies discount code before tax" is failing. Run it, read the error, and fix the underlying issue — not just the test.

That last clause matters. Left alone, a model under pressure to make a red test green will sometimes take the easy path: loosen an assertion, add a special case, mock around the problem. Telling it explicitly to fix the underlying issue, not the test, pushes it toward the harder and more correct fix. In practice, watch what it does after the first run — if it's editing the test file more than the source file, that's a sign the fix skipped the real work, and it's worth stopping and asking it to explain why the test was failing in the first place.

Advanced Setup: MCP, Hooks, and Automation

Once you're comfortable with the basics, three features change what Claude Code can actually do for you: MCP servers, hooks, and non-interactive mode. None of these are required to get value out of the tool. All three are worth setting up once your usage moves past "help me write this function."

MCP servers: giving Claude Code access to your actual systems

MCP (Model Context Protocol) is how Claude Code talks to things outside your codebase — a Postgres database, your Slack workspace, a ticketing system, internal APIs. Without MCP, Claude Code only knows what's in your files and what you tell it. With an MCP server connected, it can query your database directly instead of you copy-pasting schema into the chat.

A concrete case: I connected an MCP server to a staging database so I could ask "show me the last 20 orders where the discount code didn't apply" and get an actual answer, instead of writing the query myself, running it, and pasting results back in. That's not a huge time save on any single query. It adds up over a week of debugging sessions where the back-and-forth of "run this, tell me what you get" disappears.

The trade-off: every MCP server you add is another thing with access to real data, and another thing that can go stale, misconfigure, or return bad results that Claude Code trusts a little too much. Start with one server for the system you touch most, not five for everything you might someday need.

Hooks: running commands automatically on events

Hooks let you run a shell command whenever something specific happens — after a file edit, before a commit, after a tool call. The most useful one I've set up is a post-edit hook that runs the project's linter every time Claude Code saves a file:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npx eslint --fix $CLAUDE_FILE_PATH" }]
      }
    ]
  }
}

Why this matters: without it, lint errors pile up silently across a long session and you find them all at once at the end, usually right before a commit. With the hook, each edit gets cleaned up immediately, and Claude Code sees the linter output if something fails — so it can fix its own formatting mistakes in the same turn instead of you catching them later.

Non-interactive mode: Claude Code in CI

Claude Code doesn't have to run in a chat session. The claude -p flag runs it non-interactively: you give it a prompt, it does the work, it exits. That's what makes it usable in CI pipelines — for things like "review this PR diff and flag anything that looks like a security issue" running automatically on every pull request, with output posted as a comment.

I'd treat this as an addition to your existing checks, not a replacement. It's good at catching the kind of thing a human reviewer skims past on a Friday afternoon. It's not a substitute for a person who understands why the code exists.

Pricing: Pro, Max 5x, Max 20x, and API — What You Actually Pay For

The pricing is genuinely confusing at first because you're choosing between a flat subscription and metered API billing, and the right answer depends entirely on how you use the tool, not just how much.

The subscription tiers — Pro, Max 5x, and Max 20x — give you a set amount of Claude usage per month for a flat fee, with Max 5x and Max 20x giving you roughly 5 and 20 times the usage of Pro, respectively, at a higher price. In practice, this means: light use (a few sessions a week, mostly asking questions and reviewing small diffs) fits comfortably in Pro. Heavy agentic use — long sessions where Claude Code is reading files, running tests, iterating on fixes, and editing multiple files per prompt — burns through usage fast enough that Pro limits will interrupt you mid-task, and Max 20x becomes worth it if you're doing this most of your working day.

API billing is metered per token, no flat cap, no monthly plan. It makes more sense than a subscription in two cases: you're running Claude Code non-interactively in CI or automation where usage is unpredictable and spiky, or your usage is genuinely light enough that a subscription's flat fee costs more than what you'd actually use. If you're an individual developer with steady daily use, the subscription is almost always the better deal.

The trade-off worth naming clearly: agentic workflows are expensive in a way that chat is not. A single "find and fix this bug" session involves Claude Code reading multiple files, running commands, reading their output, and iterating — each of those round trips consumes tokens, and a long debugging session can rack up the token equivalent of a very long conversation in a few minutes. A full day of genuinely heavy use — multiple long agentic sessions, big refactors, extensive test-and-fix loops — has cost me the API equivalent of $20–40 in a single day when I've tracked it. On a subscription, that same day just eats into your usage cap instead of your wallet, which is the real argument for Max over API if your use is heavy and daily.

My rule of thumb: start on Pro. If you hit usage limits more than once or twice a week, move to Max 5x before jumping straight to Max 20x or API — most people overestimate how much they need.

What Didn't Work: Limitations and Trade-offs

Here's the part most guides skip because it's less flattering. These are real failure modes I've hit, not hypothetical caution.

Context window limits show up hard on large monorepos. On a codebase with a few hundred files, Claude Code's overview prompts work well. On a monorepo with tens of thousands of files across a dozen services, it can't hold the whole picture in context at once — it reads what it can, makes reasonable inferences, and sometimes those inferences are wrong because the file that would have corrected them was never loaded. The practical fix is to scope every prompt to a specific directory or service rather than asking about "the codebase" as a whole. That works, but it means you're doing some of the navigation yourself instead of getting the one-shot overview that works so well on smaller projects.

Over-confident edits are the failure mode that costs the most time. Claude Code will occasionally make a change, tell you it fixed the issue, and be wrong — not maliciously, just wrong the way a confident but mistaken teammate is wrong. I've had it "fix" a failing test by editing the test's expected output to match the buggy behavior, present it as done, and move on. The tell is usually a diff that's smaller and more convenient than the bug deserved. When something gets fixed suspiciously easily, check the diff before you trust it.

Cost unpredictability is real, especially in agentic mode. A prompt that seems simple — "refactor this and update all the call sites" — can spiral into a dozen tool calls if the refactor touches more files than expected. On a subscription this just eats your usage cap faster than planned. On API billing, it shows up as a bill that's harder to estimate in advance than a per-request tool would be.

And plainly: sometimes grep is just faster. If I know roughly what I'm looking for and roughly where it is — a specific function name, a specific string in an error message — typing grep -r "applyDiscount" is faster than writing a prompt, waiting for Claude Code to read files, and reading its summary of what it found. The agent earns its keep when the task requires understanding relationships between files, not when it's a lookup you could do yourself in five seconds. Reaching for the agent by default, even for tasks a simple search would solve, is the most common way people waste time with this tool.

Claude Code vs Cursor, Copilot, and Codeium

The honest way to think about these tools is by where they live and what they're optimized for, not which one is "better."

Copilot and Codeium are autocomplete-first. You're typing, and they finish your thought — a line, a function, sometimes a whole block. They're fast, they stay out of your way, and they're great for the moment-to-moment work of writing code you already know how to write. They don't plan, they don't run tests, and they don't touch files you're not actively looking at.

Cursor sits a layer up. It's a full IDE with chat and inline edit built in, so you can select a block of code and ask for changes without leaving the editor. It's IDE-first — the whole experience assumes you're looking at files, and the AI works around that. It's a strong middle ground if you want AI help but want to stay visually in control of what's changing.

Claude Code is terminal-first and agent-first. You give it a task, not a line of code, and it decides which files to read, what to run, and what to change — across multiple steps, without you approving each one. That's the entire trade-off in one sentence: Cursor and Copilot keep you in the loop constantly; Claude Code steps out of the loop and reports back.

In practice, I use Copilot-style autocomplete for routine typing, Cursor when I want to make a scoped edit while watching it happen, and Claude Code when the task is "go do this multi-step thing and tell me when it's done" — a refactor across a dozen files, a bug hunt that needs to trace a call path, a test-and-fix loop. If you're writing code line by line, an autocomplete tool is faster. If you're delegating a task and checking the result, Claude Code is built for that. Most people end up using more than one, and that's fine — they're not really solving the same problem.

Security and Data: What to Know Before You Give It Repo Access

Claude Code can read and edit files, and in agentic mode it can run commands — so before you point it at a repo, know what you're exposing.

Start with permission scoping. Claude Code asks before running commands or making edits unless you've turned on auto-approve for a session. Keep auto-approve off in any repo with production access or real credentials. It's slower, but it's the difference between reviewing a risky command and finding out after it ran.

On data retention: check Anthropic's current terms before assuming anything, since policies change. As of now, API usage isn't used to train models by default, but you're still sending file contents to a third party over the network. Treat that the same way you'd treat any cloud tool — fine for most code, not fine for anything under a strict compliance requirement without checking your organization's policy first.

The practical risk isn't Anthropic misusing your code — it's Claude Code reading a .env file or a config with plaintext secrets because nothing told it not to. Fix this the same way you'd fix it for version control: exclude sensitive paths explicitly. Add a .claudeignore-style pattern (check current docs for the exact supported syntax) covering .env*, credential files, and any directory with keys or tokens. Do this once, in your global config if the tool supports it, so you're not re-adding it per repo.

The blunt version: don't point Claude Code at a repo with secrets sitting in plaintext, full stop. Use a secrets manager or environment injection instead. That's good practice with or without AI tools — this just raises the cost of skipping it.

Try This Today

Here's a ten-minute test that won't touch anything important.

1. Install Claude Code if you haven't: npm install -g @anthropic-ai/claude-code (check current install docs in case this has changed).
2. Pick a real repo you actually work in, but not a critical one — a side project or an internal tool, not production infrastructure.
3. Run /init inside it. This generates a CLAUDE.md file summarizing the project structure, conventions, and setup. Read it. Fix anything it got wrong — that file is what Claude Code reads before every future session, so five minutes of correction now saves confusion later.
4. Pick one file you don't fully understand — something you inherited, or wrote in a hurry six months ago — and ask: "Explain what this file does and why it's structured this way."

Read the explanation critically. Does it match what you know? Did it catch something you missed, or miss something obvious? That gap is useful information — it tells you how much to trust this tool on your actual codebase, before you hand it anything that matters.