Know Your Claude — The Complete Guide

A developer's guide to understanding Anthropic, the Claude model family, Claude Code CLI, MCP, Agents, Skills, Tokens, and how to get the most out of the AI pair-programmer living in your terminal.

1. Anthropic — The Name & A Brief History

Why "Anthropic"?

The name "Anthropic" comes from the Greek word anthropos (ἄνθρωπος), meaning "human being". It reflects the company's core focus: building AI that is centered on human values, human safety, and human benefit. The word also relates to anthropology — the study of human beings and human societies.

In short: the name signals that this is an AI company that puts people first.

Timeline

2021: Anthropic was founded by Dario Amodei (CEO), Daniela Amodei (President), and seven other former OpenAI researchers. The company's mission: AI safety research and the responsible development of AI that is safe, beneficial, and understandable.
2022: Anthropic published research on Constitutional AI (CAI) — a technique that trains AI using a written set of principles instead of purely human feedback, making the training process more transparent and consistent.
2023: Claude 1 and Claude 2 were publicly released. Amazon Web Services invested $4 billion, making AWS a strategic cloud partner.
2024: Claude 3 (Haiku, Sonnet, Opus) launched — Opus surpassed GPT-4 on most major benchmarks. Anthropic also open-sourced the Model Context Protocol (MCP).
2025: Claude Code launched as a terminal-native agentic coding assistant. Claude 4 models (Sonnet 4, Opus 4) followed with extended thinking and 1M token context windows.

Anthropic is one of the only major AI labs to publish detailed model safety cards and open policy frameworks — treating safety not as a marketing checkbox but as a research discipline.

2. The Name "Claude" — Where Does It Come From?

Claude is named after Claude Shannon (1916–2001), the American mathematician and electrical engineer who founded Information Theory.

Shannon's 1948 paper "A Mathematical Theory of Communication" laid the foundation for every modern digital communication system — the internet, mobile phones, data compression, and yes, the statistical foundations that modern language models are built upon.

By naming their AI "Claude", Anthropic pays tribute to the intellectual lineage of the entire field. Shannon's work on how information is represented, transmitted, and compressed is directly upstream of how large language models process and generate text.

Fun fact

Shannon also invented the concept of a "bit" (binary digit) as the fundamental unit of information — the same concept that eventually led to tokens.

3. The Claude Model Tiers — Haiku, Sonnet & Opus

Claude models are organized into three tiers. Each name was deliberately chosen from poetry and music — because AI models at their best are both precise and expressive, structured and creative. Just like poetry.

🌸 Haiku — Speed & Efficiency

A Haiku is a traditional form of Japanese poetry consisting of exactly 17 syllables arranged in three lines (5-7-5). It is short, fast, and carefully structured. No word is wasted.

This perfectly describes the Haiku model tier:

Fastest response time
Lowest cost
Small and precise — ideal for quick tasks, subagents, high-volume automation

Poetry parallel: A haiku says exactly what needs to be said, nothing more. The model follows the same principle.

Example Haiku:

An old silent pond...
A frog jumps into the pond.
Splash! Silence again.
— Matsuo Bashō

🎼 Sonnet — Balance & Craft

A Sonnet is a 14-line poem, typically in iambic pentameter, with a defined rhyme scheme — most famously associated with Shakespeare. It is more complex than a Haiku, more structured, and covers deeper themes — but is still tightly constrained.

This describes the Sonnet tier:

Balanced performance — not the fastest, not the most powerful, but the best all-rounder
The everyday workhorse for coding, writing, and analysis
Enough depth to handle complexity, enough speed to keep your workflow moving

Poetry parallel: A sonnet handles nuanced emotions and complex arguments within a disciplined structure. The model does the same with complex code and logic.

🎭 Opus — Power & Depth

An Opus (Latin: "work") refers to a major musical composition — a symphony, concerto, or large-scale work of profound depth and complexity. In classical music, an Opus is the serious, ambitious masterwork. Think Beethoven's Opus 131 or Mozart's final symphonies.

This describes the Opus tier:

The most powerful and intelligent model
Used for complex reasoning, architecture, multi-step planning
Takes longer and costs more — but produces the most thoughtful work

