Getting Started with Claude Code

If you're not comfortable with the terminal, we recommend starting with the Claude Code Guide for Non-Engineers.

Claude Code is an AI coding agent that runs in your terminal (command-line tool). Simply give it instructions in plain English, and it handles a wide range of development tasks: reading and writing files, fixing code, running commands, and Git operations.

This article walks you through installing Claude Code and running your first command, step by step.

What is Claude Code

Claude Code is a terminal-native AI agent — distinct from the Claude chat UI you use in a browser or desktop app.

How it differs from the chat version

	Claude Web / Desktop	Claude Code
Environment	Browser / desktop app	Terminal (command line)
File access	Requires uploading	Direct access to local files
Run commands	Cannot	Can execute shell commands
Git operations	Cannot	Direct operations like commit and push
Best for	Q&A, writing, chat	Coding, file operations, automation

Claude Code is especially powerful in situations like these:

Understanding an entire codebase: Ask "Explain the structure of this project" and it will traverse the directory tree and give you an overview
Fixing bugs: Paste an error message and it will identify the root cause and implement a fix
Refactoring: Instruct "Clean up the functions in this file" and it will rewrite the code
Git operations: Ask "Review the changes and commit" and it handles everything from git diff to generating a commit message
Batch file processing: Automate repetitive tasks like "Merge all CSV files in this folder"

Pricing

Claude Code is available on the Pro plan and above. It is not available on the Free plan. Claude Code shares the same usage quota as the chat, so if coding is your primary use case, the Max plan is recommended. See Plan Comparison for details (check the latest pricing on the Anthropic pricing page).

Prerequisites

Before installing Claude Code, verify the following.

Supported OS

macOS 12 Monterey or later is required. Check your version with:

sw_vers -productVersion

Windows is supported. You can install using PowerShell, WSL, or WinGet (Git for Windows is required).

If you plan to use WSL and haven't installed it yet, run the following in PowerShell (as administrator):

wsl --install

Node.js 18 or later (only if installing via npm)

Node.js 18 or later is required only if you install Claude Code via npm. It is not needed when using the native installer.

node --version

If v18.0.0 or higher is displayed, you're good. If Node.js is not installed or the version is too old, install it from the Node.js official site.

Common pitfall: If you see node: command not found, Node.js is not installed. Download the LTS (long-term support) version from nodejs.org, or consider using the native installer which does not require Node.js.

Git

Git is required to use Git-related features.

git --version

If it's not installed, you can get it from the Git official site.

On macOS, installing Xcode Command Line Tools also includes Git.

xcode-select --install

In a WSL environment, install Git with:

sudo apt-get update && sudo apt-get install git

Installation

There are multiple ways to install Claude Code. The native installer is the officially recommended method.

Native Installer (Recommended)

No Node.js required, and it supports automatic background updates.

curl -fsSL https://claude.ai/install.sh | bash

For PowerShell:

irm https://claude.ai/install.ps1 | iex

For WinGet:

winget install Anthropic.ClaudeCode

Once installation is complete, verify the version:

claude --version

If a version number is displayed, the installation was successful.

Install with Homebrew (macOS only)

If you use Homebrew, you can also install with:

brew install --cask claude-code

On Windows, please use the native installer or npm instead.

Install with npm

Requires Node.js 18 or later. Use this if the native installer is not an option.

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

Common pitfall: If you see npm: command not found, Node.js is not installed. Address the "Node.js 18 or later" section first.

If you get an EACCES: permission denied error, try sudo npm install -g @anthropic-ai/claude-code. However, global npm installs with sudo can cause permission and security issues, so the official recommendation is to use the native installer.

After installation, running the claude command for the first time will start the authentication flow.

claude

On first launch, you will see a prompt asking you to authenticate with your Anthropic account. A browser window will open automatically and take you to the claude.ai authentication page.

Authentication steps

