Claude Code: Comprehensive Interactive Tutorial¶
From Beginner to Advanced¶
Last Updated: June 2026 | Covers Claude Code CLI, Desktop App, IDE Extensions, MCP, GitHub, and more.
Table of Contents¶
- What is Claude Code?
- Installation & Initial Setup
- First Run & Basic Navigation
- Settings & Configuration
- CLAUDE.md — Your Project Brain
- Built-in Tools Reference
- Slash Commands & Skills
- Keybindings Customization
- Hooks System
- Memory System
- Plan Mode
- Worktrees (Isolated Git Workspaces)
- GitHub Integration
- MCP — Model Context Protocol
- Connectors & External Tools
- Multi-Agent & Parallel Tasks
- Claude API & Model Selection
- Permission Modes & Security
- IDE Integrations (VS Code & JetBrains)
- Advanced Patterns & Workflows
- Troubleshooting & FAQ
- Quick Reference Cheat Sheet
1. What is Claude Code?¶
Claude Code is Anthropic's official AI coding assistant available as:
| Interface | Best For |
|---|---|
CLI (claude) |
Terminal-native workflows, scripts, CI/CD |
| Desktop App | Mac/Windows GUI with full Claude Code power |
| Web App | claude.ai/code — browser-based access |
| VS Code Extension | Inline AI assistance inside VS Code |
| JetBrains Plugin | IntelliJ, PyCharm, WebStorm, etc. |
Key Capabilities¶
- Read, write, and edit files across your entire project
- Run shell commands, tests, and builds
- Search code with regex (ripgrep-powered)
- Browse the web for up-to-date documentation
- Integrate with GitHub (PRs, issues, commits)
- Connect to external services via MCP servers
- Spawn parallel sub-agents for complex tasks
- Maintain persistent memory across sessions
2. Installation & Initial Setup¶
2.1 CLI Installation¶
# Install via npm (Node.js 18+ required)
npm install -g @anthropic-ai/claude-code
# Verify installation
claude --version
2.2 Authentication¶
# Option A: Interactive login (opens browser)
claude
# Option B: API key via environment variable
export ANTHROPIC_API_KEY="sk-ant-..."
# Option C: Set permanently in your shell profile
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
source ~/.bashrc
2.3 Desktop App¶
- Download from claude.ai — available for Mac and Windows
- Sign in with your Anthropic account
- The app bundles the CLI — you get both the GUI and terminal access
2.4 VS Code Extension¶
- Open VS Code → Extensions (
Ctrl+Shift+X) - Search: Claude Code
- Click Install
- Sign in via the sidebar or
Ctrl+Shift+P→ "Claude Code: Sign In"
2.5 JetBrains Plugin¶
- Open your JetBrains IDE → Settings → Plugins
- Search: Claude Code
- Install and restart the IDE
2.6 Directory Structure Created on First Run¶
~/.claude/
├── settings.json # Global user settings
├── keybindings.json # Custom keyboard shortcuts
├── projects/ # Per-project memory and plans
│ └── <project-hash>/
│ ├── memory/ # Persistent memory files
│ │ ├── MEMORY.md # Memory index
│ │ └── *.md # Individual memory files
│ └── plans/ # Plan mode documents
└── scheduled_tasks.json # Durable cron jobs
3. First Run & Basic Navigation¶
3.1 Starting Claude Code¶
# Start in current directory (recommended — gives full project context)
cd /path/to/your/project
claude
# Start with an immediate prompt
claude "explain what this project does"
# Run a one-shot command (non-interactive)
claude --print "what files are in this directory?"
3.2 The REPL Interface¶
Once inside Claude Code you'll see a prompt like:
Type naturally — Claude Code understands plain English requests alongside technical commands.
3.3 Basic Commands to Know First¶
| What to type | What happens |
|---|---|
/help |
Show all available commands |
/exit or Ctrl+C |
Exit Claude Code |
/clear |
Clear conversation context |
!ls -la |
Run a shell command directly |
Ctrl+R |
Search conversation history |
3.4 Your First Interactions¶
Try these beginner prompts:
> what does this project do?
> list all the TypeScript files in src/
> find where the authentication logic lives
> read the README and summarize it
> what tests exist and how do I run them?
4. Settings & Configuration¶
Settings live in two places — global user settings and project-level overrides.
4.1 Settings File Locations¶
| File | Scope | Priority |
|---|---|---|
~/.claude/settings.json |
Global (all projects) | Lower |
.claude/settings.json |
Project-level | Higher |
.claude/settings.local.json |
Local overrides (gitignored) | Highest |
4.2 Core settings.json Structure¶
{
"model": "claude-opus-4-6",
"permissions": {
"allow": [
"Bash(git *)",
"Bash(npm *)",
"Bash(python *)",
"Read(**)",
"Edit(**)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl * | bash)"
]
},
"hooks": {
"PreToolUse": [...],
"PostToolUse": [...],
"Stop": [...]
},
"env": {
"NODE_ENV": "development"
},
"includeCoAuthored": true,
"cleanupPeriodDays": 30
}
4.3 Model Selection in Settings¶
Available Models (June 2026):
| Model ID | Best For |
|---|---|
claude-opus-4-6 |
Complex reasoning, architecture, advanced tasks |
claude-sonnet-4-6 |
Balanced speed/quality — great default |
claude-haiku-4-5-20251001 |
Fast, lightweight tasks |
4.4 Permission Rules Deep Dive¶
Permissions use glob-style patterns to control what Claude can do without asking:
{
"permissions": {
"allow": [
"Bash(git log *)", // Allow all git log variants
"Bash(git diff *)",
"Bash(git status)",
"Bash(npm test)",
"Bash(npm run *)", // Allow all npm scripts
"Read(**)", // Allow reading any file
"Edit(src/**)", // Allow editing files in src/
"WebSearch(*)" // Allow web searches
],
"deny": [
"Bash(git push --force *)", // Never force push
"Bash(rm -rf *)", // Never recursive delete
"Bash(DROP TABLE *)" // Never drop tables
]
}
}
Permission pattern syntax:
- * — matches anything within a path segment
- ** — matches across path segments (recursive)
- Bash(command pattern) — matches specific shell commands
- Edit(path pattern) — matches file paths for editing
4.5 Efficient Settings for a Developer¶
{
"model": "claude-sonnet-4-6",
"permissions": {
"allow": [
"Bash(git *)",
"Bash(npm *)",
"Bash(node *)",
"Bash(python *)",
"Bash(pytest *)",
"Bash(cargo *)",
"Bash(go *)",
"Bash(make *)",
"Bash(docker *)",
"Read(**)",
"Edit(**)",
"WebSearch(*)",
"WebFetch(*)"
],
"deny": [
"Bash(rm -rf /)",
"Bash(git push --force)"
]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "echo 'File edited: checking for issues...'"
}
]
}
]
},
"includeCoAuthored": true,
"env": {
"EDITOR": "code",
"GIT_EDITOR": "code --wait"
}
}
5. CLAUDE.md — Your Project Brain¶
CLAUDE.md is a special markdown file Claude Code reads automatically when you start a session in a project. It's how you give Claude persistent, project-specific instructions.
5.1 Where to Place CLAUDE.md Files¶
/project-root/
├── CLAUDE.md # Root — always loaded
├── src/
│ └── CLAUDE.md # Loaded when working in src/
├── backend/
│ └── CLAUDE.md # Loaded when working in backend/
└── frontend/
└── CLAUDE.md # Loaded when working in frontend/
Claude loads the CLAUDE.md nearest to the files you're working with, plus the root one.
5.2 What to Put in CLAUDE.md¶
# Project: MyApp
## Overview
This is a React + FastAPI application for managing inventory.
Backend uses PostgreSQL with SQLAlchemy ORM.
## Development Commands
- Start backend: `cd backend && uvicorn main:app --reload`
- Start frontend: `cd frontend && npm run dev`
- Run all tests: `npm test && pytest`
- Lint: `npm run lint && ruff check .`
## Architecture Notes
- API lives in `backend/api/` — all routes use dependency injection
- Database models are in `backend/models/` — always use Alembic for migrations
- Frontend state is managed with Zustand (not Redux)
- Auth uses JWT tokens stored in httpOnly cookies
## Coding Conventions
- Python: Black formatting, type hints required, docstrings for public functions
- TypeScript: strict mode enabled, no `any` types
- Commits: conventional commits format (feat:, fix:, chore:, etc.)
- PRs: always include test coverage for new features
## Things to Avoid
- Never modify `backend/config.py` directly — use environment variables
- Don't use `console.log` in production code — use the logger utility
- Don't bypass TypeScript errors with `@ts-ignore`
## Testing
- Unit tests: pytest with fixtures in `tests/conftest.py`
- E2E tests: Playwright in `e2e/`
- Run a specific test: `pytest tests/test_auth.py -v`
## External Services
- Database: PostgreSQL on port 5432 (see .env.example)
- Redis cache on port 6379
- S3-compatible storage via MinIO in dev
5.3 CLAUDE.md Best Practices¶
- Keep it up to date — outdated instructions confuse Claude
- Be specific — "use Zustand" beats "use modern state management"
- Include run commands — Claude needs to know how to test and build
- Document gotchas — things that aren't obvious from code
- Use it for team conventions — commit the file to share with your team
6. Built-in Tools Reference¶
Claude Code has a rich set of built-in tools. Understanding them helps you write better prompts.
6.1 File System Tools¶
| Tool | What it does | Example prompt |
|---|---|---|
| Read | Read any file | "read the config file" |
| Write | Create or overwrite a file | "create a new component file" |
| Edit | Make targeted edits (efficient, shows diffs) | "fix the bug on line 42" |
| Glob | Find files by pattern | "find all .test.ts files" |
| Grep | Search file contents with regex | "find all TODO comments" |
6.2 Execution Tools¶
| Tool | What it does | Example prompt |
|---|---|---|
| Bash | Run shell commands | "run the tests" |
| NotebookEdit | Edit Jupyter notebooks | "add a cell to the notebook" |
6.3 Research Tools¶
| Tool | What it does | Example prompt |
|---|---|---|
| WebSearch | Search the internet | "look up the React 19 docs" |
| WebFetch | Fetch a specific URL | "read the content at this URL" |
6.4 Orchestration Tools¶
| Tool | What it does | Example prompt |
|---|---|---|
| Agent | Spawn a sub-agent for complex tasks | Automatic — Claude uses this internally |
| Task tools | Track todo lists | Automatic — Claude uses this internally |
6.5 Tool Usage Tips¶
Be specific to get the right tool:
# Vague (Claude must guess)
> look at the auth stuff
# Better (Claude knows to use Grep + Read)
> find where JWT tokens are generated and read that file
# Best (Claude can go straight to work)
> grep for "jwt.sign" in the backend/ directory, then read the file that contains it
7. Slash Commands & Skills¶
7.1 Built-in Slash Commands¶
| Command | Description |
|---|---|
/help |
Show help and all available commands |
/clear |
Clear conversation context (start fresh) |
/exit |
Exit Claude Code |
/fast |
Toggle fast mode (same Opus model, faster output) |
/tasks |
Show background tasks |
/memory |
View/manage memory |
7.2 User-Invocable Skills¶
Skills are extended capabilities invoked with /skill-name:
| Skill | What it does |
|---|---|
/commit |
Create a git commit with an AI-written message |
/review-pr |
Review a pull request |
/simplify |
Review changed code for quality issues and fix them |
/loop [interval] [command] |
Run a command on a recurring schedule |
/update-config |
Configure Claude Code settings interactively |
/keybindings-help |
Help customizing keyboard shortcuts |
/claude-api |
Build/debug Claude API applications |
7.3 Running Shell Commands Inline¶
Prefix any command with ! to run it directly:
7.4 Creating Custom Skills¶
Create a custom skill file at .claude/commands/my-skill.md:
# My Custom Deploy Skill
Run the full deployment pipeline:
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy to staging: `./deploy.sh staging`
4. Verify deployment: `curl https://staging.myapp.com/health`
Report results and any failures.
Then invoke it with /my-skill.
8. Keybindings Customization¶
8.1 Default Keybindings¶
| Key | Action |
|---|---|
Enter |
Submit message |
Shift+Enter |
Add newline |
Ctrl+C |
Cancel / Exit |
Ctrl+R |
Search history |
Up/Down arrows |
Navigate history |
Ctrl+L |
Clear screen |
8.2 Customizing Keybindings¶
Edit ~/.claude/keybindings.json:
[
{
"key": "ctrl+shift+c",
"command": "claude.commit",
"description": "Quick commit"
},
{
"key": "ctrl+shift+t",
"command": "claude.runTests",
"description": "Run tests"
},
{
"key": "ctrl+shift+r",
"command": "claude.reviewChanges",
"description": "Review current changes"
}
]
8.3 Chord Bindings¶
Chord bindings require pressing two key combinations in sequence:
[
{
"key": "ctrl+k ctrl+c",
"command": "claude.commit",
"description": "Chord: commit"
},
{
"key": "ctrl+k ctrl+p",
"command": "claude.createPR",
"description": "Chord: create PR"
}
]
Use the /keybindings-help skill to get guided setup assistance.
9. Hooks System¶
Hooks let you run shell commands automatically at specific points in Claude Code's operation. This is powerful for auditing, validation, and automation.
9.1 Hook Types¶
| Hook | When it fires |
|---|---|
PreToolUse |
Before Claude uses any tool |
PostToolUse |
After Claude uses any tool |
Notification |
When Claude sends a notification |
Stop |
When Claude finishes a response |
9.2 Hook Configuration in settings.json¶
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo \"[AUDIT] About to run bash command: $CLAUDE_TOOL_INPUT\" >> ~/.claude/audit.log"
}
]
}
],
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "cd $CLAUDE_PROJECT_DIR && npm run lint --fix 2>/dev/null || true"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'Task completed' 2>/dev/null || true"
}
]
}
]
}
}
9.3 Hook Environment Variables¶
Hooks receive these environment variables:
| Variable | Value |
|---|---|
CLAUDE_TOOL_NAME |
Name of the tool being used (e.g., "Bash", "Edit") |
CLAUDE_TOOL_INPUT |
JSON input to the tool |
CLAUDE_PROJECT_DIR |
Current project directory |
CLAUDE_SESSION_ID |
Unique session identifier |
9.4 Practical Hook Examples¶
Auto-format on save:
{
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "prettier --write \"$CLAUDE_TOOL_INPUT_PATH\" 2>/dev/null || true"
}
]
}
]
}
Block dangerous commands:
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'DROP TABLE' && exit 1 || exit 0"
}
]
}
]
}
Log all file edits:
{
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "command",
"command": "echo \"$(date): Edited $CLAUDE_TOOL_INPUT\" >> ~/claude-edits.log"
}
]
}
]
}
Use the /update-config skill to configure hooks interactively.
10. Memory System¶
Claude Code has a persistent file-based memory system that survives across sessions.
10.1 Memory Types¶
| Type | Purpose | Example |
|---|---|---|
| user | Who you are, your role, preferences | "I'm a senior Go developer new to React" |
| feedback | How Claude should behave | "Don't add trailing summaries to responses" |
| project | Project context, goals, decisions | "We're migrating from MongoDB to Postgres by Q3" |
| reference | Pointers to external resources | "Bug tracker is in Linear project MYAPP" |
10.2 Memory File Location¶
~/.claude/projects/<project-hash>/memory/
├── MEMORY.md # Index file (always loaded)
├── user_role.md # Your role/background
├── feedback_style.md # Communication preferences
├── project_goals.md # Current project context
└── reference_tools.md # External resource pointers
10.3 Asking Claude to Remember Things¶
> Remember that I prefer concise responses without trailing summaries
> Remember that this project uses pnpm, not npm
> Remember that I'm a backend developer — explain frontend concepts in backend terms
> Remember that our staging environment is at staging.internal.mycompany.com
> Forget what you remembered about the old auth system — we've migrated to OAuth
10.4 Memory Best Practices¶
- Be specific about what to remember — vague memories don't help
- Update stale memories — things change, tell Claude when they do
- Use it for preferences — coding style, communication style, expertise level
- Don't use it for code — code lives in the repo, not memory
11. Plan Mode¶
Plan mode lets Claude explore your codebase and design an implementation approach before writing any code. It's a safety net for complex changes.
11.1 When Plan Mode Activates¶
Claude automatically enters plan mode for: - New feature implementations - Multi-file changes - Tasks with multiple valid approaches - Architectural decisions - Unclear requirements
11.2 Working with Plan Mode¶
> add OAuth2 authentication to the API
# Claude enters plan mode, explores codebase, then presents:
# - What files need to change
# - Proposed approach (e.g., which OAuth library to use)
# - Risks and trade-offs
# - Questions for you to answer
> Yes, proceed with the plan
# Claude exits plan mode and implements
> Use Passport.js instead of jose, and add Google as the only provider
# Claude updates the plan and asks again before implementing
11.3 Plan Mode Tips¶
- Ask questions before approving — this is your chance to redirect
- Request alternatives — "show me a simpler approach" or "what if we used X instead"
- Plans are saved to
.claude/plans/— you can review them - Force plan mode by starting your prompt with "Plan how to..."
12. Worktrees (Isolated Git Workspaces)¶
Worktrees create isolated copies of your repo for parallel work — perfect for experimenting without affecting your main branch.
12.1 Starting a Worktree¶
> start a worktree
# Claude creates a new git worktree in .claude/worktrees/<name>/
# Claude switches the session to work in that worktree
> start a worktree named oauth-experiment
# Named worktree
12.2 Working in a Worktree¶
# Inside a worktree session, all your work is isolated:
> refactor the auth module to use JWT
# Changes only affect the worktree, not your main branch
> exit the worktree and keep my changes
# Exits worktree, keeps the branch for later
> exit the worktree and discard everything
# Exits and deletes the worktree — clean slate
12.3 Worktree Use Cases¶
- Risky refactors — experiment without fear
- Parallel features — work on multiple features simultaneously across sessions
- Reproducing bugs — isolate the bug-reproduction environment
- Code review — check out a PR branch in a worktree without disturbing your work
13. GitHub Integration¶
Claude Code integrates deeply with GitHub via the gh CLI tool.
13.1 Prerequisites¶
# Install GitHub CLI
# macOS
brew install gh
# Windows
winget install GitHub.cli
# Linux
sudo apt install gh
# Authenticate
gh auth login
13.2 Common GitHub Workflows¶
Create a PR:
> create a pull request for these changes
# Claude will:
# 1. Check git status and diff
# 2. Review all commits since branching
# 3. Write a PR title and description
# 4. Push the branch
# 5. Open the PR with gh pr create
Review an existing PR:
> review PR #142
> /review-pr 142
# Claude fetches the PR, reads all changed files, and provides a thorough review
Commit with a good message:
> /commit
# Claude:
# 1. Runs git status and git diff
# 2. Reads recent commit messages to match your style
# 3. Writes a meaningful commit message
# 4. Creates the commit
Work with Issues:
> list open issues labeled "bug"
> create an issue for the authentication timeout bug I just found
> close issue #89 — we fixed it in the last commit
13.3 GitHub Actions Integration¶
> look at the failing CI run and tell me what's wrong
# Claude fetches the workflow run output via gh run view
> add a GitHub Actions workflow for running tests on every PR
# Claude creates .github/workflows/test.yml
> fix the flaky test that's causing CI failures
# Claude reads the test, analyzes the failure pattern, and fixes it
13.4 Useful gh Commands to Know¶
# These work directly via ! prefix in Claude Code:
!gh pr list # List open PRs
!gh pr view 142 # View PR details
!gh pr checkout 142 # Check out a PR branch
!gh run list # List CI runs
!gh run view <run-id> # View CI run output
!gh issue list --label bug # List bug issues
!gh release create v1.2.3 # Create a release
14. MCP — Model Context Protocol¶
MCP (Model Context Protocol) is a standard protocol that lets Claude connect to external data sources, tools, and services. Think of MCP servers as plugins that extend what Claude can access.
14.1 What MCP Servers Do¶
MCP servers give Claude access to: - Databases — query Postgres, MySQL, SQLite directly - APIs — Slack, Jira, Linear, Notion, etc. - File systems — remote files, cloud storage - Custom tools — anything your team builds
14.2 Configuring MCP Servers¶
Add MCP server configuration to settings.json or .claude/settings.json:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
"description": "Local development database"
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"slack": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-slack"],
"env": {
"SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
"SLACK_TEAM_ID": "T0123456"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
"description": "Extended filesystem access"
}
}
}
14.3 Popular MCP Servers¶
| MCP Server | npm Package | What it enables |
|---|---|---|
| PostgreSQL | @modelcontextprotocol/server-postgres |
SQL queries on Postgres |
| SQLite | @modelcontextprotocol/server-sqlite |
SQLite database access |
| GitHub | @modelcontextprotocol/server-github |
Advanced GitHub operations |
| Filesystem | @modelcontextprotocol/server-filesystem |
Extended file access |
| Brave Search | @modelcontextprotocol/server-brave-search |
Web search via Brave |
| Slack | @modelcontextprotocol/server-slack |
Read/post Slack messages |
| Puppeteer | @modelcontextprotocol/server-puppeteer |
Browser automation |
| Memory | @modelcontextprotocol/server-memory |
Persistent knowledge graph |
14.4 Using MCP Tools in Conversation¶
Once an MCP server is configured, Claude uses its tools automatically:
# With postgres MCP configured:
> show me the 10 most recent users who signed up
# Claude queries: SELECT * FROM users ORDER BY created_at DESC LIMIT 10;
# With Slack MCP configured:
> what did the #engineering channel discuss today?
# Claude reads recent Slack messages
# With GitHub MCP configured:
> list all open PRs in the myorg/myrepo repository
# Claude uses the GitHub MCP to fetch PRs
14.5 Building a Custom MCP Server¶
// minimal-mcp-server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
const server = new Server(
{ name: "my-custom-server", version: "1.0.0" },
{ capabilities: { tools: {} } }
);
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: "get_deployment_status",
description: "Check the deployment status of a service",
inputSchema: {
type: "object",
properties: {
service: { type: "string", description: "Service name" }
},
required: ["service"]
}
}
]
}));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === "get_deployment_status") {
const { service } = request.params.arguments as { service: string };
// Your custom logic here
const status = await checkMyDeploymentSystem(service);
return { content: [{ type: "text", text: JSON.stringify(status) }] };
}
throw new Error("Unknown tool");
});
const transport = new StdioServerTransport();
await server.connect(transport);
Register it in settings.json:
{
"mcpServers": {
"my-deploy-tool": {
"command": "node",
"args": ["path/to/minimal-mcp-server.js"]
}
}
}
15. Connectors & External Tools¶
Beyond MCP, Claude Code connects to external systems through several mechanisms.
15.1 Shell Commands as Connectors¶
Any CLI tool becomes a connector via Bash:
> check the current Kubernetes pod status
# Claude runs: kubectl get pods --all-namespaces
> deploy to staging
# Claude runs your deploy script
> query the database for active sessions
# Claude runs: psql $DATABASE_URL -c "SELECT count(*) FROM sessions WHERE active=true"
15.2 Environment Variables for Secrets¶
Never hardcode secrets. Use environment variables:
# In your shell profile (~/.bashrc or ~/.zshrc):
export DATABASE_URL="postgresql://..."
export SLACK_WEBHOOK_URL="https://hooks.slack.com/..."
export JIRA_API_TOKEN="..."
Reference them in settings.json:
15.3 Docker & Container Integration¶
> build and run the Docker container for local testing
> check the logs from the auth service container
> run the database migration inside the postgres container
> inspect the network between the API and database containers
15.4 Cloud Provider CLIs¶
# AWS — Claude can use awscli
> list all running EC2 instances in us-east-1
> check the CloudWatch logs for the API lambda
# Azure — Claude can use az cli
> show the resource group for the production environment
# GCP — Claude can use gcloud (requires interactive login first)
# ! gcloud auth login
> list all Cloud Run services in the project
16. Multi-Agent & Parallel Tasks¶
For complex tasks, Claude Code can spawn multiple sub-agents working in parallel.
16.1 How Multi-Agent Works¶
Claude automatically uses sub-agents for: - Open-ended research that spans many files - Tasks that need isolated exploration - Parallel code generation across multiple modules - Background monitoring tasks
16.2 Spawning Work in Background¶
> in the background, run the full test suite and tell me when it's done
# Claude starts a background Bash task and continues being responsive
> keep checking the CI status every 5 minutes until it passes
# Use /loop for this:
> /loop 5m check the latest CI run status and report results
16.3 The /loop Skill¶
/loop runs a prompt or command on a recurring schedule:
# Basic usage
> /loop 10m check if any new error logs appeared
# With a slash command
> /loop 5m /review-pr
# Check deployment
> /loop 2m check if the deployment to staging completed successfully
# Loop self-terminates after 7 days
16.4 Parallel Agent Patterns¶
> analyze both the frontend and backend performance simultaneously and give me a combined report
# Claude spawns parallel agents to analyze both, merges the results
> review all the changed files in this PR in parallel
# Claude spawns one agent per file for speed
16.5 Scheduled Tasks (Cron)¶
# Session-only (disappears when Claude Code exits):
> remind me in 30 minutes to push my changes
# Durable (persists across sessions, 7-day max):
> every day at 9am, summarize any new GitHub issues and PRs
17. Claude API & Model Selection¶
17.1 API Key Management¶
# Set your API key
export ANTHROPIC_API_KEY="sk-ant-api03-..."
# Verify it works
claude --print "hello"
17.2 Choosing the Right Model¶
| Task | Recommended Model | Why |
|---|---|---|
| Complex architecture decisions | claude-opus-4-6 |
Best reasoning |
| Day-to-day coding | claude-sonnet-4-6 |
Best balance |
| Quick lookups, simple edits | claude-haiku-4-5-20251001 |
Fastest, cheapest |
| Code review | claude-opus-4-6 |
Thoroughness |
| Generating boilerplate | claude-haiku-4-5-20251001 |
Speed |
17.3 Fast Mode¶
Fast mode uses the same Opus model with optimized output:
17.4 Building Applications with the Claude API¶
Use the /claude-api skill when building Claude-powered applications:
Example API usage with prompt caching:
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: process.env.ANTHROPIC_API_KEY,
});
// Always use prompt caching for large system prompts
const response = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 4096,
system: [
{
type: "text",
text: "You are a helpful coding assistant...",
cache_control: { type: "ephemeral" } // Cache this system prompt
}
],
messages: [
{ role: "user", content: "Explain how to implement rate limiting" }
]
});
console.log(response.content[0].text);
17.5 Model IDs Quick Reference¶
claude-opus-4-6 # Most capable
claude-sonnet-4-6 # Best for most tasks
claude-haiku-4-5-20251001 # Fastest/cheapest
18. Permission Modes & Security¶
18.1 The Permission System Explained¶
Every tool call goes through a permission check:
Permission decision flow:
1. Check deny list — if matched, BLOCK
2. Check allow list — if matched, ALLOW silently
3. If neither — PROMPT the user to approve or deny
18.2 Interactive Permission Approvals¶
When Claude encounters a command not in your allow list:
Claude wants to run: git push origin main
[A]llow once | [D]eny | [L] Allow for this session | [P] Allow permanently
18.3 Security Best Practices¶
DO:
{
"permissions": {
"allow": [
"Bash(git log *)",
"Bash(git diff *)",
"Bash(git status)",
"Bash(npm test)",
"Read(**)"
]
}
}
DON'T (too permissive):
18.4 Audit Logging with Hooks¶
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) BASH: $CLAUDE_TOOL_INPUT\" >> ~/.claude/audit.log"
}
]
}
]
}
}
18.5 Project-Level vs Global Permissions¶
# Global settings (~/.claude/settings.json):
# - Safe defaults for all projects
# - Minimal allow list
# Project settings (.claude/settings.json):
# - Project-specific tools
# - Committed to the repo — shared with team
# Local settings (.claude/settings.local.json):
# - Your personal overrides
# - Add to .gitignore — never commit this
19. IDE Integrations (VS Code & JetBrains)¶
19.1 VS Code Extension Features¶
- Inline chat — select code, press shortcut, ask a question
- Ghost text — AI-powered completions as you type
- Panel chat — full Claude Code experience in a sidebar
- File references — drag files into the chat
- Terminal integration — run Claude commands from the terminal panel
Key VS Code shortcuts:
| Shortcut | Action |
|---|---|
| Ctrl+Shift+I | Open Claude Code panel |
| Ctrl+I | Inline edit selected code |
| Ctrl+Shift+L | Ask about selected code |
19.2 JetBrains Plugin Features¶
- Same core capabilities as VS Code
- Works in: IntelliJ IDEA, PyCharm, WebStorm, GoLand, Rider, CLion
- Project-aware — understands your IDE's project structure
- Refactoring support — works with IDE refactoring tools
19.3 IDE vs CLI — When to Use Which¶
| Scenario | Use |
|---|---|
| Writing code in a specific file | IDE extension |
| Complex multi-file refactors | CLI |
| Understanding a codebase | CLI |
| Quick edits, simple questions | IDE extension |
| Git operations, CI/CD | CLI |
| Automation scripts | CLI |
| PR reviews | CLI |
20. Advanced Patterns & Workflows¶
20.1 The Exploration-Plan-Execute Pattern¶
For complex tasks, break into phases:
Phase 1 - Explore:
> how is authentication currently implemented? map out all the files involved
Phase 2 - Plan:
> Plan how to migrate this auth system from JWT to OAuth2 using Auth0
Phase 3 - Execute (after reviewing and approving the plan):
> proceed with the plan
Phase 4 - Verify:
> run all the auth tests and verify nothing is broken
> create a PR for these changes
20.2 Context Management¶
Claude Code has a context window — manage it:
> /clear # Clear context when changing topics entirely
> /compact # Summarize and compress context (if available)
# Start with context already loaded:
claude "fix the failing test in auth.test.ts"
Tips: - Clear context between unrelated tasks - Reference specific files rather than asking Claude to explore broadly - Use sub-agents for large explorations (they don't consume your context)
20.3 The "Rubber Duck" Pattern¶
Use Claude Code to think through problems:
> I need to implement rate limiting for our API. I'm considering two approaches:
1. Redis-based sliding window
2. In-memory fixed window per instance
We have 5 API servers. Which would you recommend and why?
> Now plan the implementation of option 1 using our existing Redis connection
20.4 Code Review Workflow¶
# Before pushing a PR:
> review my changes since the last commit — look for bugs, security issues, and style problems
> /simplify
> /commit
# After pushing:
> create a PR for these changes and request review from the @backend-team
20.5 Test-Driven Development with Claude¶
> write failing tests for a user authentication service that doesn't exist yet
> now implement the minimum code to make those tests pass
> refactor the implementation for clarity without breaking any tests
> add edge case tests I might have missed
20.6 Debugging Production Issues¶
> we're getting this error in production: [paste error/stack trace]
> reproduce this locally and find the root cause
> fix it and add a regression test
> write a postmortem summary of what happened and how we fixed it
20.7 Documentation Generation¶
> generate API documentation for all the endpoints in routes/
> update the README with the current setup instructions based on what you see in the code
> create a changelog entry for the changes in this PR
20.8 Database Operations (with MCP)¶
# With PostgreSQL MCP configured:
> show me the schema for the users table
> find any N+1 query problems in the API code
> write a migration to add an index on users.email
> explain the query plan for this slow query: SELECT ...
21. Troubleshooting & FAQ¶
21.1 Common Issues¶
"Claude is not allowed to run this command"
- Add the command to your permissions.allow list in settings.json
- Or approve it interactively when prompted
"Context window is getting large"
- Use /clear to start fresh
- Be more specific in your requests to avoid broad exploration
- Use sub-agents for research-heavy tasks
"Claude keeps repeating the same mistake" - Tell Claude explicitly: "Remember that you should X, not Y" - Check if a CLAUDE.md instruction is contradicting you - Use memory: "remember for future sessions that..."
"MCP server isn't connecting"
# Test your MCP server manually:
npx @modelcontextprotocol/server-postgres postgresql://localhost/mydb
"GitHub operations failing"
"Hooks aren't firing"
- Check the matcher field — it's case-sensitive
- Verify the command runs correctly in your shell manually
- Check the CLAUDE_TOOL_NAME value matches what you expect
21.2 Performance Tips¶
| Tip | Impact |
|---|---|
Use claude-haiku for simple tasks |
Faster, cheaper |
| Pre-approve common commands in settings | No approval delays |
| Use CLAUDE.md to avoid re-explaining context | Fewer round-trips |
| Reference specific files instead of asking Claude to search | More focused responses |
Use /clear between unrelated tasks |
Fresher context, better focus |
| Enable prompt caching in API applications | Significant cost savings |
21.3 Best Practices Summary¶
DO: - Write a good CLAUDE.md before starting a project - Configure sensible permissions upfront - Use plan mode for significant changes - Commit regularly and use meaningful commit messages - Run tests after Claude makes changes - Keep memory updated with current project state
DON'T:
- Give Claude overly broad Bash(*) permissions
- Let Claude make database schema changes without review
- Trust Claude's output without running tests
- Let context grow stale — use /clear between topics
- Store secrets in settings.json — use environment variables
22. Quick Reference Cheat Sheet¶
Essential Commands¶
claude # Start Claude Code in current directory
claude "fix the bug in auth.py" # Start with an immediate task
claude --print "explain this" # Non-interactive, print output only
/help # Show all commands
/clear # Clear conversation context
/fast # Toggle fast mode
/commit # AI-assisted git commit
/review-pr <number> # Review a GitHub PR
/loop <interval> <command> # Recurring task
!<command> # Run shell command directly
Key Files¶
~/.claude/settings.json # Global settings
~/.claude/keybindings.json # Keyboard shortcuts
.claude/settings.json # Project settings (commit this)
.claude/settings.local.json # Local overrides (gitignore this)
CLAUDE.md # Project instructions for Claude
.claude/commands/*.md # Custom skills
Settings.json Template¶
{
"model": "claude-sonnet-4-6",
"permissions": {
"allow": ["Bash(git *)", "Bash(npm *)", "Read(**)", "Edit(**)", "WebSearch(*)"],
"deny": ["Bash(rm -rf *)", "Bash(git push --force)"]
},
"mcpServers": {},
"hooks": {},
"includeCoAuthored": true
}
MCP Servers Quick Setup¶
# Add to settings.json mcpServers:
# PostgreSQL: "@modelcontextprotocol/server-postgres"
# GitHub: "@modelcontextprotocol/server-github"
# Filesystem: "@modelcontextprotocol/server-filesystem"
# SQLite: "@modelcontextprotocol/server-sqlite"
# Slack: "@modelcontextprotocol/server-slack"
GitHub Workflow¶
# Complete PR workflow:
!git checkout -b feature/my-feature
# ... make changes ...
/commit
# Claude writes commit message and commits
> create a PR for these changes with a description of what I built
# Claude creates the PR via gh CLI
Models Quick Reference¶
claude-opus-4-6 → Complex tasks, architecture
claude-sonnet-4-6 → Daily coding (recommended default)
claude-haiku-4-5-20251001 → Fast, lightweight tasks
What's Next?¶
Now that you have a solid foundation, explore these areas:
- Build a custom MCP server for your internal tools
- Set up team-wide CLAUDE.md to standardize AI assistance across your org
- Integrate Claude Code into CI/CD — automated PR reviews, test generation
- Explore the Claude API for building your own AI-powered tools with
/claude-api - Create a custom skills library for your team's common workflows
Tutorial written for Claude Code as of June 2026. Powered by Claude Sonnet 4.6. Report issues or contribute: anthropics/claude-code