Music parallel: You don't play an Opus at a casual gathering. You bring it out for the most important performance.

Model Summary Table

Model	Named After	Character	Best For	Cost
Haiku	Japanese 17-syllable poem	Fast, precise, minimal	Quick tasks, subagents	💰
Sonnet	14-line structured poem	Balanced, versatile	Daily coding, writing	💰💰
Opus	Major musical composition	Deep, powerful, thorough	Architecture, hard problems	💰💰💰

4. Understanding Tokens — Simply Explained

Before we go further, let's talk about tokens — because everything in AI is measured in them.

What Is a Token?

Think of a token as a small chunk of text. Not exactly a word, not exactly a letter — something in between.

Real-world analogy

Imagine you're sending a telegram and you pay per word. Now imagine the billing system splits words further — short common words like "the", "is", "at" cost 1 unit each, but longer or rare words like "anthropomorphic" might cost 4–5 units. That billing unit is roughly what a token is.

The Rule of Thumb

~4 characters = 1 token OR ~¾ of a word = 1 token

In practice:

"Hello" = 1 token
"Hello, how are you?" = 5 tokens
"I am a software engineer" = 6 tokens
"Refactor this function to use async/await" ≈ 9 tokens
A full page of text (500 words) ≈ ~650–750 tokens
This entire article ≈ ~8,000–10,000 tokens

A Practical Token Example

Let's say you ask Claude:

"What is 2 + 2?"

That question is ~6 tokens. Claude's answer "2 + 2 = 4." is ~7 tokens. Total: ~13 tokens used. Very cheap.

Now compare with:

"Read this 500-line file and refactor it to follow SOLID principles, add JSDoc comments, and write unit tests."

That question alone is ~25 tokens. But now Claude has to read the 500-line file (maybe 3,000–5,000 tokens), reason about it, and write the refactored version + tests (another 3,000–6,000 tokens output). Total: easily 10,000–15,000 tokens.

Tokens = Input + Output

Every interaction has two parts that are both counted and billed:

Your message (input tokens)  +  Claude's reply (output tokens)  =  Total tokens used

Interaction	Input Tokens	Output Tokens	Total
"Hi Claude!" / "Hello!"	~3	~3	~6
Simple question / Short answer	~20	~50	~70
Read 1 file / Explain it	~1,500	~400	~1,900
Read entire codebase / Full plan	~50,000	~5,000	~55,000
Full agent session (write feature)	~100,000	~30,000	~130,000

The Context Window = Your Token Budget Per Session

Think of the context window like a whiteboard in a meeting room. Everything written on the board — your questions, Claude's answers, the files it read, the code it wrote — takes up space. When the whiteboard is full, something has to be erased before new stuff can fit.

Claude Sonnet 4.6 supports up to 1,000,000 tokens — that's like fitting an entire large novel and a large codebase onto the whiteboard at the same time.

Context Window sizes:
- Claude Haiku:  200,000 tokens  ≈ 150,000 words  ≈ ~500 pages of code
- Claude Sonnet: 200,000–1,000,000 tokens (1M in beta)
- Claude Opus:   200,000 tokens

How Many Messages Per Context Window?

This varies by message length, but as a rough guide for Sonnet (200K window):

Conversation Type	Approx. Message Count Before Window Fills
Short Q&A (few words each)	~300–500 messages
Medium coding questions	~50–100 messages
Heavy file reading + writing	~10–20 exchanges
Agent session with many files	~5–15 task cycles

Pro-tip: When a session gets long, use /compact to summarize history and free up window space, or /clear to start fresh between unrelated tasks.

API Pricing (Rough Guide)

When using Claude via the API (e.g., in Claude Code), you pay per 1 million tokens (MTok):

Model	Input (per MTok)	Output (per MTok)
Haiku 4.5	~$0.80	~$4.00
Sonnet 4.6	~$3.00	~$15.00
Opus 4.6	~$15.00	~$75.00

Claude.ai Pro/Max plans include a monthly message allowance — you don't pay per token directly, but each plan has usage limits that reset monthly.

5. Installing Claude Code

