Claude Code Guide

Claude Code is an agentic coding tool that lives in your terminal. It can edit files, run commands, search your codebase, and interact with git — all through natural language.

Install on macOS, Linux, or WSL

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

Install on Windows

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

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

winget install Anthropic.ClaudeCode

Install ↗ Git for Windows so Claude Code can use the Bash tool. Without it, Claude Code falls back to PowerShell.

Install via Homebrew (macOS / Linux)

# Stable channel (~1 week behind, skips bad releases)
brew install --cask claude-code

# Latest channel
brew install --cask claude-code@latest

First launch

Open any project directory and run claude. You'll be prompted to log in on first use. Switch accounts later with /login.

cd your-project
claude

Run Claude Code in VS Code

You can also run Claude Code directly inside VS Code, JetBrains IDEs, and Cursor. Install the Claude Code extension from the VS Code marketplace, and it will appear as an integrated panel in your editor. Same machinery, just rendered inside the IDE.

Other useful launch flags

Claude Code uses a tiered permission system: read-only tools (file reads, grep) need no approval, bash commands require approval per project, and file modifications require approval per session. Rules are evaluated in order: deny → ask → allow. Deny always wins.

Where to configure

Permissions live in settings.json at two levels:

Permission Modes

Set defaultMode in your settings to change how Claude asks for approval:

Example 1: Minimal — auto-approve reads only

Good starting point. Claude can read your code freely but still asks before running commands or editing files.

{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob"
    ]
  }
}

Example 2: Solo developer — trust most tools

For personal projects where you want minimal interruption. Put this in your global settings.

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(git *)",
      "Read",
      "Edit",
      "Grep",
      "Glob",
      "WebFetch",
      "WebSearch",
      "mcp__*"
    ]
  }
}

Example 3: Team project — allow builds, block danger

Allow common dev commands but explicitly block destructive ones. Great for shared repos.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Read",
      "Grep",
      "Glob"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  }
}

Bundled Skills

These ship with Claude Code — no installation needed. Bundled skills are prompt-based: they give Claude detailed instructions and let it orchestrate the work using its tools. Invoke them with / followed by the skill name.

Custom commands are markdown files that become slash commands. Save them as skills (recommended) or in the legacy commands folder:

Use $ARGUMENTS in your skill to accept input when invoked.

Review the changes on the current branch compared to main.

Focus on:
1. Logic errors and edge cases
2. Security issues
3. Performance concerns
4. Missing error handling

Reference file names and line numbers.
Show the diff summary first.

Write tests for $ARGUMENTS

Cover:
- Happy path
- Empty / null input
- Error cases
- Edge cases

Use the existing test framework. Run tests after writing them.

Refactor $ARGUMENTS to be cleaner and more maintainable.

Rules:
- Keep the same behavior (no feature changes)
- Improve naming and readability
- Extract repeated logic into functions
- Add type hints if missing
- Run tests after to confirm nothing broke

Hooks are shell commands, HTTP calls, or LLM prompts that execute automatically at specific lifecycle points. Add them to .claude/settings.json (project) or ~/.claude/settings.json (global). Hook commands receive JSON on stdin with tool details.

Auto-format Python files after every edit

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs black 2>/dev/null; exit 0"
      }]
    }]
  }
}

Auto-format JavaScript/TypeScript with Prettier

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null; exit 0"
      }]
    }]
  }
}

Block dangerous commands

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' | grep -qE 'rm -rf|git push.*--force|git reset --hard' && echo 'Blocked: dangerous command' >&2 && exit 2 || exit 0"
      }]
    }]
  }
}

Protect sensitive files from edits

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | grep -qE '\\.env|secrets/|\\.git/' && echo 'Blocked: protected file' >&2 && exit 2 || exit 0"
      }]
    }]
  }
}

Desktop notification when Claude needs input

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Claude Code needs input\" with title \"Claude Code\" sound name \"Ping\"'"
      }]
    }]
  }
}

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "powershell -Command \"Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention','Claude Code')\""
      }]
    }]
  }
}

A subagent is a specialized AI assistant that runs in its own context window, does the work, and returns only the summary to your main session. The verbose output — file searches, log dumps, multi-step reasoning — stays isolated. Use one when a side task would flood your main conversation with stuff you won't reference again.

Subagents help you:

• Preserve context by keeping exploration and implementation out of your main conversation
• Enforce constraints by limiting which tools a subagent can use
• Reuse configurations across projects with user-level subagents at ~/.claude/agents/
• Specialize behavior with focused system prompts for specific domains
• Control costs by routing tasks to faster, cheaper models like Haiku

Define a subagent

Subagents live in .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (personal). The frontmatter description tells Claude when to delegate to it.

