# Claude Code Complete Tutorial

This is a comprehensive Claude Code tutorial designed for developers. Whether you're new to AI coding tools or migrating from other tools, this guide will help you master Claude Code — the most powerful AI coding assistant in 2026.

---

## 1. What is Claude Code

### An agentic coding assistant, not code completion

Claude Code is Anthropic's official CLI **agentic coding assistant**. Unlike traditional code-completion tools such as GitHub Copilot, it behaves like an experienced developer:

- **Understands the task on its own**: you describe what you want, it produces a plan
- **Works on code directly**: reads, edits and creates any file in the project
- **Runs terminal commands**: tests, dependency installs, builds
- **Understands the project deeply**: 200K token context window by default (`claude-opus-5` / `claude-sonnet-5` and others extend to 1M)
- **Dispatches subagents**: splits a complex task across several specialised subagents running in parallel

### Who uses it

Since its release in May 2025, Claude Code has become a core development tool at leading companies worldwide, including Netflix, Spotify, KPMG, L'Oréal and Salesforce. It reached the $1B annual revenue milestone in just six months.

### Key updates in 2025-2026

| Update | What it does |
|------|------|
| **Plan Mode** | Research and analyse first, then propose a plan — fewer mistakes |
| **Agent Teams** | Multiple agents working in parallel, isolated via git worktree |
| **Voice Mode** | Voice interaction — hold space and talk |
| **Computer Use** | Drives the desktop, browser and developer tools |
| **Hooks system** | 17 lifecycle events for automating workflows |
| **MCP protocol** | Connects external tools and services |
| **Skills** | Knowledge modules — shareable workflow templates |
| **Extended Thinking** | Reasons deeply in private before answering hard questions |
| **Opus 5 / Sonnet 5** | Current flagship and everyday default (4.8 / 4.6 still on sale) |
| **1M Context Beta** | `claude-sonnet-5` / `claude-opus-5` and others support a 1M token context |

### Why go through QCode.cc

Using Claude Code directly from mainland China runs into two problems: the network is unreachable and the cost is high. Through QCode.cc:

- **Low latency on Asia-Pacific nodes** — no VPN or self-hosted proxy needed
- **Up to 80% lower cost** than official pricing
- **Claude Code and Codex share one plan quota** — one plan, two tools
- **High availability across nodes** (HK / North America / Europe / global Route 53)

---

## 2. Installation & Setup

### System requirements

| Requirement | Detail |
|------|------|
| OS | macOS 12+, Ubuntu 20.04+, Windows 10+ (WSL2) |
| Node.js | 18.0 or newer (22 LTS recommended) |
| Git | 2.x or newer |
| Disk space | about 200MB |

### Install Claude Code

```bash
# npm install (recommended)
npm install -g @anthropic-ai/claude-code

# Users in China can speed this up with the Taobao mirror
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
```

### Configure QCode.cc

Set the environment variables in your terminal:

```bash
# Add to ~/.bashrc or ~/.zshrc
export ANTHROPIC_BASE_URL=https://api.qcode.cc/api
export ANTHROPIC_AUTH_TOKEN=cr_your_api_key
```

> **Why `ANTHROPIC_AUTH_TOKEN` and not `ANTHROPIC_API_KEY`**: a QCode.cc key starting with `cr_` is a **third-party gateway key**, not an official Anthropic key. When Claude Code sees `ANTHROPIC_AUTH_TOKEN` it sends `Authorization: Bearer <token>` to the gateway; with `ANTHROPIC_API_KEY` it sends `x-api-key` instead, which can collide with the OAuth session of an Anthropic account you are already signed into. **Using `ANTHROPIC_AUTH_TOKEN` is the official QCode recommendation.**