Claude Code works on macOS, Linux, and Windows (via WSL). Here's how to get set up on each platform.

macOS — Recommended Method

The fastest way is the official install script — it handles Node.js and Claude Code in one step:

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

This script installs Node.js (via nvm) if it's not already present, then installs Claude Code globally. After installation:

claude --version   # Verify installation
claude doctor      # Check all dependencies and auth

If you prefer to manage Node yourself:

# Step 1: Install Node.js v20+ via Homebrew
brew install node

# Step 2: Verify version (must be >= 20)
node --version

# Step 3: Install Claude Code
npm install -g @anthropic-ai/claude-code

# Step 4: Verify
claude --version
claude doctor

Linux (Ubuntu / Debian)

The one-liner script works here too:

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

Or manually:

# Step 1: Install Node.js v20+ via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify Node version (must be >= 20)
node --version

# Step 2: Install Claude Code
npm install -g @anthropic-ai/claude-code

# Step 3: Verify
claude --version
claude doctor

Windows — via WSL (Windows Subsystem for Linux)

Claude Code does not run natively on Windows — it requires WSL (Windows Subsystem for Linux). This is because Claude Code uses Unix-style shell commands and file permissions internally.

# Step 1: Enable WSL (run in PowerShell as Administrator)
wsl --install

# Restart your machine, then open Ubuntu terminal from Start menu

# Step 2: Inside WSL Ubuntu terminal, run the install script
curl -fsSL https://claude.ai/install.sh | bash

# Or manually:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

# Step 3: Verify
claude --version
claude doctor

Important for WSL users: Always run Claude Code from inside the WSL terminal (Ubuntu), not from PowerShell or CMD. Your project files should ideally live inside the WSL filesystem (~/projects/) rather than on the Windows mount (/mnt/c/...) for best performance.

First-Time Authentication

claude        # Launch Claude Code for the first time

On first launch, Claude Code opens a browser window to authenticate with your Anthropic account. After login, your credentials are saved locally.

Updating Claude Code

npm update -g @anthropic-ai/claude-code   # Update to latest
claude --version                           # Confirm version

6. Claude Code — The Terminal-Native Agent

Claude Code is not a chat interface that happens to know about programming — it is a full agentic system that reads your codebase, executes commands, modifies files, manages git workflows, connects to external services, and delegates tasks to sub-agents.

Launching Claude Code

claude                          # Interactive REPL (conversational mode)
claude -p "explain src/auth.ts" # One-shot print mode (no session)
claude -c -p "add unit tests"   # Continue last session headlessly
claude -r <session-id> "..."    # Resume a specific session
claude --max-turns 5 -p "..."   # Cap agentic loops (great for CI)
claude --output-format json     # JSON output for scripting

7. Keyboard Shortcuts

Key	What It Does
`Ctrl+C`	Cancel current generation
`Ctrl+D`	Quit the session
`Ctrl+L`	Clear screen (history is preserved)
`↑ / ↓`	Cycle through command history
`Esc Esc`	Edit the last prompt
`Shift+Tab`	Toggle permission modes: Normal → Auto-Accept → Plan Mode
`\ + Enter`	Drop to multi-line input (works everywhere)
`Shift+Enter`	Multi-line input (after running `/terminal-setup`)

Pro-tip: Shift+Tab is the fastest way to enter Plan Mode — Claude reads your codebase and produces a plan without touching any files.

8. Slash Commands

Slash commands are typed inside an active Claude Code session. They give you access to built-in superpowers.

Session & Context Management

Command	What It Does
`/init`	Auto-generate a `CLAUDE.md` summary of the repo — run this in every new project
`/clear`	Wipe chat history; start fresh (use between distinct tasks)
`/compact`	Compress a long session to save context window tokens
`/context`	Show current context window usage and any excluded skills
`/cost`	Show token spend for the current session
`/memory`	Open and edit your `CLAUDE.md` memory files

Configuration & Model

Command	What It Does
`/config`	Open settings TUI (permissions, model, hooks)
`/model`	Switch models mid-session (`Sonnet`, `Opus`, `Haiku`)
`/permissions`	Audit what Claude is allowed to read and write
`/keybindings`	Create or edit `~/.claude/keybindings.json`