---
description: Research a topic across the codebase. Use when the user asks "where is X used", "what depends on Y", or for any read-only exploration that would flood the main context.
tools: Read Glob Grep
---

You are a focused codebase researcher. Your job is to investigate the user's question
across the project and return a concise summary with file paths and line numbers.

Process:
1. Find relevant files with Glob and Grep first
2. Read the files in depth
3. Return a structured summary: findings, file references, open questions

Don't edit anything. Don't run shell commands. Stay read-only.

Invoke and manage subagents

Open the subagent panel with /agents. The Running tab shows live subagents. The Library tab lets you create and edit definitions. Claude can also auto-delegate to a subagent when the description matches your request.

export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-4-5"

Skills + Subagents

A skill can run in a subagent by adding context: fork to its frontmatter. The skill content becomes the subagent's prompt, with the agent type controlling tools and model.

---
name: deep-research
description: Research a topic thoroughly across the codebase
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:

1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

While subagents are isolated workers that report back to the main agent, Agent Teams are multiple full Claude Code sessions that coordinate as peers. One session is the lead. The others are teammates that share a task list and message each other directly — no central dispatcher.

Subagents vs Agent Teams

Enable Agent Teams

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Start a team

After enabling, just describe the team you want in natural language. Claude creates the team, spawns the teammates, and coordinates.

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Behind the scenes Claude generates ~/.claude/teams/<team-name>/config.json and a shared task list at ~/.claude/tasks/<team-name>/. Don't edit these by hand — the runtime overwrites them.

Display modes

Best practices

• 3–5 teammates is the sweet spot. Beyond that, coordination cost eats the parallel-work gain.
• Avoid file conflicts. Two teammates editing the same file overwrites each other. Partition the work so each teammate owns a different set of files.
• Require plan approval for risky tasks: "Spawn an architect teammate to refactor auth. Require plan approval before any changes." The teammate stays in read-only plan mode until the lead approves.
• Use hooks to enforce quality gates: TeammateIdle, TaskCreated, TaskCompleted. Exit with code 2 to send feedback and keep the teammate working.
• Clean up with the lead when finished: "Clean up the team". Teammates shouldn't run cleanup — only the lead.

Claude reads CLAUDE.md at the start of every session. It's where you put your project's architecture, coding standards, build commands, and any rules you want Claude to follow.

For existing projects, run /init — Claude analyzes your codebase and generates a CLAUDE.md with the conventions it discovers. Then refine it with anything Claude wouldn't know on its own. For new projects, use the template below as a starting point.

Where to place it

Template

Use this as a starting guide — customize it for your project:

# Project: [Name]

## Tech Stack
- [Framework], [Language + version]
- [Database], [Key libraries]

## Commands
- Dev: [command]
- Build: [command]
- Test: [command]
- Lint: [command]

## Architecture
- [Where services live]
- [Where routes/views live]
- [Where models/types live]
- [Where tests live]

## Code Style
- [Rule 1 — be specific]
- [Rule 2]
- [Rule 3]

## Rules
- ALWAYS run tests after changes
- ALWAYS use TypeScript strict mode
- NEVER commit directly to main
- Keep files under 300 lines — split if larger

Skills are the next level beyond custom commands. They live at .claude/skills/your-skill-name/SKILL.md and support auto-triggering, bundled scripts, and subagent control.

Popular Skills

Find More Skills

The skill ecosystem is growing fast. Browse community directories:

Create Your Own Skill

Create a directory in .claude/skills/your-skill-name/ with a SKILL.md file. Add YAML frontmatter for name and description — Claude uses the description to decide when to auto-load it.

---
name: explain-code
description: Explains code with diagrams and analogies. Use when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy** — compare the code to something from everyday life
2. **Draw a diagram** — use ASCII art to show the flow or structure
3. **Walk through the code** — explain step-by-step what happens
4. **Highlight a gotcha** — what's a common mistake or misconception?

Keep explanations conversational.

The Three Pillars

The Development Cycle

Before writing any code, analyze the existing codebase structure and create a detailed plan. List every file you'll create or modify, and explain why. Wait for my approval before implementing.

Knowing everything you know now, scrap this and implement the elegant solution.

This error is happening: [paste error]
Don't just fix the symptom. Find the root cause, explain it, then fix it properly. Run tests after.

Use parallel subagents for these independent tasks:
1. [Task A]
2. [Task B]
3. [Task C]
Work on all three at the same time. Combine results when done.

Create a modular project structure for [description].
Each feature gets its own file in a logical folder structure.
No file should be longer than 300 lines.
Include type hints and error handling from the start.

Scan the entire project for files larger than 600 lines of code. List them sorted by size, and suggest how each could be split into smaller, focused modules.

Before you start, ask me questions to make sure you understand exactly what I want.

Plugins

