Claude Code Install and Usage Guide: From Installation to Your First Code Change

Claude Code is a coding assistant from Anthropic. You start it inside a project folder and tell it what you want in plain language. It reads files, edits code, runs commands, and investigates errors, and it asks before it changes anything.

This guide starts from zero: install it, sign in, ask your first question, let it make your first change, and then cover the places beginners most often get hurt (permissions, undoing changes, secrets).

Check three things first

1. An account. Claude Code needs one of these:

• A Claude Pro, Max, Team, or Enterprise subscription
• A Claude Console account (pay by API usage)
• Access through a cloud provider such as Amazon Bedrock, Google Cloud, or Microsoft Foundry (mostly used at companies)

The official docs are explicit: the free claude.ai plan does not include Claude Code.

2. A supported region. Claude is only available in the countries Anthropic lists. Check that yours is on the list before you start. This site also has notes on account restrictions and bans (in Chinese): What I learned after 3 Claude bans, part 1 and part 2.

3. A computer that meets the requirements:

You do not need to install Node.js first.

Entry points: terminal, desktop app, editor

Claude Code comes in several forms:

If you have never used a terminal, read the official terminal guide first. It shows how to open one and how to paste a command.

Step 1: Install

Pick one method. When it finishes, close the terminal and open a new one.

macOS, Linux, WSL (recommended by the docs):

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

How to tell PowerShell from CMD: a PowerShell prompt starts with PS C:\, while a CMD prompt is just C:\. Pasting into the wrong one gives an error. In PowerShell, the CMD command complains that && is not a valid statement separator. In CMD, irm is reported as not recognized.

Other ways to install:

brew install --cask claude-code        # Homebrew
winget install Anthropic.ClaudeCode    # Windows WinGet
npm install -g @anthropic-ai/claude-code   # npm, needs Node.js 22 or later

There are also apt, dnf, and apk repositories for Debian, Fedora, RHEL, and Alpine. See the official install page. If you use npm, do not add sudo. The docs specifically warn that it causes permission problems.

On native Windows, it helps to also install Git for Windows so Claude Code can use its Bash tool. Without it, Claude Code falls back to PowerShell.

Verify:

claude --version

If it prints a version number (something like 2.1.295 (Claude Code)), you are done. For a more detailed health check, run:

claude doctor

If you see "claude: command not found"

This is the most common problem. It means the install folder is not on your PATH yet. First make sure you closed the old terminal and opened a new window. If that does not help, follow the official PATH fix. On macOS and Linux the native installer puts the launcher at ~/.local/bin/claude, so check that this folder is on your PATH.

The installer shows no progress bar while it downloads, so it can look stuck. Just wait for it to finish.

Step 2: Sign in and start

Go to the project you want to work on and type claude:

cd /path/to/your/project
claude

The first launch asks you to sign in. Follow the prompts and approve access in your browser, using one of the account types above. Your credentials are saved, so you will not need to sign in again. To switch accounts later, type /login inside Claude Code.

If you have set the ANTHROPIC_API_KEY environment variable and you approve the key when Claude Code asks, it skips the sign-in. In that case you are billed by API usage, not against your subscription.

Trusting the folder

The first time you start Claude Code in a folder, it also runs a safety check. It asks whether this is a project you created or one you trust, and reminds you that once you trust it, Claude Code can read, edit, and execute files in that folder.

• The cursor starts on No, exit. To continue, move to Yes, I trust this folder with the arrow keys and press Enter. Press Esc to cancel.
• Trusting is fine for your own code, well-known open source projects, and your team's projects. For a folder someone sent you, look through it first.
• This screenshot was taken in the home folder, which is too broad. As described above, cd into the specific project first and then run claude, so it only touches that project.

After you confirm, the version, current model, and working folder appear above the prompt. Type /help to see the available commands, or /resume to continue an earlier conversation.

Step 3: Ask your first question

Do not change anything yet. Let it read the project:

What does this project do?

What technologies does it use? Where is the entry point?

Explain the folder structure

Claude Code reads your files as needed, so you do not have to paste code. You can also ask it about itself, for example "how do I create custom skills".

Step 4: Let it make your first change

Add a hello world function to the main file

It finds a suitable file, shows you the change, and asks for your approval before making it. Look it over and choose Yes if it is fine.

That is a permission prompt. The next section explains how to control them.

Permission modes: how often should it ask?

A permission mode decides what Claude Code may do without asking you. Press Shift+Tab at any time to switch modes.

A few notes:

• According to the docs, from version 2.1.283 on, interactive terminal sessions start in auto mode by default (this needs a model that supports auto mode, and an organization admin can turn it off). Earlier versions did this only for Pro, Max, and Team plans. So your first session may not ask for every step. Check the mode shown in the interface, and press Shift+Tab to return to Manual if you want.
• You can also choose a mode at launch: claude --permission-mode plan.
• The command-line flag for bypassPermissions is --dangerously-skip-permissions, and "dangerously" is not decoration. Do not use it on a computer that holds real data.
• A safe combination for beginners: start unfamiliar tasks in plan so it proposes a plan, then switch to Manual or acceptEdits to execute it once you have read it.

Use Git: what if something breaks?

AI edits quickly, so you need to be able to undo quickly too. Two habits help:

1. Commit before you start. Ask it to "commit the current changes", or run git commit yourself. Whatever happens afterward, you can return to this point.
2. Use Claude Code's built-in undo. Type /rewind (aliases /checkpoint and /undo) to roll the conversation and the code back to an earlier point.

Claude Code can also run Git for you if you ask in plain language:

Which files have I changed?

Commit my changes with a clear message

Create a new branch called feature/quickstart

Help me resolve this merge conflict

Command cheat sheet

When launching from the terminal:

Inside a session (start with /):

Tip: typing / lists the commands and skills available to you. Use Tab to complete and ↑ to browse your input history.

CLAUDE.md: help it remember your project

Every new conversation starts from scratch. To make it remember how to run tests or what your code style is, write that down in CLAUDE.md, which is read automatically at startup.

The easiest start is to run /init in the project. It reads the code and drafts a file with build commands, how to run tests, and the conventions it finds. Then edit it by hand.

When you write it:

• Specific beats vague. "Run npm test after changes" works better than "care about code quality".
• Keep it short. The docs suggest under 200 lines per file. Long files use up context and are followed less reliably.
• It is guidance, not enforcement. CLAUDE.md is read as context, and Claude may not follow it every time. To truly forbid an action, use permission rules or hooks.
• If the project already has an AGENTS.md (the equivalent file used by Codex and other tools) and no CLAUDE.md, Claude Code reads AGENTS.md by default. If both exist, it reads only CLAUDE.md.

A minimal example:

# Project notes
- This is a Next.js site. Articles live in content/posts and are written in MDX
- Local preview: npm run dev
- Before committing, run: npm run lint and npm test
- Do not edit the generated files in data/

Claude Code also has "auto memory": it takes its own notes based on your corrections. Use /memory to view and toggle it.

Connect external tools (MCP)

MCP is how Claude Code connects to outside services, such as documentation, databases, or design files. To add a remote server:

claude mcp add --transport http notion https://mcp.notion.com/mcp

To add a server that runs locally (everything after -- is the command that starts it):

claude mcp add --env AIRTABLE_API_KEY=your-key --transport stdio airtable -- npx -y airtable-mcp-server

Then run claude mcp list to see what you added, and type /mcp in a session to check status and finish authorization. --scope chooses where it is saved: by default it applies only to the current project (local), project writes a .mcp.json in the project so the team can share it, and user applies to all your projects.

Only connect servers you trust. An MCP server can read your data and be called by the model, so do not add one from an unknown source.

How to write a good prompt

When I want it to do something, I put the task into four sentences:

1. What: one sentence on the result you want.
2. Where to look: which files or folders to check, so it does not wander through the whole project.
3. What not to touch: files, formats, or dependencies that must stay as they are.
4. How to know it is done: how the result is checked (tests pass, the change is visible on the page) and what it should report back.

A vague request:

Something is wrong with the article list, please fix it

The same request in four sentences:

The article list shows posts whose status is draft. It should show only published ones.
Look only at lib/posts.ts and the files under app/(zh)/posts.
Do not edit data/posts.generated.json. It is generated by a script.
When you are done, run npm run build and npm test, and once both pass, tell me which lines you changed.

For more ways to write prompts, see the official best practices.

Three more habits:

• Let it read first, then change. For complex tasks, start in plan mode so it explains what it intends to do.
• Split big tasks into steps. "First create the database table, then the API, then the page" is steadier than "build a user system".
• Run /clear when a task is done. The longer a conversation gets, the more likely it drifts, and the more of your quota it uses.

What it is good at, and what to avoid

Good at: understanding an unfamiliar project, fixing small bugs, writing tests, editing docs, refactoring, sorting through error logs, and writing release notes.

Do not hand these to it on your first try:

• Changes to payment, permission, or account code. You must read every line yourself
• Bulk deletion of files or data
• Edits directly on a production environment
• Important projects with no backup and no commits

Security essentials

• Do not paste secrets to it. Keep API keys and database passwords in .env, and confirm .gitignore excludes .env.
• Do not let it commit secrets. If a secret reaches GitHub, deleting the file does not help because it stays in the history. Revoke the key on the platform and generate a new one.
• Read before you approve. Pay particular attention to the shell commands it wants to run and the addresses it wants to reach.
• Do not use bypassPermissions on a machine that holds important data.

Updating and uninstalling

• Native installs update themselves in the background. To update right now, run claude update.
• Installs through Homebrew, WinGet, or Linux package managers do not update automatically: brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode.
• To uninstall a native install, delete ~/.local/bin/claude and ~/.local/share/claude. To clear your settings as well, also delete ~/.claude and ~/.claude.json. That removes your conversation history and MCP configuration.

One-page recap

1. Confirm your account (paid subscription or Console), region, and system.
2. Install with curl -fsSL https://claude.ai/install.sh | bash, or the PowerShell command on Windows.
3. Go to the project folder, run claude, and sign in in the browser.
4. Ask "what does this project do" first, then give it one small task.
5. Commit with Git first, use plan for unfamiliar tasks, and /rewind if something breaks.
6. Run /init to generate CLAUDE.md so you do not repeat yourself every time.

How it maps to Codex

If you are also looking at OpenAI's Codex, the concepts line up almost one to one, so the same habits carry over:

The matching guide is Codex Install and Usage Guide.

Official links

• Claude Code quickstart
• Advanced setup
• Permission modes
• CLAUDE.md and memory
• Commands reference
• MCP
• Troubleshooting installation