Tools & Integrations

Command	What It Does
`/mcp`	View connected MCP server status
`/ide`	Integrate with VS Code, Cursor, or JetBrains
`/review`	Run a full code review (bugs, style, performance)
`/install-github-app`	Enable Claude to auto-review pull requests
`/help`	List all available commands, including your custom ones

Custom Slash Commands

You can define your own slash commands as Markdown files:

# Project-specific command (only works inside the project)
mkdir -p .claude/commands
echo "Analyze this code for performance issues:" > .claude/commands/optimize.md

# Global command (works everywhere)
mkdir -p ~/.claude/commands
echo "Review this code for security vulnerabilities:" > ~/.claude/commands/security.md

# Parameterized command using $ARGUMENTS
echo 'Fix issue #$ARGUMENTS following our coding standards' > .claude/commands/fix-issue.md

Usage in session:

> /optimize
> /fix-issue 123

Advanced command with frontmatter and shell context injection:

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a smart git commit with full context
---

## Context
- Current status: !`git status`
- Current diff: !`git diff HEAD`
- Current branch: !`git branch --show-current`

Write a commit message following Conventional Commits format.

9. Operating Modes

Normal Mode (Default)

Claude asks for permission before executing each tool call. Ideal when you want to review every action before it's taken.

Auto-Accept Mode

Claude proceeds without asking permission. Good for well-defined tasks where you trust the scope. Toggle with Shift+Tab.

Plan Mode

Claude enters read-only mode — it analyses the codebase and produces a detailed plan without touching any files. Once you approve the plan, you can switch to Auto-Accept and let it execute.

Toggle: Shift+Tab (cycles through Normal → Auto-Accept → Plan)

Headless / Print Mode

Run Claude as a one-shot command for scripting and CI:

claude -p "list all type errors in the project" --output-format json
echo "fix lint errors" | claude --pipe

`--dangerously-skip-permissions`

Bypasses all permission prompts — similar to "yolo mode" in Cursor. Use with caution, ideally inside Docker containers in CI environments.

10. CLAUDE.md — Project Memory

CLAUDE.md is the single most powerful customization you can make. Claude reads it at the start of every session, giving it persistent project context.

File Hierarchy

~/.claude/CLAUDE.md           # Global: applies to all projects
./CLAUDE.md                   # Project root: shared with team via git
./.claude/CLAUDE.md           # Project-local: team config
~/.claude/settings.local.json # Personal overrides (gitignore this)

Recommended CLAUDE.md Structure

# Project: My App

## Stack
- Frontend: React 18, TypeScript, Tailwind
- Backend: Node.js, Express, PostgreSQL
- Testing: Vitest, Playwright

## Key Commands
- `npm run dev` — Start dev server
- `npm run test` — Run tests
- `npm run lint` — Lint and format

## Conventions
- Use 2-space indentation
- Prefer named exports over default exports
- Write tests for all public functions
- Use conventional commits: feat/fix/chore/docs

## Important Paths
- API routes: `src/routes/`
- Components: `src/components/`
- Database migrations: `db/migrations/`

Quick add: Type # <instruction> in any prompt to instantly append a rule to your CLAUDE.md. Example: # Always use single quotes in JavaScript.

11. MCP — Model Context Protocol

MCP is an open-source standard developed by Anthropic that lets Claude Code connect to external tools, data sources, and APIs through a standardized protocol. Think of it as a universal USB-C adapter — instead of every tool needing a custom integration, MCP defines a single plug that works with everything.

Without MCP vs With MCP

Without MCP	With MCP
Read files, run bash commands	Query your production database
—	Create Jira tickets from natural language
—	Review GitHub PRs without leaving the terminal
—	Check Sentry errors and cross-reference with code
—	Pull Figma designs and implement them in code

MCP Architecture

Adding MCP Servers

# HTTP transport (recommended for cloud services)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# With authentication header
claude mcp add --transport http my-api https://api.example.com/mcp \
  --header "Authorization: Bearer $MY_TOKEN"