Run claude in your terminal
A browser window opens automatically, showing the Anthropic authentication page
Log in to claude.ai (or sign up if you don't have an account)
Once authentication is complete, your browser will show a "Authentication successful" message
Return to your terminal — Claude Code is now running

Common pitfall: If your browser doesn't open automatically, copy the URL displayed in your terminal and paste it into your browser.

Important: A Pro plan or above subscription is required to use Claude Code. If you log in with a Free plan account, you will see an error indicating the feature is unavailable.

Authenticating with an API key

If you have an Anthropic API key (paid API access), you can also authenticate via an environment variable.

export ANTHROPIC_API_KEY="your-api-key-here"
claude

Creating CLAUDE.md

CLAUDE.md is a configuration file you place in your project's root directory. Whatever you write in this file is automatically loaded by Claude Code when it works inside that project, and treated as context for the project.

This eliminates the need to explain "This project is built with Next.js..." every single time.

CLAUDE.md template

Create the following file at the root of your project:

touch CLAUDE.md

Here is a template. Customize it for your project.

# Project Overview

This project is [1-2 sentence description of the project].

## Tech Stack

- Language: TypeScript
- Framework: Next.js 15 (App Router)
- Database: PostgreSQL
- Package manager: pnpm

## Directory Structure

- `src/app/` — Page components
- `src/components/` — Shared components
- `src/lib/` — Utility functions
- `prisma/` — Database schema

## Coding Conventions

- Use TypeScript strict mode
- Write components as function components
- Use Vitest for testing
- Follow Conventional Commits for commit messages

## Common Commands

- `pnpm dev` — Start development server
- `pnpm build` — Production build
- `pnpm test` — Run tests
- `pnpm lint` — Run lint checks

## Notes

- Direct pushes to `main` are prohibited. Always create a Pull Request.
- Write environment variables in `.env.local`; record only variable names in `.env.example`.

CLAUDE.md can be freely customized for your project's size and type. The more detail you add, the more accurate Claude Code's responses become — but it's best to start simple and grow it over time.

Tips: You can also place a CLAUDE.md in your home directory (~/CLAUDE.md). It's useful for global settings shared across all projects, such as your preferred code style or language preferences.

Basic Usage

Claude Code has three main ways to use it.

1. Interactive Mode (conversational work)

Just type claude in your terminal to launch an interactive shell.

claude

Once launched, a > prompt appears. Enter your instructions in plain English.

> Explain the structure of this project
> Review the code in src/app/page.tsx
> Update the README.md
> Check the git diff and commit the changes

This mode is ideal when you want to work through multiple tasks in a conversational way, or when you want to review results and dig deeper. To exit, press Ctrl + C or type /exit.

2. One-Shot Mode (run once and exit)

Use the -p option to execute a single instruction and exit immediately.

claude -p "Generate a README for this project"
claude -p "List all TypeScript files in the src directory"
claude -p "Summarize the latest commit in plain English"

This is handy for scripting or automating routine tasks.

3. Pipe input

You can also pipe the output of other commands into Claude Code.

# Ask Claude to review a file's contents
cat src/utils/format.ts | claude -p "Review this code and suggest improvements"

# Ask Claude to analyze an error log
cat error.log | claude -p "Analyze this error log and identify the cause"

# Ask Claude to summarize a git diff
git diff | claude -p "Summarize these changes in commit message format"

Common pitfall: In interactive mode, a long conversation can approach the context limit (the amount of information the AI can hold in memory at once). If that happens, use the /compact command to summarize the conversation, or /clear to reset it.

Key Slash Commands

A list of slash commands available in interactive mode.

Command	Description
`/help`	Show a list of available commands
`/clear`	Reset the conversation history (use when starting a new task)
`/compact`	Summarize the conversation to save context
`/cost`	Show the number of tokens used and cost for the current session
`/model`	Switch the model in use (Sonnet / Opus, etc.)
`/exit`	Exit Claude Code
`/bug`	Report a bug or issue to Anthropic
`/review`	Rate the last response (submit feedback)

Controlling context

You can also explicitly specify which files Claude Code should reference.

# Launch with a specific file loaded
claude --file src/components/Button.tsx

# Launch with a specific directory
claude --dir src/components

During a conversation, type @filepath to add a file to the context.

> @src/api/users.ts Clean up the type definitions in this file

Tips: In large projects, starting with > Read the CLAUDE.md in this project and get familiar with the structure improves the accuracy of subsequent responses.

Try it out

Once installation is complete, let's actually run it. If you have an existing project, run it from that directory; if not, try it in any convenient folder.

# Navigate to your project directory
cd your-project

# Launch Claude Code
claude

# Example commands to try
> Explain the structure of the current directory
> If there's a README.md, read it and summarize its contents
> Summarize the latest 10 git log entries in plain English

As a first step, it's recommended to start by having Claude Code get familiar with your current project.

Next Steps

Now that you understand the basics of Claude Code, take your usage further.

Claude Code Guide for Non-Engineers — A gentle introduction even if you've never used a terminal before
Claude Code Practical Workflows — Practical workflows for code review, bug fixing, refactoring, and more
IDE Integration — How to use Claude Code together with VS Code or JetBrains IDEs
Plan Comparison — Differences between Pro / Max plans and Claude Code usage limits