Claude Code for Beginners: From Install to First Productive Session

Most Claude Code tutorials bury the useful stuff under paragraphs of AI hype. You don't need a philosophy lecture on large language models. You need to install the tool, configure it, and get productive — ideally within your first hour.

This guide covers the exact steps from zero to a productive coding session. No fluff, no theory. If you follow along, you'll have Claude Code installed, configured with your project, and completing real tasks in under 30 minutes.

What Claude Code Actually Is

Claude Code is a terminal-based AI coding agent built by Anthropic. It runs in your terminal (not a browser, not an IDE plugin), reads and writes files, executes shell commands, and uses your local development environment directly.

What makes it different from ChatGPT or a browser-based Claude conversation:

• It sees your files. Claude Code reads your actual source code, not pasted snippets.
• It makes changes. It can create files, edit existing ones, and run your build tools.
• It runs commands. Tests, linters, git operations, package managers — anything your terminal can do.
• It persists across turns. Your conversation has memory within a session. Ask it to fix something, then ask a follow-up — it remembers the context.
• It understands your project. Through CLAUDE.md files and MCP tools, you can teach it your codebase's conventions, architecture, and patterns.

Think of it as pair programming with an AI that has direct access to your project — not a chatbot that works on copy-pasted code.

Installation: 5 Minutes

Prerequisites

You need Node.js 18 or higher installed. Check your version:

```bash

node --version

```

If you see v18.x or higher, you're good. If not, install Node.js from nodejs.org or via nvm.

You also need an Anthropic API key. Get one at console.anthropic.com — the free tier gives you enough tokens to follow this entire guide.

Install Claude Code

One command:

```bash

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

```

That's it. No GUI installer, no IDE extension, no account linking. The CLI is now available globally as `claude`.

Set Your API Key

```bash

export ANTHROPIC_API_KEY=sk-ant-your-key-here

```

Add this to your shell profile (~/.bashrc, ~/.zshrc, or equivalent) so it persists across terminal sessions.

Verify It Works

```bash

claude "What is 2+2?"

```

If you see Claude respond with "4" (probably with some extra commentary), you're set up. If you get an authentication error, double-check your API key.

First Commands: Getting Comfortable

Navigate to any project directory and launch Claude Code:

```bash

cd your-project

claude

```

This opens an interactive session. Now try these commands in order — they'll teach you the interface progressively.

Ask a Question About Your Code

```

What does this project do? Read the main entry file and summarize the architecture.

```

Claude Code will read your project files and respond. Watch what happens — you'll see it requesting permission to read files. Approve those permissions. This is your first experience with the tool's security model: it asks before accessing files.

Edit a File

```

Add a comment at the top of README.md that says "Updated by Claude Code"

```

Claude Code will show you the diff before applying it. You approve or reject the change. This review-before-apply workflow is fundamental — Claude Code never silently modifies your files.

Run a Command

```

Run the test suite and tell me which tests pass and which fail

```

Claude Code figures out how to run your tests (npm test, pytest, cargo test, etc.) and executes the command. It then analyzes the output and reports results in plain English.

Understanding the Interface

The Claude Code interface is minimal by design. Here's what you're looking at:

The prompt — Where you type your requests. Natural language, no special syntax required.

The token counter — Shows how many tokens you've used in the current session. This is your cost meter. A typical session consumes 50K-200K tokens depending on complexity. At Sonnet pricing ($3/M input, $15/M output), that's roughly $0.30-$1.50 per session.

The model indicator — Shows which Claude model you're using. Sonnet is the default (fast, cost-effective). Opus is available for harder tasks (slower, more expensive, more capable).

Permission prompts — When Claude Code wants to read a file, write a file, or run a command, it asks first. You'll see the exact action and can approve or deny it. You can also configure auto-approval for trusted actions.

Essential Commands

Claude Code has built-in commands prefixed with `/`. These are the five you'll use constantly:

• `/help` — Shows all available commands. Read this once, then forget about it.
• `/clear` — Wipes the current conversation and starts fresh. Use this when your session gets bloated with irrelevant context. A clean context window produces better results.
• `/compact` — Compresses the conversation history to save tokens without losing important context. Use this when you're mid-task but running low on context budget.
• `/model` — Switch between Claude models. Default is Sonnet. Switch to Opus for complex architecture decisions or tricky debugging. Switch back to Sonnet for routine tasks. This is your single biggest lever for cost control.
• `/cost` — Shows your token usage and estimated cost for the current session.

The pattern most experienced users follow: start with Sonnet, switch to Opus for hard problems, switch back to Sonnet immediately after. Opus costs 5x more — use it surgically.

Setting Up CLAUDE.md: Teaching Claude Your Project

This is the highest-leverage setup step most beginners skip. A `CLAUDE.md` file in your project root gives Claude Code persistent context about your project. It reads this file at the start of every session.

Create one:

```markdown

Project: My App

Stack

• Next.js 14 with App Router
• TypeScript strict mode
• Tailwind CSS v4
• PostgreSQL with Drizzle ORM

Commands

• `npm run dev` — start dev server
• `npm run test` — run vitest
• `npm run lint` — eslint + prettier check

Conventions

• Use named exports, not default exports
• All API routes go in `src/app/api/`
• Use Zod for all input validation
• Write tests in `__tests__/` co-located with source files

Architecture

• `src/app/` — Next.js routes and pages
• `src/lib/` — shared utilities and database client
• `src/components/` — React components (no business logic)
• `src/services/` — business logic layer

```