# stdio transport (local processes)
claude mcp add --transport stdio filesystem npx -y @modelcontextprotocol/server-filesystem

# Check connected servers
/mcp

MCP Configuration File (`.mcp.json`)

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_TOKEN"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

Popular MCP Servers

Server	What It Enables
GitHub	Read PRs, create issues, review code, push branches
Slack	Post messages, search channels, read threads
Jira / Linear	Read tickets, update status, create tasks
PostgreSQL	Query databases with natural language
Figma	Read designs and implement them in code
Sentry	Look up errors and correlate with code
Notion	Read and write docs and databases
Playwright	Browser automation and testing

12. Skills

Skills are modular, auto-discovered capabilities that extend what Claude can do. Unlike slash commands (which you invoke manually), Skills are invoked by Claude automatically when the task description matches.

Creating a Skill

mkdir -p .claude/skills/code-review
touch .claude/skills/code-review/SKILL.md

Example — Code Review Skill:

---
name: code-review
description: Performs a thorough code review. Use when the user asks to review,
  audit, or check code for issues.
---

# Code Review Skill

When performing a code review, always check for:

1. **Security vulnerabilities** — SQL injection, XSS, unvalidated inputs
2. **Performance issues** — N+1 queries, memory leaks, unnecessary re-renders
3. **Code smell** — duplicated logic, deeply nested conditions, unclear naming
4. **Test coverage** — are edge cases covered?
5. **Documentation** — are public APIs documented?

Format output as a structured report with severity:
🔴 Critical, 🟡 Warning, 🟢 Suggestion.

Skills vs Slash Commands vs CLAUDE.md

Feature	CLAUDE.md	Slash Commands	Skills
Invocation	Always loaded	Manual (`/command`)	Auto or manual
Scope	Project conventions	Specific prompts	Reusable workflows
Supporting Files	❌	❌	✅ (scripts, templates)
Works on Claude.ai	❌	❌	✅
Best For	Standards, paths	Quick macros	Complex procedures

13. Subagents — Delegating Context-Hungry Work

Subagents are specialized Claude instances with their own isolated context windows. They do focused work and return only a summary to the main session — preventing the main context from bloating.

Why Use Subagents

Main Session (200K context)
  └── Delegate: "Explore all API routes and summarize"
        └── Subagent (clean 200K context)
              ├── Reads 50 files
              ├── Analyzes patterns
              └── Returns 2-paragraph summary  ←  only this comes back

Defining a Subagent

Subagents live in .claude/agents/ as Markdown files with frontmatter:

---
name: explorer
description: Use to explore a codebase, map out file structure, and return a concise summary
model: haiku
color: blue
---

You are a codebase explorer. Your job is to read files and return a
concise, structured summary of what you find. Do not write or modify files.
Focus on: folder structure, key modules, data flow, entry points.

Model Tiers for Subagents

Task	Recommended Model	Reason
File exploration, search	Haiku	Fast and cheap
Implementation, writing	Sonnet	Balanced quality/cost
Architecture decisions	Opus	Maximum reasoning

14. Custom Agents — Building Specialized AI Workers

While subagents are helper workers called automatically from within Claude Code, custom agents are fully defined AI personas with their own identity, system instructions, allowed tools, and path restrictions. They are purpose-built to do one job extremely well and can be invoked by name.

Think of the difference like this:

Subagent: A temporary assistant you send on a research errand
Custom Agent: A dedicated specialist with a job title and a job description, who you bring in for specific, recurring scenarios

How Custom Agents Work

Custom Agent Definition

Custom agents live in .claude/agents/ as Markdown files with a frontmatter header:

---
name: security-auditor
description: >
  Specialized security agent. Use when asked to audit code for vulnerabilities,
  review authentication logic, check for exposed secrets, or analyze attack surfaces.
model: opus
color: red
tools:
  - Read
  - Bash(grep:*)
  - Bash(find:*)
allowed-paths:
  - src/
  - api/
denied-paths:
  - .env
  - secrets/
---

# Security Auditor Agent

You are a senior application security engineer with 15+ years of experience.
Your job is to identify vulnerabilities and security risks in code.

