Claude Code is Anthropic’s command-line interface that brings Claude directly into your development workflow. Unlike a web chat interface, Claude Code can read your actual files, run commands, and edit code across your entire project — without you copying and pasting anything.

This tutorial walks you through installation, core commands, and practical examples so you can start using it effectively from day one.

What Makes Claude Code Different

Most AI coding tools work like this: you paste a code snippet into a chat window, Claude suggests a change, you copy it back into your editor. This works for small tasks but breaks down quickly for anything complex.

Claude Code works differently. It’s an agentic tool — it operates inside your actual project directory and can:

  • Read any file in your project with full context
  • Edit files directly (with your permission)
  • Run shell commands and see their output
  • Search your codebase with grep and file glob patterns
  • Browse the web and fetch URLs
  • Connect to external services via MCP (Model Context Protocol)

The result is that you can describe a task in plain language and Claude Code will figure out which files to read, what changes to make, and how to verify the result — all in one session.

Installation

Claude Code requires Node.js 18 or later and an Anthropic API key.

Step 1: Install Node.js

If you don’t have Node.js:

# macOS (using Homebrew)
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows — download the installer from nodejs.org

Verify: node --version should output v18.x.x or higher.

Step 2: Install Claude Code globally

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

Verify the install:

claude --version

Step 3: Get an Anthropic API key

Go to console.anthropic.com, create an account, and generate an API key. Set it as an environment variable:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export ANTHROPIC_API_KEY="sk-ant-..."

Or set it just for the current session:

ANTHROPIC_API_KEY="sk-ant-..." claude

Starting Your First Session

Navigate to any project directory and run:

cd my-project
claude

Claude Code will read your directory structure and wait for your first message. You’ll see a prompt like:

>

Type your task in plain English. For example:

> Explain what this codebase does and list the main entry points.

Claude will read relevant files and respond with an explanation. The key difference from a chat interface: Claude actually reads your package.json, README.md, source files, and directory tree — it’s not guessing.

Essential Commands

Interactive mode (default)

claude                      # Start a session in the current directory
claude --continue           # Resume the most recent session
claude --model claude-opus-4-8  # Use a specific model

One-shot mode

Run a task without entering interactive mode:

claude "Add JSDoc comments to all exported functions in src/utils.ts"
claude "Find all TODO comments in the codebase and list them"
claude "Write a test file for src/auth.ts covering edge cases"

Slash commands (inside a session)

CommandEffect
/helpShow all available slash commands
/compactSummarise conversation history to save context
/costShow token usage and estimated cost for this session
/clearStart a fresh conversation (keep same directory)
/statusShow current model, context usage, permissions
/exitEnd the session

How Permissions Work

Claude Code asks for your permission before taking any action that modifies your system. You’ll see prompts like:

Claude wants to edit: src/components/Header.tsx
Allow? [y/n/always/never]

Your options:

  • y — allow this one action
  • n — deny this action
  • always — always allow this type of action for this session
  • never — always deny this type of action for this session

The permission system makes it safe to let Claude work autonomously on large tasks — you can always see and approve what it’s about to do.

Working with Files

Claude Code has built-in tools for file operations. You don’t need to tell it to use them — Claude decides when to read or edit files based on your request.

Reading files: Claude automatically reads relevant files when you ask about code. You can also be explicit:

> Read src/auth/middleware.ts and explain what each function does

Editing files: When you ask Claude to make a change, it shows you the exact diff before applying it:

> Refactor the login function to use async/await instead of callbacks

Claude will show you the proposed change and ask permission before modifying the file.

Creating files:

> Create a new file src/utils/formatDate.ts with a function that formats dates to YYYY-MM-DD

Running Shell Commands

Claude Code can run commands in your shell — linting, tests, builds, git operations. This is one of its most powerful features for debugging.

> Run the test suite and tell me which tests are failing

Claude will run npm test (or whatever your project uses), read the output, and explain what’s failing and why.

> Run eslint and fix any auto-fixable errors

Claude will run eslint, read the errors, fix the ones it can, and report back on the remaining issues.

The CLAUDE.md File

Create a file called CLAUDE.md in your project root to give Claude project-specific instructions that it reads automatically at the start of every session:

# ThinkStreamTV Site

## Tech stack
- Astro 5 (static output)
- TypeScript
- Custom CSS (no framework)
- Cloudflare Pages deployment

## Conventions
- All URLs use trailing slashes
- No emojis in content
- CSS uses design tokens from src/styles/global.css
- Blog posts live in src/content/blog/

## Commands
- Dev server: npm run dev
- Build: npm run build
- Type check: npm run check

With CLAUDE.md in place, Claude starts every session knowing your stack, conventions, and commands — no need to re-explain the project each time.

MCP: Connecting External Tools

MCP (Model Context Protocol) lets Claude Code connect to external services — databases, APIs, file systems. Once configured, these appear as additional tools Claude can use.

Example: connecting Claude Code to a PostgreSQL database so it can query your schema directly:

// .claude/mcp.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

After adding this, Claude can run SQL queries during your session:

> Look at the users table schema and write a migration to add a last_login_at column

Practical Examples

Example 1: Add tests to an existing module

> Look at src/stripe/webhooks.ts and write comprehensive tests for it in src/stripe/webhooks.test.ts. 
> Cover the success cases, error cases, and signature validation.

Claude reads the webhook handler, understands what it does, writes tests, and creates the file.

Example 2: Refactor a component

> The Header component in src/components/Header.tsx has grown too large. 
> Extract the mobile navigation into its own MobileNav component.

Claude reads the existing component, creates the new MobileNav.tsx, updates Header.tsx to import it, and shows you every change before applying it.

Example 3: Debug a build error

> The build is failing with this error: [paste error message]. Fix it.

Claude reads the file mentioned in the error, understands the context, finds the cause, and applies the fix.

Example 4: Documentation pass

> Go through every exported function in the src/utils/ directory and add JSDoc comments.
> Include @param, @returns, and a one-sentence description for each.

Claude reads each file, adds documentation, and shows you each edit.

Tips for Best Results

Be specific about scope. “Fix the login” is harder to act on than “Fix the 401 error that happens when the JWT token is expired in src/auth/middleware.ts”.

Point Claude at the right files. If you know which file is relevant, mention it: “Look at src/api/users.ts and…”. Claude will still read related files, but starting with the right one saves time.

Let Claude plan first. For large tasks, ask Claude to describe its plan before executing: “Before making changes, describe what you’re going to do and which files you’ll modify.”

Use /compact on long sessions. If a session has been running for a while, /compact summarises the history and frees up context for more work.

Write a CLAUDE.md. Any project you’ll work on more than once deserves a CLAUDE.md. It makes every future session start from a position of full context.

Model Selection

Claude Code supports multiple models. Choose based on the task:

ModelUse for
claude-sonnet-4-6Default — best balance of speed and quality
claude-opus-4-8Complex reasoning, large codebases, hard bugs
claude-haiku-4-5Simple tasks, fast completions, lower cost

Set the default model in your config or pass --model on the command line.

Next Steps

Once you’re comfortable with the basics:

  • Set up MCP servers for your database, file systems, or internal APIs
  • Configure hooks to run linting or formatting automatically after file edits
  • Use sub-agents for parallel tasks — run multiple Claude instances on independent subtasks
  • Explore the Agent SDK if you want to build your own tools on top of Claude’s capabilities

The Claude Code documentation covers all features in detail. Start there once you’ve worked through a few real tasks and want to go deeper.