This file dramatically improves Claude Code's output quality. Without it, Claude Code guesses at your conventions and often guesses wrong. With it, Claude Code follows your patterns from the first interaction.

Time investment: 10 minutes. Impact: every session for the lifetime of the project.

Installing Your First MCP Server

MCP (Model Context Protocol) servers extend Claude Code with additional capabilities. They're plugins that give Claude Code access to external tools — databases, APIs, documentation, or context engines.

The most impactful first MCP server to install is a context engine. Without one, Claude Code reads files sequentially to understand your codebase, consuming thousands of tokens on exploration. A context engine pre-indexes your code and serves only the relevant parts.

Here's how to set up vexp as your first MCP server:

```bash

npm install -g vexp-cli

cd your-project

vexp init

vexp index

```

Then add it to your Claude Code MCP configuration:

```bash

claude mcp add vexp -- vexp-core mcp --workspace .

```

Now when Claude Code needs to understand your codebase structure, it queries the vexp index instead of reading files one by one. Token usage drops by 58% on average — which directly translates to faster sessions and lower costs.

Your First Productive Session: A Real Task

Theory is over. Let's complete a real coding task. We'll walk through adding a new API endpoint — a common task that touches multiple files and demonstrates Claude Code's strengths.

The Task

Add a `GET /api/health` endpoint that returns the application's status, version, and database connectivity.

The Prompt

```

Create a health check API endpoint at src/app/api/health/route.ts.

It should:

1. Return JSON with { status: "ok", version: string, db: "connected" | "error" }
2. Read the version from package.json
3. Test the database connection with a simple query
4. Return 200 if everything's healthy, 503 if the database is down

Follow our existing API route patterns.

```

Notice the prompt structure: what to create, where to put it, what it should do (with specifics), and what patterns to follow. This level of specificity is what separates productive Claude Code usage from frustrating back-and-forth.

What Happens Next

Claude Code will:

1. Read your existing API routes to understand patterns
2. Read `package.json` for the version
3. Check how your database client is configured
4. Write `src/app/api/health/route.ts` with the complete implementation
5. Show you the diff for approval

Review the code. If it looks right, approve it. If something's off, tell Claude Code what to change — "Use the db client from `src/lib/db.ts` instead of creating a new connection."

Verify It Works

```

Run the dev server and test the health endpoint with curl

```

Claude Code will start your dev server, hit the endpoint, and show you the response. If there are errors, it reads the error output and suggests fixes.

Total time for this task: 3-5 minutes. The same task done manually (finding patterns, writing the route, testing) typically takes 15-20 minutes.

Tips for Beginners

These lessons come from thousands of hours of collective Claude Code usage. Internalize them early.

Start Simple, Build Up

Don't ask Claude Code to "refactor the entire authentication system" on day one. Start with small, well-defined tasks: add a utility function, write tests for an existing module, fix a specific bug. Build your intuition for what Claude Code handles well before tackling complex projects.

Be Specific in Your Prompts

"Fix the bug" is a bad prompt. "Fix the TypeError in `src/auth/validateToken.ts` where `user.role` is undefined when the JWT payload doesn't include a role claim — add a fallback to 'viewer'" is a great prompt. Specificity is the single biggest determinant of output quality.

Watch Your Token Usage

Tokens are money. Every file Claude Code reads, every command output it processes, every long conversation turn — it all counts. Use `/compact` when conversations get long. Use `/clear` to start fresh when you switch tasks. Use Sonnet for routine work and Opus only when you need it.

Budget rule of thumb: a productive session costs $0.50-$2.00 on the API plan with Sonnet. If you're spending more than $5 per session regularly, your prompts are too vague or your sessions are too long.

Use Git as Your Safety Net

Claude Code can make mistakes. Always work on a branch, commit before major changes, and review diffs before approving. If Claude Code makes a bad edit, `git checkout -- filename` instantly reverts it. This safety net lets you experiment aggressively without risk.

Let Claude Code Run Commands

Many beginners manually run tests, then paste the output back into Claude Code. Don't do this. Tell Claude Code to run the tests itself. It sees the raw terminal output (with line numbers, stack traces, error codes) and produces better fixes than when you summarize errors in English.

Read the Diffs

Don't auto-approve everything. Read the diffs Claude Code shows you — especially early on. You'll learn what Claude Code does well (boilerplate, patterns, test writing) and where it needs guidance (architecture decisions, business logic edge cases). This calibration makes you a better prompter over time.

What's Next

You now have Claude Code installed, configured, and productive. The learning curve from here is about depth, not breadth:

• Learn subagents for parallel task execution
• Configure auto-approval rules for trusted actions to speed up workflows
• Add more MCP servers for your specific tools (databases, APIs, documentation)
• Optimize your CLAUDE.md as you learn what context Claude Code needs most

The developers who get the most out of Claude Code aren't the ones who ask the most complex questions. They're the ones who break work into clear, specific tasks, keep their context window clean, and use the right model for the right job.

Start simple. Be specific. Watch your tokens. Everything else follows.