## Your focus areas
1. **Injection flaws** — SQL, NoSQL, command injection
2. **Authentication & Session Management** — weak tokens, insecure cookies
3. **Sensitive Data Exposure** — secrets in code, unencrypted storage
4. **Access Control** — broken authorization, IDOR vulnerabilities
5. **XSS & CSRF** — input/output encoding, CSRF tokens

## Output format
Always produce a structured report:
- **Risk level**: Critical / High / Medium / Low / Info
- **Location**: File path and line number
- **Description**: What the issue is
- **Recommendation**: How to fix it

Be specific and actionable. Reference OWASP Top 10 where applicable.

More Custom Agent Examples

Test Writer Agent:

---
name: test-writer
description: Use when writing unit tests, integration tests, or e2e tests.
  Specializes in Vitest, Jest, Playwright, and Cypress.
model: sonnet
color: purple
---
You are a test engineering expert. You write exhaustive tests that cover:
happy paths, edge cases, error states, and boundary conditions.
Always use descriptive test names. Mock external dependencies. Aim for 90%+ coverage.

API Designer Agent:

---
name: api-designer
description: Use when designing REST or GraphQL APIs. Produces OpenAPI specs,
  validates RESTful conventions, and generates documentation.
model: sonnet
color: green
---
You are a REST API design expert. You follow RESTful principles strictly.
Always produce OpenAPI 3.0 specs. Name endpoints as nouns, not verbs.
Return well-structured JSON with consistent error formats.

Database Migration Agent:

---
name: migration-expert
description: Use when writing database migrations. Specializes in safe,
  reversible schema changes with zero downtime strategies.
model: opus
color: orange
---
You are a database migration specialist. You write migrations that are:
- Always reversible (up + down)
- Safe for production (no full table locks on large tables)
- Documented with comments explaining the "why"

Custom Agents vs Subagents vs Skills

Feature	Subagents	Custom Agents	Skills
Purpose	Offload context-heavy tasks	Specialized expert persona	Reusable workflow procedures
Identity	Minimal	Full (name, personality, instructions)	Procedure-focused
Tool Restrictions	Inherited	✅ Custom per-agent	Inherited
Path Restrictions	No	✅ Yes	No
Model Choice	Per-agent	✅ Per-agent	Inherited
Invocation	Claude delegates automatically	By name or description match	Auto-matched by description
Best For	Exploration, summarization	Expert tasks (security, testing, APIs)	Consistent procedures

Can a Custom Agent Call Another Custom Agent?

Yes — and this is one of the most powerful patterns in Claude Code.

Custom agents can spawn and delegate to other custom agents, creating a chain of specialists where each one does only what it is best at. The orchestrating agent coordinates the work, each specialist executes its slice in its own isolated context, and results are passed up the chain.

Why This Matters

Think of a real engineering team: a tech lead doesn't write every line of code, run every test, and file every ticket themselves. They break the work down and hand each piece to the right person. Agent chaining works the same way.

Real-world analogy: You ask a contractor to renovate your kitchen. The contractor (orchestrator agent) doesn't do everything — they call in a plumber, an electrician, and a tiler (specialist agents). Each expert shows up, does their job, and reports back. The contractor assembles the full result and hands it to you.

How Agent Chaining Works

Each agent runs in its own clean context window. Only the summary output is passed to the orchestrator — not the full work, which would overflow the context. This makes complex multi-step pipelines practical at scale.

Example — Orchestrator Agent

---
name: feature-lead
description: >
  Use when delivering a complete feature end-to-end. Orchestrates design,
  implementation, testing, and security review by calling specialist agents.
model: opus
color: yellow
tools:
  - Read
  - Write
  - Task
---

# Feature Lead Agent

You are a senior engineering lead responsible for delivering complete features.
You do NOT write code or tests yourself.

## Your workflow — always in this order:
1. Call **api-designer** to produce an OpenAPI spec for the feature
2. Call **backend-dev** with the spec to implement it
3. Call **test-writer** with the implementation to write tests
4. Call **security-auditor** with the implementation to check for vulnerabilities
5. Compile the outputs into a final delivery summary