A plugin bundles skills, hooks, subagents, MCP servers, and LSP servers into a single installable package. Instead of every teammate manually setting up the same skills + hooks, a plugin is a one-click install.

Run /plugin inside Claude Code to open the plugin manager. The Discover and Browse screens now show each plugin's commands, agents, skills, hooks, and MCP/LSP servers before installation — you see exactly what you're getting.

# Browse the manager UI
/plugin

# Install from the Anthropic-managed marketplace
/plugin install frontend-design@claude-plugins-official
/plugin install github@claude-plugins-official
/plugin install sentry@claude-plugins-official
/plugin install typescript-lsp@claude-plugins-official

Plugin Marketplaces

A marketplace is a marketplace.json file hosted on GitHub (or any git host) that lists multiple plugins from one source. Add the marketplace once; install any of its plugins thereafter.

# Add a community marketplace
/plugin marketplace add owner/repo

# Install a specific plugin from it
/plugin install name@marketplace

# CLI equivalent (without a session)
claude plugin install plugin-name

The default trusted source is ↗ anthropics/claude-plugins-official. For your own marketplace, publish a marketplace.json in a git repo — that's the whole setup.

MCP Servers

MCP (Model Context Protocol) servers give Claude Code access to systems it doesn't already understand: GitHub, your database, your browser, your production tooling. Add them with claude mcp add.

Recommended day-one MCP servers

# Browser automation — Claude can see your UI
claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest

# GitHub — PRs, issues, code search across repos
claude mcp add --transport stdio github -- npx @anthropic/mcp-github@latest

# Postgres — read schemas, run queries
claude mcp add --transport stdio postgres -- npx @modelcontextprotocol/server-postgres@latest postgresql://user:pass@host/db

# SimplerLLM — AI library docs and code examples
claude mcp add --transport sse simplerllm https://learnwithhasan.com/simplerllm/mcp/server/sse/

# Notion — connect to your workspace
claude mcp add --transport http notion https://mcp.notion.com/mcp

Learn more about the ↗ SimplerLLM MCP server for AI library documentation access. Use /mcp any time to view connection status.

Claude Code defaults to Anthropic models (Opus and Sonnet). Use /model to switch between them. For non-Anthropic models, ↗ CC Switch lets you route to 50+ models from providers like DeepSeek, MiniMax, OpenRouter, and more.

export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-4-5"

The Claude Agent SDK gives you the same tool-using agent loop that powers Claude Code, but as a Python or TypeScript library you import into your own application. Hand Claude an objective, and it autonomously reads files, runs commands, edits code, and iterates — all from inside your app.

The TypeScript SDK bundles a native Claude Code binary as an optional dependency, so you don't need to install Claude Code separately.

Install

pip install claude-agent-sdk
export ANTHROPIC_API_KEY=sk-ant-...

npm install @anthropic-ai/claude-agent-sdk
export ANTHROPIC_API_KEY=sk-ant-...

Your first agent in 8 lines

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

Built-in tools (no implementation needed)

Build it into a desktop app

The Agent SDK is built for being embedded. You spin up an async for message in query(...) loop inside your app's event handler, stream tokens to your UI, and respond to AskUserQuestion events with a native picker.

Real example: VidTSX. VidTSX is my desktop app for AI motion graphics. Inside it, Claude drives the whole production pipeline — script generation, scene layout, prompt-to-video render orchestration — using the Agent SDK. The same agent that fixes bugs in Claude Code is the one that writes a Remotion composition and schedules a render job. One binary, two surfaces.

→ See how VidTSX uses Claude under the hood ↗

What else you get

Compare to other Claude tools

Full docs: ↗ Agent SDK overview · ↗ Quickstart · ↗ Example agents repo

You can run Claude Code at $0 cost by pointing it at a free model on ↗ OpenRouter. We do this at the project level so it never touches your global Claude configuration — no conflicts, no broken main setup, just a sandboxed override for the one project you want free.

Step 1 — Create the project-level config. Inside the project where you want to use Claude Code for free, create a .claude folder, and inside it create a file named settings.local.json.

Step 2 — Get a free OpenRouter API key. Sign up at ↗ openrouter.ai, create an API key, then browse the models page and copy the slug of any model tagged free (for example minimax/minimax-m2.5:free).

Step 3 — Paste this into .claude/settings.local.json (replace the key and model slug with your own):

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "XXX",
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "minimax/minimax-m2.5:free",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "minimax/minimax-m2.5:free",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "minimax/minimax-m2.5:free"
  }
}

Step 4 — Launch Claude Code in that project. Open a terminal in the project folder and run claude. Then run the /model command — you should see the free OpenRouter model listed as the active model. Say hi to confirm it answers.

Step 5 — Verify $0 cost. Head to your OpenRouter usage logs — you'll see your requests landing at $0. Enjoy.