Claude in
your codebase
A command-line tool that reads your code, runs commands, makes changes, runs tests, and iterates. Not a chatbot that talks about code. A colleague that writes it.
Everything else in the handbook is about chatting with Claude. Claude Code is different. You point it at a real codebase, describe what you want, and it does the work: reading files, planning changes, editing code, running tests, committing, and opening pull requests. You stay in control, but the execution is autonomous.
This section is for anyone comfortable with a terminal who wants to understand what Claude Code can do, how to use it well, and where the edges are.
What it feels like
That is a real interaction shape: describe the problem, Claude reads the relevant files, finds the bug, fixes it, adds tests, runs the suite, and confirms everything passes. The whole thing takes about ninety seconds.
What it can do
Read your code
Reads files, understands project structure, traces dependencies across a codebase. Up to 1M tokens of context.
Edit files
Makes targeted changes to existing files with surgical precision. Diffs are reviewable before or after.
Run commands
Executes terminal commands: tests, builds, linters, scripts. Reads the output and adjusts based on results.
Create new files
Scaffolds new features, new test files, new configs. From a single file to a full project skeleton.
Debug
Takes a stack trace or error log, reads the relevant code, identifies likely causes, fixes the most probable one.
Refactor
Renames across a codebase, extracts functions, restructures modules, updates imports. With test verification.
Write tests
Reads a function, understands its behaviour, and generates test cases covering happy path, edge cases, and failures.
Review PRs
Reads a diff, checks for correctness, edge cases, security, and ranks comments by severity.
Commit and push
Creates branches, writes commit messages, pushes to remote, opens pull requests with descriptions.
Explain code
Reads unfamiliar code and explains what it does, how it works, and where the non-obvious bits are.
When to use Claude Code vs the chat
| Task | Use | Why |
|---|---|---|
| Fix a bug in your codebase | Claude Code | Reads the actual files, runs the actual tests |
| Explain a concept | Chat | No code to read, just a conversation |
| Build a new feature | Claude Code | Creates files, edits files, tests, commits |
| Draft an email | Chat | Text in, text out, no codebase involved |
| Refactor a module | Claude Code | Needs to trace dependencies across many files |
| Review a PR | Claude Code | Reads the diff in context of the full repo |
| Write a one-off script | Either | Chat can write it, Claude Code can write and run it |
| Learn a new language | Chat | Exploratory, no project to work in |
| Migrate 200 files to a new pattern | Claude Code | Bulk changes with verification at each step |
| Generate documentation | Claude Code | Reads the code to document what actually exists |
If the task involves reading or changing real files in a real project, Claude Code. If the task is a conversation, chat.
Who this section is for
Claude Code is for anyone comfortable with a command line. You do not need to be a senior engineer. If you can open a terminal, navigate to a folder, and run a command, you can use Claude Code. The steepest part of the learning curve is not the tool itself, it is learning when to trust it and when to check its work.
This section has six pages, each going deeper than the last:
- Getting started covers installation, your first session, and your first real task.
- The workflow covers the Explore, Plan, Implement, Commit cycle and when to use each permission mode.
- Patterns is the page to bookmark. Ten common tasks, each as a complete worked example with a terminal reconstruction.
- Configuration covers CLAUDE.md, hooks, permissions, settings, and cost management in depth.
- IDE integration covers VS Code and JetBrains for developers who prefer a graphical interface.
Start with Getting started if this is your first time.