## Rules
- Do not skip steps. All four specialists must run.
- If any specialist returns a critical finding, pause and report to the user before continuing.
- Your final output must include: spec location, implementation files, test files, and security report.

The `Task` Tool — How Agents Invoke Each Other

The key is the Task tool in the orchestrator's allowed tools list. Task is a built-in Claude Code tool that launches a sub-session (agent or subagent) with a specific prompt and returns its output. You do not need to wire this up manually — Claude Code handles the handoff automatically when an agent's description matches what the orchestrator needs.

tools:
  - Task        # ← This is what enables calling other agents
  - Read
  - Write

Chaining Rules & Limits

Rule	Detail
Depth	Agents can chain multiple levels deep (A → B → C), but keep chains ≤ 3 levels to avoid runaway costs
Context isolation	Each agent gets a fresh context — only the return value travels up the chain
Model mixing	Orchestrator can be Opus while sub-agents are Sonnet or Haiku — optimise cost per task
Circular calls	Avoid Agent A calling Agent B which calls Agent A — this causes infinite loops
Token cost	Each agent in the chain is a separate API call; deep chains with heavy models can get expensive

When to Use Agent Chaining

Multi-phase features — design → build → test → review in one command
Quality gates — always run security-auditor and test-writer after any implementation agent
Parallel specialization — different agents own different parts of the codebase (frontend, backend, infra)
Reducing context bloat — instead of one massive session reading everything, split into specialists that each read only what they need

Pro-tip: Give your orchestrator agent the Task tool and a very clear numbered workflow in its instructions. The more explicit the handoff order, the more reliable the chain.

15. Hooks — Automation that Always Runs

Hooks guarantee execution of shell commands regardless of model behavior. Prompts can be ignored; hooks cannot. Use them for linting, formatting, tests, and notifications.

Hook Lifecycle Events

Event	When It Fires
`PreToolUse`	Before Claude uses a tool
`PostToolUse`	After a tool use completes
`Notification`	When Claude sends a message
`Stop`	When the session ends