> **Get your API key** from the [QCode.cc console](https://qcode.cc/dashboard); it starts with `cr_`.

> **Choosing an endpoint**: the default is `https://api.qcode.cc/api` (global Route 53 picks the nearest node automatically). Users in mainland China should prefer `asia.qcode.cc` (Asia node, nearest of HK/JP, lowest latency). The other domains (`us` / `eu` / `asia`) and the BASE_URL rules are covered in [Endpoints & API Formats](/docs/getting-started/endpoints-and-api-paths).

Apply the configuration:

```bash
source ~/.bashrc  # or source ~/.zshrc
```

### Verify the installation

```bash
# Check the version
claude --version
# Prints a version number (yours may differ, see https://github.com/anthropics/claude-code/releases)

# Quick test
claude -p "Hello, please introduce yourself"
```

If Claude replies, installation and configuration succeeded.

### Shell completion (optional)

```bash
# Bash
claude completion bash >> ~/.bashrc

# Zsh
claude completion zsh >> ~/.zshrc

# Fish
claude completion fish > ~/.config/fish/completions/claude.fish
```

---

## 3. First Use

### Start

Run it in any project directory:

```bash
cd ~/my-project
claude
```

Claude Code scans the project structure automatically and enters interactive mode.

### Reading the interface

```text
╭─────────────────────────────────────────╮
│ claude                                   │
│                                          │
│ Project: my-project                      │
│ Model: claude-sonnet-5                   │
│ Context: 12,345 / 1,000,000 tokens       │
╰─────────────────────────────────────────╯

> _
```

Type in plain language — Claude will understand and act.

### First task: understand the project

```text
> Analyse this project's architecture and tell me the main modules and how they relate
```

Claude automatically:
1. Reads `package.json`, `README.md` and the directory structure
2. Skims the key source files
3. Produces a structured architecture analysis

### Permission prompts

When Claude wants to perform an action, it asks you to confirm:

```text
Claude wants to run:
  Tool: Bash
  Command: npm test

  [y] allow  [n] deny  [a] always allow in this session
```

- **y**: allow this once
- **n**: deny
- **a**: always allow this kind of action for the rest of the session (handy for everyday development)

### Common permission modes

| Mode | What it does | When to use |
|------|------|---------|
| Default | Confirm every action | First time, sensitive projects |
| `--allowedTools` | Specify which tools are allowed | Scoped automation |
| `--dangerously-skip-permissions` | Skip all confirmations | Isolated Docker environments, CI/CD |

---

## 4. Core Features

### 4.1 Plan Mode

Plan Mode makes Claude research and analyse first and only then propose a plan. It suits complex tasks.

```bash
# Enter plan mode
> /plan

# Or trigger it from the prompt
> Analyse the requirements and draft a plan first — don't change any code yet
```

**How it works**:
1. Claude analyses the codebase and the requirements
2. It proposes a plan (which files to create/modify, in which order)
3. You review the plan and ask for changes
4. Once confirmed, Claude executes it

**Example**:

```text
> /plan
> I want to add JWT-based user authentication to this project

Claude: Let me analyse the current project structure and draft a plan...

📋 Plan:
1. Create src/middleware/auth.ts — JWT verification middleware
2. Create src/services/auth-service.ts — authentication business logic
3. Modify src/routes/index.ts — add login/register routes
4. Create src/models/user.ts — user data model
5. Add dependencies: jsonwebtoken, bcrypt
6. Create test files

Does this plan work? Anything to adjust?
```

### 4.2 Extended Thinking

Opus 5 (and 4.8 / 4.7, still on sale) has built-in extended thinking — we recommend adaptive thinking together with the effort parameter, see the [Adaptive Thinking Configuration Guide](/docs/usage/adaptive-thinking). On hard problems it reasons deeply in private first.

```text
> I've been chasing this concurrency bug for two days. Analyse the race condition in src/worker.ts

[Claude reasons internally for thousands of tokens, walking execution paths, locking and timing]

Claude: Found it. On line 127 of worker.ts...
```

**When it kicks in automatically**:
- Complex debugging
- Architecture-level analysis
- Multi-step reasoning chains

### 4.3 Sub-agents

Claude can spawn specialised subagents for specific tasks:

```text
> Review this PR for me, and check for security issues at the same time

Claude: I'll start two subagents in parallel:
  - Subagent 1: code quality review
  - Subagent 2: security vulnerability scan
```

Subagents run in their own context, so they don't pollute the main session.

### 4.4 Key commands

| Command | What it does | Example |
|------|------|------|
| `/model` | Switch model | `/model opus` |
| `/plan` | Enter plan mode | `/plan` |
| `/compact` | Compact the context | `/compact` |
| `/cost` | Show current cost | `/cost` |
| `/clear` | Clear the context | `/clear` |
| `/init` | Generate CLAUDE.md | `/init` |
| `/review` | Code review | `/review` |
| `/help` | Help | `/help` |
| `Esc` | Cancel the current action | |
| `Ctrl+C` | Interrupt the response | |

### 4.5 Context management

Claude Code has a 200K token context window. Long sessions need managing:

```bash
# Check current context usage
/cost

# Compact the context (keep what matters, free space)
/compact

# Start a completely new session
/clear
```

**Best practices**:
- Run `/compact` once context usage passes 70%
- Start a new session with `/clear` when you switch tasks
- On complex projects keep background information in CLAUDE.md (`/compact` never removes it)

---

## 5. CLAUDE.md — Project Configuration

### Why you need CLAUDE.md

Every time Claude Code starts it reads the project's `CLAUDE.md` to learn the architecture, coding standards and local conventions. Without it you re-explain the project every session.

### Create it quickly

```bash
# Claude analyses the project and generates the file
/init
```

### File hierarchy

| Location | Scope | Git |
|------|---------|---------|
| `~/.claude/CLAUDE.md` | Global (all projects) | Not tracked |
| `project root/CLAUDE.md` | This project | Commit to Git |
| `.claude/CLAUDE.md` | This project (private) | Add to .gitignore |
| `subdirectory/CLAUDE.md` | That subdirectory only | As needed |

### Practical template: React + TypeScript project

```markdown
# MyApp

## Tech Stack
- React 19 + TypeScript 5.x + Vite
- Styling: Tailwind CSS v4
- State: Zustand
- Testing: Vitest + Testing Library

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint`

## Coding Standards
- Function components only; define Props with an interface
- The any type is not allowed
- CSS through Tailwind utility classes only
- Commit format: feat: / fix: / docs:

## Project Structure
- src/components/ — reusable components
- src/pages/ — page components
- src/hooks/ — custom hooks
- src/lib/ — utility functions
- src/api/ — API request wrappers

## Notes
- Node.js 22+, pnpm as the package manager
- All API requests go through src/api/client.ts
```

> For the full guide see [CLAUDE.md Configuration](/docs/usage/claude-md).

---

## 6. Model Selection

### Comparing the three models

Prices are a snapshot taken on 2026-08-16 from [qcode.cc/models](https://qcode.cc/models); **that page is the source of truth**. The 4.x models are still on sale, they are simply no longer the default.

| | Opus 5 | Sonnet 5 | Haiku 4.5 |
|--------|----------|------------|-----------|
| **Position** | Current flagship | Everyday default | Light and fast |
| **Reasoning** | Very strong | Strong | Adequate |
| **Code quality** | Very high | High | Medium |
| **Response speed** | Slower | Medium | Fast |
| **Context** | 1M / 128K | 1M / 128K | 200K |
| **Input price** | $5.00/M | $2.00/M | $1.00/M |
| **Output price** | $25.00/M | $10.00/M | $5.00/M |

### Switching models

```bash
# Switch inside an interactive session
/model opus    # switch to Opus
/model sonnet  # switch to Sonnet
/model haiku   # switch to Haiku

# Specify at launch
claude --model claude-opus-5
```

### Recommendations by scenario

| Scenario | Recommended | Why |
|------|---------|------|
| Architecture design | **Opus** | Deep reasoning, keeps the whole picture |
| Everyday coding | **Sonnet** | Best value |
| Bug fixing | **Sonnet** | Good enough and fast |
| Hard debugging | **Opus** | Extended Thinking |
| Code formatting | **Haiku** | Use the cheapest model for simple work |
| PR review | **Sonnet** | Balance of speed and quality |
| Large refactors | **Opus** | Needs whole-project understanding |
| Writing docs | **Sonnet** | Good enough |

### A mixed strategy (recommended)

```text
A day's model usage:
├── Sonnet 5 (70%) — everyday development, bug fixes, tests
├── Opus 5  (15%) — architecture decisions, hard problems
└── Haiku 4.5 (15%) — formatting, simple questions, bulk operations
```

You can switch at any point in a conversation:

```bash
# Plan with Opus first
/model opus
> Analyse this module's architecture and draft a refactoring plan

# Once the plan is agreed, switch to Sonnet to execute
/model sonnet
> Carry out step one of the plan
```

---

## 7. Advanced Tips

### Hooks

Configure automation hooks in `.claude/settings.json`:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILEPATH"
          }
        ]
      }
    ]
  }
}
```

> Full guide: [Hooks System](/docs/advanced/hooks).

### MCP servers

Connect external tools through the Model Context Protocol:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    }
  }
}
```

### Skills

Skills are reusable knowledge modules:

```bash
# List available skills
/skills

