Getting Started with Claude Code

Claude Code is Anthropic's terminal coding agent. It reads files, runs shell commands, edits code, and chains actions across a task. This page walks through installation, authentication, the first session, and what to expect on cost.

Install

Claude Code ships as an npm package. You need Node 18 or newer. Check with node --version first.

npm install -g @anthropic-ai/claude-code

Confirm the install:

claude --version

If the claude binary is not on your PATH, your npm global bin directory is probably not exported. Run npm config get prefix and add /bin to your shell PATH.

On Windows

Windows support works through WSL2. Native PowerShell is not supported. Install WSL2 with Ubuntu, install Node inside the WSL distribution, then install Claude Code with npm. Running claude from inside WSL gives you a working terminal agent against Windows files mounted under /mnt/c/.

On macOS and Linux

Run the npm install command above. If you use nvm, the install goes into the currently active Node version. If you later switch Node versions, reinstall Claude Code under the new version.

Authenticate

Two paths: API key or OAuth.

Path 1: API key

Generate a key at console.anthropic.com under API Keys. Export it in your shell profile:

export ANTHROPIC_API_KEY=sk-ant-api03-...

Reload your shell and run claude. The session picks up the key from the environment. This path bills usage directly to the API account that owns the key.

Path 2: OAuth via claude.ai

Run:

claude auth login

A browser tab opens and prompts you to sign in to claude.ai. Token is stored at ~/.claude/credentials.json. This path bills against your claude.ai Pro or Max subscription rather than per-token API billing. Use this if you already pay for Pro.

You can switch between modes with claude auth logout and then claude auth login, or by unsetting ANTHROPIC_API_KEY.

Key safety

Never check ANTHROPIC_API_KEY into a repo. If you accidentally commit one, rotate it in the Anthropic console immediately. Use direnv or a .env.local that is git-ignored for project-specific keys.

First session

Change into any project directory and run:

cd ~/projects/my-app
claude

On first run Claude Code scans the directory for a few signals:

• CLAUDE.md in the repo root
• AGENTS.md in the repo root
• .claude/settings.json for project settings
• Parent directories up to your home folder for additional CLAUDE.md files
• ~/.claude/CLAUDE.md for global rules

It prints a ready prompt. Type your first request.

A sample first prompt:

List the top-level folders and tell me what this project does in two sentences.

Claude will use the LS and Read tools, open a README or package.json, and answer. Notice that read operations happen automatically. Write operations and shell commands trigger an approval step unless you change permission mode.

Reading vs editing

The three file tools behave differently:

• Read: opens a file for Claude. Runs without approval in default mode.
• Edit: applies a find-and-replace to an existing file. Prompts for approval by default, showing the diff.
• Write: creates or overwrites a file. Also prompts for approval by default.

A typical task like "add a dark mode toggle to the navbar" triggers a sequence: Read several files, propose Edit operations, pause for approval, apply the edits, then run npm test and wait for approval on the Bash call.

You can accept a single tool call, accept all calls for the rest of the session, or reject.

Permission modes

Three modes control approval behavior:

1. Default: prompts for approval on every write and every shell command.
2. Auto-accept: tool calls proceed without prompting. Toggle with Shift+Tab twice from default.
3. Plan: Claude describes every action before running it. Toggle with Shift+Tab once from default.

For first sessions stay in default mode. Switch to plan when you want a review before action. Reach for auto-accept only when the hooks and test suite can catch anything that goes wrong.

Writing your first CLAUDE.md

A minimum viable CLAUDE.md at the repo root gives Claude enough context to stop asking repetitive questions. Start with five rules:

# Project Rules

- Language: TypeScript, strict mode, no `any`.
- Framework: Next.js App Router.
- Test command: `pnpm test`.
- Lint before commit: `pnpm lint`.
- Commit style: conventional commits (feat, fix, chore, docs).

This file is injected into every session. Keep it short at first, expand when you notice a repeat correction you keep making.

Cost expectations

Billing depends on which model is active and which auth path you picked.

API pricing on Sonnet 4 at the time of writing: about $0.003 per 1,000 input tokens and $0.015 per 1,000 output tokens. Opus 4 is roughly 5x that. Haiku 4 is roughly a third.

Typical session costs on Sonnet 4:

• A quick bug fix that reads three files and edits one: $0.05 to $0.25
• A feature ticket with 10-15 tool calls: $0.50 to $2.00
• A multi-hour refactor that reads 50+ files: $3 to $10

Heavy daily use lands at $2 to $8 per day for most developers. Pair that with /cost at the end of sessions to build a mental model.

If you are on Pro or Max via OAuth, you hit rate limits rather than a dollar bill. Pro includes an hourly usage budget; Max raises it. Once the budget is hit, the session pauses until it refills.

Common first-session mistakes

1. Running claude outside the project directory. Claude operates on the working directory. Change in first.
2. Not writing a CLAUDE.md. Without it Claude has to guess conventions and often picks the wrong ones.
3. Accepting auto-mode on the first task. You will not catch mistakes early enough to correct them.
4. Treating the chat as ephemeral. The session context counts toward token cost. Hit /compact when you change topics.
5. Leaving a secret in a committed file. Hooks and a .gitignore entry prevent this.

The /help menu and built-ins

Type /help in any session to see every available command. The most used built-ins:

• /compact: summarizes the session and resets context with the summary as the starting point.
• /clear: wipes context entirely.
• /model: switch models mid-session.
• /cost: show token usage and running cost.
• /status: show model, permission mode, and session info.
• /doctor: diagnose setup issues like missing keys or outdated binaries.

Once you are comfortable, add custom slash commands by dropping markdown files into ~/.claude/skills/. See the skills reference for that path.

Updating

Npm global installs get stale. Update with:

npm install -g @anthropic-ai/claude-code@latest

Run /doctor inside a session if you suspect a version mismatch. Release cadence is roughly every two weeks; new features land with the latest tag.

A sample first-hour workflow

Here is a concrete walkthrough you can copy on any Next.js or Node project.

1. cd into the repo root.
2. Run claude.
3. First prompt: Summarize the architecture in 5 bullet points based on the folder structure and top-level config files. Claude reads package.json, tsconfig.json, and the src tree, then prints a summary. Cost: about 8,000 input tokens, 400 output tokens, roughly 3 cents on Sonnet 4.
4. Second prompt: Write a short CLAUDE.md capturing the conventions you just observed plus the test and lint commands from package.json. Claude drafts the file, asks for approval on the Write call, and you accept.
5. Third prompt: Pick the smallest TODO comment in the codebase and resolve it. Open a branch first. Claude runs git checkout -b fix/todo-, edits the file, runs tests, and stops.
6. Review the diff, run git diff, adjust the prompt if needed, commit.

That sequence exercises every major surface: reading, writing, shell commands, git operations, approval flow, and the /cost command you can run at the end to audit total spend. Expect $0.15 to $0.40 total for this walkthrough on Sonnet 4.

Where to go next

Once the first session feels natural, pick one upgrade at a time:

• Write better CLAUDE.md files. See the CLAUDE.md guide page for the import syntax and examples.
• Configure settings.json for model defaults and hooks. The settings.json reference covers every field.
• Add a PreToolUse hook to block dangerous shell commands. The hooks reference includes working shell scripts.
• Install an MCP server like filesystem or GitHub for extra capability. The MCP servers page covers setup.
• Create your first custom slash command in ~/.claude/skills/. The skills page shows the file format.

Keep sessions short when possible. A single session with 80k tokens of context costs more per turn than two sessions of 40k each, since every request sends the full context to the model. Use /compact aggressively when topics shift, and open a new session for unrelated tasks.