Hook Configuration in `settings.json`

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black $file && python -m mypy $file"
          }
        ]
      },
      {
        "matcher": "Write(*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $file && npx tsc --noEmit"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished!\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

16. Permissions & Security

`settings.json` — Full Permission Example

{
  "model": "claude-sonnet-4-6",
  "maxTokens": 4096,
  "permissions": {
    "allowedTools": [
      "Read",
      "Write",
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Write(./production.config.*)",
      "Bash(rm -rf *)"
    ]
  }
}

Permission Modes Explained

Normal — Claude asks before every tool use
Auto-Accept — Claude proceeds without asking (toggle with Shift+Tab)
--dangerously-skip-permissions — Bypasses all prompts (CI environments only)

Team tip: Commit .claude/settings.json and .mcp.json to git so the whole team shares the same tool permissions and MCP configuration. Add .claude/settings.local.json to .gitignore for personal overrides.

17. Context Management Tips

The context window is a shared resource. Managing it well directly affects quality and cost.

/clear between tasks — Don't carry unrelated history into a new task; it wastes tokens and can confuse Claude.
/compact — Summarizes and compresses a long session to free up context while preserving the key decisions.
Use ! prefix for shell commands — !git status runs in bash directly, bypassing Claude's conversational mode and consuming fewer tokens.
Subagents for exploration — Delegate file reading and searching to subagents; only the summary comes back into main context.
--max-turns N — Cap how many agentic loops Claude runs. Useful in CI to prevent runaway sessions.

Use the /cost command inside a session to track spend in real time.

18. Useful Environment Variables

# Cost & telemetry
DISABLE_COST_WARNINGS=1       # Hide cost warnings
DISABLE_TELEMETRY=1           # Opt out of usage telemetry
DISABLE_AUTOUPDATER=1         # Prevent automatic updates

# Timeouts & output
BASH_DEFAULT_TIMEOUT_MS=30000       # Bash command timeout (default 30s)
BASH_MAX_TIMEOUT_MS=600000          # Max bash timeout (10 min)
BASH_MAX_OUTPUT_LENGTH=50000        # Bash output character limit
MCP_TIMEOUT=5000                    # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000              # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000         # MCP output token limit

# Prompt caching
DISABLE_PROMPT_CACHING=1            # Disable globally
DISABLE_PROMPT_CACHING_SONNET=1     # Disable for Sonnet only

# Experimental
ENABLE_EXPERIMENTAL_MCP_CLI=true    # Load MCP tools on-demand (~80% token savings)

19. Quick Reference — Everything in One Place

20. Getting Started Checklist

Install: curl -fsSL https://claude.ai/install.sh | bash
Health check: claude doctor
Navigate to your repo: cd my-project
Launch and initialize: claude → /init
Review the generated CLAUDE.md and customize it for your stack
Add an MCP server: claude mcp add --transport http github https://api.githubcopilot.com/mcp/
Try Plan Mode: Shift+Tab twice — ask Claude to plan a feature
Create a custom agent: mkdir -p .claude/agents && vim .claude/agents/reviewer.md
Create a slash command: mkdir -p .claude/commands && echo "..." > .claude/commands/review.md
Commit your config: git add CLAUDE.md .claude/ .mcp.json
Monitor cost: use /cost to track token spend per session
Manage context: use /compact when sessions get long, /clear between unrelated tasks

What's Next?

Now that you understand the full Claude ecosystem, explore further:

Claude Code Official Docs
MCP Server Registry
Awesome Claude Code — community skills, hooks, and agents
Anthropic Prompt Engineering Guide
Claude API Reference

1. Anthropic — The Name & A Brief History​

Why "Anthropic"?​

Timeline​

2. The Name "Claude" — Where Does It Come From?​

3. The Claude Model Tiers — Haiku, Sonnet & Opus​

🌸 Haiku — Speed & Efficiency​

🎼 Sonnet — Balance & Craft​

🎭 Opus — Power & Depth​

Model Summary Table​

4. Understanding Tokens — Simply Explained​

What Is a Token?​

The Rule of Thumb​

A Practical Token Example​

Tokens = Input + Output​

The Context Window = Your Token Budget Per Session​

How Many Messages Per Context Window?​

API Pricing (Rough Guide)​

5. Installing Claude Code​

macOS — Recommended Method​

Linux (Ubuntu / Debian)​

Windows — via WSL (Windows Subsystem for Linux)​

First-Time Authentication​

Updating Claude Code​

6. Claude Code — The Terminal-Native Agent​

Launching Claude Code​

7. Keyboard Shortcuts​

8. Slash Commands​

Session & Context Management​

Configuration & Model​

Tools & Integrations​

Custom Slash Commands​

9. Operating Modes​

Normal Mode (Default)​

Auto-Accept Mode​

Plan Mode​

Headless / Print Mode​

--dangerously-skip-permissions​

10. CLAUDE.md — Project Memory​

File Hierarchy​

Recommended CLAUDE.md Structure​

11. MCP — Model Context Protocol​

Without MCP vs With MCP​

MCP Architecture​

Adding MCP Servers​

MCP Configuration File (.mcp.json)​

Popular MCP Servers​

12. Skills​

Creating a Skill​

Skills vs Slash Commands vs CLAUDE.md​

13. Subagents — Delegating Context-Hungry Work​

Why Use Subagents​

Defining a Subagent​

Model Tiers for Subagents​

14. Custom Agents — Building Specialized AI Workers​

How Custom Agents Work​

Custom Agent Definition​

More Custom Agent Examples​

Custom Agents vs Subagents vs Skills​

Can a Custom Agent Call Another Custom Agent?​

Why This Matters​

How Agent Chaining Works​

Example — Orchestrator Agent​

The Task Tool — How Agents Invoke Each Other​

Chaining Rules & Limits​

When to Use Agent Chaining​

15. Hooks — Automation that Always Runs​

Hook Lifecycle Events​

Hook Configuration in settings.json​

16. Permissions & Security​

settings.json — Full Permission Example​

Permission Modes Explained​

17. Context Management Tips​

18. Useful Environment Variables​

19. Quick Reference — Everything in One Place​

20. Getting Started Checklist​

What's Next?​