# Use a specific skill
> /commit    # generate a commit with the commit skill
> /review    # review code with the review skill
```

### --bare mode

Scripted invocation with all interactive features skipped:

```bash
claude --bare -p "List every TODO comment" --output-format json
```

---

## 8. Practical Examples

### Example 1: understand a new codebase

```bash
cd ~/unfamiliar-project
claude
```

```text
> Analyse this project:
> 1. which technologies it uses
> 2. the core modules and their responsibilities
> 3. how data flows through it
> 4. draw a simple architecture diagram (ASCII)
```

Claude browses package.json, the source directories and the config files, and produces a complete map of the project.

### Example 2: implement a feature with Plan Mode

```text
> /plan
> I need to add rate limiting to the API:
> - at most 60 requests per minute per user
> - store counters in Redis
> - return 429 with a Retry-After header when exceeded

Claude:
📋 Plan:
1. Install dependency: ioredis
2. Create src/middleware/rate-limiter.ts
3. Create src/config/rate-limit.ts (settings)
4. Modify src/app.ts (register the middleware)
5. Create tests/rate-limiter.test.ts
6. Update docker-compose.yml (add the Redis service)

Confirm and I'll start.

> The plan looks good, go ahead
```

### Example 3: debugging a hard bug

```text
/model opus
> Users report that "stock occasionally goes negative when orders are placed concurrently".
> Analyse src/services/order-service.ts and src/services/inventory-service.ts,
> find the concurrency bug and fix it.

