Learning how to use Claude Code well is mostly learning how to hand a coding agent a job with clear boundaries. Anthropic’s terminal-based agent can read your files, run commands, edit code, and work through a task across many steps, but the quality of the result depends on the context and permissions you set up first. Get those right and it becomes the fastest way I’ve found to move through grunt work in a repo. The same principles apply whether you are asking how to use Claude Code for the first time or tuning a setup you have been running for months.
This guide covers installation, CLAUDE.md, plan mode, permission modes, automation, session management, and the failure modes that bite people in the first week. I based it on Anthropic’s official Claude Code documentation, checked August 2026. I have not treated documented behavior as personal hands-on testing.
What Is Claude Code?
Claude Code is an agentic coding environment that runs in your terminal. Anthropic’s docs describe it as a loop that works through three phases: gather context, take action, and verify results. The phases blend together. A question about your codebase might only need context gathering. A bug fix cycles through all three repeatedly.
The important difference from a chatbot is that Claude Code acts. It reads files, searches code, runs shell commands, and edits. Anthropic’s documentation says the built-in tools fall into five categories: file operations, search, execution, web access, and code intelligence. Each tool use feeds back into the loop and informs the next decision.
That agency is the whole point, and it is also the risk. The same command access that makes Claude Code productive makes a sloppy session expensive. You manage that with project instructions, plan mode, and permission modes, which is what most of this guide is about. If you want the short version of how to use Claude Code safely, those three controls are the answer.
What You Need Before You Start
You need a supported system and a project you are willing to let an agent touch. Anthropic’s setup documentation lists macOS 13.0+, Windows 10 1809+, and current Ubuntu, Debian, or Alpine as supported, with 4 GB+ RAM and an internet connection.
Before you open a session, commit or stash unrelated work. Run the existing test command yourself so you have a baseline. If the repository contains credentials or customer data, keep it out of the working tree or use an isolated environment. An agent does not need every file on your machine just because your terminal can see it. Most problems people hit when learning how to use Claude Code trace back to skipping this prep step, not to the tool itself.
How to Install Claude Code
Anthropic’s setup documentation covers installing Claude Code on macOS, Linux, and WSL with a curl installer script:
curl -fsSL https://claude.ai/install.sh | bashWindows users can run the PowerShell installer with irm https://claude.ai/install.ps1 | iex. There are also package-manager paths: Homebrew with brew install --cask claude-code, WinGet with winget install Anthropic.ClaudeCode, and signed apt, dnf, and apk repositories on Debian, Fedora, RHEL, and Alpine. A desktop app for macOS, Windows, and Linux exists for people who want a graphical interface instead of the terminal.
Native installations auto-update in the background. Homebrew and WinGet do not, so you upgrade those manually. After install, open a terminal in the project directory and run claude. That command is the heart of how to use Claude Code: everything else is configuration around it.
Set Up CLAUDE.md Before Serious Work
The single highest-leverage thing you can do when learning how to use Claude Code is write a CLAUDE.md. Anthropic’s best-practices guide recommends running /init to generate a starter file based on your current project structure, then refining it over time. The /init command analyzes the codebase to detect build systems, test frameworks, and code patterns.
CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules there. That gives the agent persistent context it cannot infer from code alone.
Keep the file short and human-readable. For each line, ask whether removing it would cause Claude to make mistakes. If not, cut it. A bloated CLAUDE.md gets ignored, and a file that gets ignored is worse than no file at all.
A practical starter looks like this:
# Project instructions
- Run `pytest -q` after Python changes.
- Run `npm test` after frontend changes.
- Keep API responses backward compatible.
- Never edit generated migration files by hand.
- Do not modify .env, credentials, or production data.
- Summarize changed files and test output before finishing.How to Use Claude Code in the Terminal
Start a session by running claude in the project root. Your first job should be small and verifiable. Ask for an overview of the codebase, an explanation of the main architecture patterns, or where a specific feature lives.
The official common-workflows guide offers prompt recipes for everyday tasks. For an unfamiliar codebase:
give me an overview of this codebase
explain the main architecture patterns used here
how is authentication handled?For a bug, tell Claude the command that reproduces the issue and paste the error. For a refactor, ask for a bounded change and existing patterns to follow. For tests, be specific about the behavior you want covered and let Claude match your existing test style.
The pattern that works: start broad, then narrow. Ask about coding conventions and project-specific terms before you ask for edits. A Claude session that understands the project first produces dramatically better work than one guessing from a vague prompt. This is the part of how to use Claude Code that feels slow at first and pays off immediately.
Explore First, Then Plan, Then Code
The biggest mistake people make with any coding agent is jumping straight to implementation. Anthropic’s best-practices guide recommends separating research and planning from execution. Once you know how to use Claude Code at the basic level, plan mode is the upgrade that stops you from paying for wrong assumptions.
Enter plan mode by pressing Shift+Tab until the status bar shows plan mode on, or start the session with claude --permission-mode plan. In plan mode, Claude reads files and answers questions without making changes.
Plan mode separates research and planning from implementation. Claude reads files and proposes a plan but makes no edits until the user approves it, and the plan can be opened in a text editor with Ctrl+G for direct editing. That is the workflow for anything that touches more than a couple of files.
The agentic loop Claude Code runs: gather context, propose a plan, get approval, edit, then review and verify.
A good plan names files, tests, assumptions, and anything it will not touch. If the plan is vague, refine it before approving. Fixing a plan is cheap. Repairing code written from a false premise is not. If you remember one rule about how to use Claude Code on real projects, make it this one.
Understand Permission Modes
Permission modes control when Claude pauses to ask before editing files or running commands. Anthropic’s permission-modes documentation lists the available modes: default, acceptEdits, plan, auto, dontAsk, and bypassPermissions.
The default mode allows reads only, which is right for getting started and for sensitive work. acceptEdits adds file edits and common filesystem commands. plan is for exploring a codebase before changing it. auto runs everything with background safety checks. dontAsk allows only pre-approved tools, which suits locked-down CI. bypassPermissions skips all checks and should only run in isolated containers and VMs.
Writes to protected paths are never auto-approved except in bypassPermissions mode. Anthropic’s docs list .git, shell config files, and .envrc among the protected paths, which means the default guardrails cover the files you most want protected.
Switch modes mid-session by pressing Shift+Tab to cycle default, acceptEdits, and plan. Match the mode to the task. A documentation edit does not need unrestricted shell access. A dependency upgrade may need package-manager access, but it still does not need your whole home directory. Permission modes are where most of the safety in how to use Claude Code actually lives.
Manage the Context Window
Claude’s context window holds the entire conversation, including every message, every file read, and every command output. Anthropic’s best-practices guide says performance degrades as context fills, which makes the context window the most important resource to manage.
A single debugging session can consume tens of thousands of tokens. When the window is getting full, Claude may start forgetting earlier instructions or making more mistakes. Watching this happen is how most people finally understand why good context hygiene matters in how to use Claude Code.
Practical habits: scope investigations narrowly, delegate broad exploration to subagents so file reads do not flood the main context, and keep CLAUDE.md concise. If a session has wandered far from its original task, start a fresh session and carry only the relevant context forward.
How to Use Claude Code for Automation and CI
Interactive sessions are for exploration. Repeatable jobs belong in non-interactive mode. Claude Code can run non-interactively with claude -p for CI, pre-commit hooks, or scripts, with plain text, JSON, or streaming JSON output formats for programmatic parsing.
A basic example from the official docs pipes git history into a summarization task:
git log --oneline -20 | claude -p "summarize these recent commits"Automation needs stricter contracts than chat. Define the allowed directory, the expected artifact, and the exact verification command. For unattended runs, use dontAsk mode with only pre-approved tools or keep permissions narrow. Make failure visible. A script that exits successfully after producing nothing is worse than a loud failure, because it creates fake confidence.
Resume, Fork, and Rewind Sessions
Claude Code saves each conversation locally as a plaintext JSONL file under ~/.claude/projects/, which enables rewinding, resuming, and forking sessions. Before Claude makes code changes, it also snapshots the affected files so a checkpoint can restore them.
Resume with claude --continue or claude --resume to reopen a session under the same ID and keep appending. Fork with --fork-session or /branch to copy history into a new session ID and leave the original untouched.
File edits are reversible. Before Claude edits a file, it snapshots the current contents. If something goes wrong, press Esc twice to rewind to a previous state, or ask Claude to undo. Checkpoints are separate from git and remain available when you resume a conversation. They only cover file changes, so actions that affect remote systems cannot be checkpointed, which is why Claude asks before running commands with external side effects.
Give Claude a Way to Verify Its Work
The best habit from Anthropic’s best-practices guide: give Claude a check it can run. A test suite, a build exit code, a linter, or a screenshot comparison turns a session you watch into one you can walk away from. Without a check, “looks done” is the only signal, and you become the verification loop. With a check, Claude does the work, runs it, reads the result, and iterates until it passes.
Have Claude show evidence rather than asserting success. Test output, the command it ran and what it returned, or a screenshot of the result. Reviewing evidence is faster than re-running verification yourself, and it works for sessions you were not watching. This closes the loop on how to use Claude Code for anything you plan to walk away from.
Common Claude Code Problems and Fixes
Claude misunderstands the repository
Stop implementation and ask it to explain the relevant files again. Improve CLAUDE.md, narrow the working directory, and include the acceptance condition. More autonomy will not repair missing context.
It changes too much
Reduce the task to one behavior and name excluded files or subsystems. Use plan mode and review the plan before approving. Check the diff after each coherent slice instead of waiting for a giant final patch.
Commands keep asking for approval
Check the permission mode instead of reflexively disabling safeguards. If the same safe command appears repeatedly, encode an appropriate project rule or use a controlled environment. Do not solve friction by granting unrestricted access.
Tests pass but the change is wrong
Tests only cover what they assert. Review behavior, interfaces, error handling, and the diff itself. Add a regression test that fails for the original bug and would fail again if the fix disappears.
The session loses direction
Restate the goal, current state, and remaining acceptance checks. For long work, ask Claude to write a checkpoint before continuing. If the task has grown into several unrelated jobs, split it.
Where Claude Code Fits
Claude Code is one of several serious coding agents, and it should not be your only evaluation point. My best AI coding agents comparison puts Claude Code next to Codex, Cursor, and Hermes with the tradeoffs spelled out. If you are coming from OpenAI’s tooling, my how to use OpenAI Codex guide covers the same ground for that stack.
Frequently Asked Questions
Can Claude Code edit an entire repository?
Yes, when its working directory and permission mode allow it. Broad access does not guarantee a good result. Start with inspection and a bounded task, then review every changed file.
Does Claude Code need CLAUDE.md?
The CLI runs without it, but CLAUDE.md gives the agent durable project-specific instructions. It reduces repeated corrections and makes automated runs more predictable.
Is Claude Code safe to run with full access?
Full access expands the blast radius of a mistake. Use bypassPermissions only in an isolated container or VM. For normal work, match the permission mode to the task and keep protected paths protected.
How long does it take to learn how to use Claude Code?
You can install it and run a basic session in an afternoon. Reliable use takes longer because the hard part is task design: clear context, bounded authority, good tests, and disciplined review. That is the whole game.
Can I use Claude Code in CI?
Yes. Anthropic documents claude -p for non-interactive execution with machine-readable output. CI jobs should use narrow permissions, explicit timeouts, deterministic verification, and visible failure. Automating how to use Claude Code for CI is a separate skill from interactive work, and the receipts matter more there.
The Setup That Actually Sticks
Learning how to use Claude Code is mostly learning how to give an agent a clean job. Write a concise CLAUDE.md. Explore before you edit. Use plan mode for anything that touches multiple files. Match permission modes to the task. Give Claude a check it can run and require evidence.
Claude Code moves fast and Anthropic ships frequently. Check the changelog, keep your project instructions current, and make every automated run leave evidence. Speed is useful. Reviewable speed is what you can trust.
