Claude Code Tutorial: From Zero to Your First Pull Request

This tutorial gets you from zero to a working Claude Code setup with a real pull request submitted. No theory, no comparisons. Just open your terminal and follow along.

Claude Code is Anthropic's agentic coding assistant — an ai-powered tool that lives in your cli, reads your entire codebase, and executes development tasks through natural language. Unlike ide plugins that suggest code snippets as you type, Claude Code plans multi-step implementations, handles git workflows, runs tests, and manages dependencies automatically. The llm underneath (Claude Sonnet and Opus models) powers everything from simple refactor tasks to complex multi-file debugging.

It launched in February 2025 and hit general availability in May 2025. By November 2025, it had reached $1B in annualized revenue — the fastest-growing ai coding tool on the market.

This tutorial is for beginners who want a hands-on, step-by-step guide. If you already have Claude Code installed and want advanced workflows, check out our how to use Claude Code power-user guide instead. And if you're still deciding between tools, our best AI coding assistant comparison covers the full landscape.

Prerequisites

You need three things:

1. A terminal — Terminal.app on macos, Windows Terminal on Windows, or any linux terminal
2. A Claude subscription — Pro ($20/month), Max ($100–$200/month), Team, or Enterprise. You can also use Claude Console API credits. Check pricing at claude.ai
3. A code project — any repo works, but this tutorial uses a Node.js project. The same functionality applies to Python, JavaScript, or any language

OpenAI's Codex and other ai tools offer alternatives, but Claude's models consistently rank at the top of coding benchmarks.

If you've never used a terminal before, Anthropic has a terminal guide in their docs.

Step 1: Install Claude Code

Open your terminal. The recommended install method depends on your OS.

macos or linux:

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

macos via Homebrew:

brew install --cask claude-code

Windows PowerShell:

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

Windows via npm (if PowerShell gives you trouble):

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

Windows requires Git for Windows. Install that first if you don't have it.

The native install auto-updates in the background. Homebrew and npm installs don't — you'll need to run brew upgrade claude-code or npm update -g @anthropic-ai/claude-code periodically to get new features and security fixes.

Verify the install:

claude --version

You should see a version number. If you get "command not found," restart your terminal or check that the install directory is in your PATH.

Step 2: Authentication

Start Claude Code for the first time:

claude

You'll see a welcome screen. It will prompt you to log in. You have three authentication paths:

• Claude Pro/Max subscription (recommended) — log in with your claude.ai account
• Claude Console — use api credits with pre-paid billing. A "Claude Code" workspace is auto-created for cost tracking
• Cloud providers — Amazon Bedrock, Google Vertex AI, or Microsoft Foundry for enterprise setups

Follow the prompts. You'll be redirected to a browser to complete authentication. Once done, credentials are stored locally — you won't need to log in again unless you run /login to switch accounts.

Step 3: Start your first session

Navigate to a project directory and launch Claude Code:

cd ~/projects/my-app
claude

Claude reads your project structure automatically. You don't need to manually add files to context. Ask it what it sees:

what does this project do?

Claude will analyze your files — package.json, source files, configs, docs — and give you a summary. Follow up with specifics:

what technologies does this project use?

This is Claude exploring your codebase. It uses built-in subagents — a fast, read-only "Explore" agent that searches and analyzes without burning through your main conversation history context.

Step 4: Set up CLAUDE.md

This is the step most beginners skip, and it's the most important one. A CLAUDE.md file at the root of your repo tells Claude how your project works. Every session, this file is automatically loaded into context.

Ask Claude to generate one:

analyze this codebase and create a CLAUDE.md file covering:
1. Tech stack and dependencies
2. Project structure
3. Build, test, and lint commands
4. Coding conventions you observe

Claude will scan your project and create the file. Here's what a good one looks like for a Node.js project:

# CLAUDE.md

## Tech stack
- Node.js 22, Express, TypeScript
- PostgreSQL with Prisma ORM
- Jest for testing

## Project structure
- `src/` — application source
- `src/routes/` — API endpoints  
- `src/models/` — Prisma models
- `tests/` — test files

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
- Dev server: `npm run dev`

## Conventions
- Use async/await, no callbacks
- All API responses follow { data, error } shape
- Tests required for new endpoints

Commit this file. Your whole team benefits from it. Treat it as a living document — when Claude makes a mistake, add a rule to CLAUDE.md so it doesn't happen again. This is how the ai assistant gets smarter over time for your specific repo.

Step 5: Make your first code change

Now use claude code for real work. Describe what you want in natural language:

add input validation to the POST /users endpoint -
email must be valid, name must be non-empty,
and return proper error messages

Claude will:

1. Find the relevant route file
2. Read the existing code
3. Plan the implementation
4. Show you proposed changes
5. Ask for permission before writing

Review the diff. If it looks good, approve it. If not, tell Claude what to change. The conversation history means Claude remembers your feedback and adjusts. This is the core functionality that makes Claude Code different from a simple chatbot — it code works directly on your files.

Step 6: Run tests and lint

After making changes, have Claude verify its own work:

run the tests and fix any failures

Claude will execute your test suite (using the commands from CLAUDE.md), read the bash output, and fix any issues. This is the feedback loop that makes ai coding actually reliable — the coding assistant doesn't just write code, it validates that it works.

For lint:

run lint and fix any warnings

Claude runs npm run lint (or whatever your lint command is), reads the output, and fixes the issues automatically.

Step 7: Create a pull request with git

Claude handles git workflows conversationally:

create a branch called feature/user-validation, commit these changes
with a descriptive message, and push to origin

Claude will run the bash commands:

git checkout -b feature/user-validation
git add -A
git commit -m "Add input validation to POST /users endpoint

- Validate email format using regex
- Require non-empty name field
- Return structured error responses with field-level messages"
git push origin feature/user-validation

Then create the pull request:

create a pull request with a description of what we changed and why

If you have the GitHub CLI (gh) installed, Claude uses it directly. If you have the GitHub MCP server configured, it can use that instead. Either way, you get a real PR with a proper description — a complete automation of the review-to-merge workflow.

Essential slash commands and shortcuts

These are the commands you'll use daily. Press ? inside Claude Code to see all keyboard shortcuts.

The /compact command is especially useful for long sessions. Claude auto-compacts at ~95% context usage, but manually compacting at 70-80% gives better results.

Working with VS Code and other IDEs

Claude Code isn't terminal-only. It's available as extensions for vs code and JetBrains IDEs:

• VS Code: Install the Claude Code extension from the marketplace. It adds a Claude panel alongside your editor.
• JetBrains: Available for IntelliJ, PyCharm, WebStorm via the plugin marketplace.

You can also use Claude Code on the web at claude.ai/code, through the desktop app, and in Slack via the Claude Code Slack integration.

The cli remains the most powerful interface for coding tools. The ide extensions are convenient but the terminal gives you the full functionality — including all slash commands, Plan Mode, subagents, and automation via bash scripting.

Common use cases for beginners

Here's a quick reference for the development tasks you'll use most:

Debugging:

there's a bug where the login page shows a blank screen
after entering wrong credentials - find and fix it

Refactor:

refactor the database module to use connection pooling

Code review:

review my recent changes and suggest improvements

Documentation:

update the README with current installation instructions

Dependencies:

update all npm packages to their latest versions and fix
any breaking changes

Each of these workflows leverages Claude's ability to read multiple files, understand the relationships between them, and make coordinated changes across your repo. That's what separates an ai-powered coding assistant from a basic chatbot — it understands your whole codebase, not just the file you're looking at.

Pricing and next steps

Claude Code pricing depends on your subscription (see our full Claude Code pricing breakdown for the detailed math):

• Pro ($20/month) — good for individual developers. Sonnet model for everyday use.
• Max 5x ($100/month) — 5x Pro's usage. Good for heavy daily use. See our Claude Max analysis for whether the upgrade is worth it.
• Max 20x ($200/month) — for developers running Claude Code all day.
• Console API — pay per token. No subscription needed.

Once you're comfortable with the basics in this tutorial, explore:

• Custom subagents — specialized ai agents for specific tasks in your workflows
• Hooks — run custom commands at lifecycle points (before/after tool execution)
• Skills — reusable patterns that teach Claude domain-specific development tasks
• GitHub Actions — automate code review and PR generation in CI/CD

All of these are covered in the official docs and our advanced guide to using Claude Code. The markdown format that CLAUDE.md uses for configuration also powers subagent definitions and skills — once you understand one, you understand them all.

Open your terminal, install Claude Code, and point it at a real project. The fastest way to learn is to use it on something you actually need to ship.

Related reading

• How to use Claude Code: the power user's deep dive — context management, subagents, GitHub Actions
• Claude Code: the AI coding tool that lives in your terminal — the full overview
• Claude Code pricing — every plan and how to save money
• Cursor vs Claude Code — comparing the IDE approach to the terminal approach
• Coding with AI: a practical workflow — the 6-step process from planning to code review