[Opus engages Extended Thinking and walks execution paths, locking and transaction isolation levels]

Claude: Found it. On line 45 of inventory-service.ts the stock check and the decrement are not in the same transaction,
which is a TOCTOU race. The fix is to use SELECT FOR UPDATE...
```

### Example 4: batch refactoring

```text
> All class components in the project need to become function components + Hooks.
> Work through every .tsx file under src/components/ one at a time.

Claude will:
1. Find every class component
2. Convert them one by one to function components
3. Turn lifecycle methods into useEffect
4. Turn this.state into useState
5. Run the tests to confirm nothing broke
```

### Example 5: write a full test suite

```text
> Write a complete unit test suite for src/services/user-service.ts:
> - cover every public method
> - include both happy and error paths
> - mock external dependencies (database, cache)
> - target 90%+ coverage
```

### Example 6: CI/CD automation

```bash
# Inside GitHub Actions
claude -p "Review the code changes in this PR, focusing on security and performance" \
  --output-format json \
  --max-turns 3 \
  --allowedTools Read,Glob,Grep
```

> More CI/CD examples: [Automation & CI/CD](/docs/advanced/headless).

---

## 9. Claude Code + Codex Together

Claude Code and OpenAI Codex CLI are the two strongest AI coding tools of 2026, each with its own strengths.

**The best pairing**: Claude Code plans and reviews, Codex executes and does bulk work.

```bash
# 1. Claude Code drafts the plan
claude
> /plan
> Design an implementation plan for the user permission system

# 2. Codex executes it
codex "Follow the plan in PLAN.md and implement steps 1-3"
```

> **One QCode.cc plan, one shared quota for both tools** — switching costs nothing.
> Full comparison: [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code).
> Codex guide: [Complete Codex Tutorial](/docs/ide/codex).

---

> **Working as a team?** For teams of three or more we recommend the [Enterprise Team plan](https://qcode.cc/enterprise) — a dedicated domain `e-xxx.qcode.cc`, sub-API-key management, account protection, corporate transfer and invoices. See the [Enterprise Guide](/docs/reference/enterprise-guide).

## 10. FAQ

### Installation fails

**Q: `npm install -g` gives a permission error**

```bash
# Option 1: use sudo
sudo npm install -g @anthropic-ai/claude-code

# Option 2: manage Node.js with nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
npm install -g @anthropic-ai/claude-code
```

### Network problems

**Q: connection times out or is refused**

```bash
# Check the configuration
echo $ANTHROPIC_BASE_URL    # should be https://api.qcode.cc/api
echo $ANTHROPIC_AUTH_TOKEN  # should start with cr_

# Test connectivity
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" https://api.qcode.cc/api/v1/models
# -> 200 + a JSON model list = address, key and network all fine
```

### Controlling cost

**Q: I'm worried about the bill**

- Use **Sonnet** day to day (60% cheaper than Opus)
- Check spend any time with `/cost`
- Use `/compact` to shrink the context and cut token usage
- Send simple tasks to **Haiku** (the cheapest)
- See the [Cost Optimization Guide](/docs/usage/cost-optimization)

### Claude doesn't understand the project

**Q: Claude keeps misreading the project structure or conventions**

Create a `CLAUDE.md` (see chapter 5) and write down the project background, conventions and common commands. Claude reads it automatically on every start.

### How it differs from other tools

**Q: how is Claude Code different from Cursor / Copilot?**

| Tool | Type | Character |
|------|------|------|
| **Claude Code** | CLI agent | Plans and executes autonomously, understands the whole project |
| **Cursor** | IDE | Deep editor integration, real-time completion |
| **Copilot** | IDE plugin | Line-level completion, simple suggestions |

Claude Code is an agent-level assistant (it can complete complex tasks on its own), not a line-level completion tool. The two work well together: Cursor for real-time editing and completion, Claude Code for planning and executing complex work.

> **Note**: the same QCode.cc `cr_` key works with Claude Code, Codex CLI and a wide range of IDEs / CLIs / desktop apps including Cursor. For Cursor (custom Base URL + API Key) see [Cursor Editor Integration](/docs/ide/cursor); the protocol matrix and full list are in [Tool Compatibility Overview](/docs/ide/tool-compatibility).

---

## Related Docs

- [Installation Guide](/docs/getting-started/installation) — detailed installation steps
- [CLAUDE.md Configuration](/docs/usage/claude-md) — the full project configuration guide
- [Hooks System](/docs/advanced/hooks) — automation hooks in detail
- [Automation & CI/CD](/docs/advanced/headless) — using headless mode
- [Model Selection Guide](/docs/usage/model-selection) — detailed model comparison
- [Cost Optimization](/docs/usage/cost-optimization) — techniques for controlling spend
- [Codex vs Claude Code](/docs/getting-started/codex-vs-claude-code) — the two tools compared
- [Complete Codex Tutorial](/docs/ide/codex) — the full Codex guide
- [Plans & Pricing](https://qcode.cc/pricing) — QCode.cc plans