---
title: "Claude Code Comprehensive Reference Guide (2024-2026)"
description: "> A complete reference covering hooks, skills, MCP integration, Agent SDK, configuration, subagent patterns, and IDE integrations."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/claude-code-reference
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:13:40.513Z
license: CC-BY-4.0
attribution: "Claude Code Comprehensive Reference Guide (2024-2026) — Claudary (https://claudary.paisolsolutions.com/skills/claude-code-reference)"
---

# Claude Code Comprehensive Reference Guide (2024-2026)
> A complete reference covering hooks, skills, MCP integration, Agent SDK, configuration, subagent patterns, and IDE integrations.

## Overview

# Claude Code Comprehensive Reference Guide (2024-2026)

> A complete reference covering hooks, skills, MCP integration, Agent SDK, configuration, subagent patterns, and IDE integrations.

**Last Updated:** January 2026
**Applicable Versions:** Claude Code 2.x+

---

## Table of Contents

1. [Hooks System Deep Dive](#1-hooks-system-deep-dive)
2. [Skills and Slash Commands](#2-skills-and-slash-commands)
3. [MCP Server Implementation](#3-mcp-server-implementation)
4. [Agent SDK Patterns](#4-agent-sdk-patterns)
5. [Configuration Best Practices](#5-configuration-best-practices)
6. [Subagent Orchestration](#6-subagent-orchestration)
7. [IDE Integrations](#7-ide-integrations)
8. [Production Examples](#8-production-examples)
9. [Context Window Management](#9-context-window-management)
10. [Tools Reference](#10-tools-reference)

---

## 1. Hooks System Deep Dive

Hooks are automated actions triggered at specific points in a Claude Code session. They enable validation, monitoring, and control of Claude's actions through bash commands or LLM-based evaluation.

**Sources:**
- [Hooks Reference - Claude Code Docs](https://code.claude.com/docs/en/hooks)
- [Anthropic Blog: Configure Hooks](https://claude.com/blog/how-to-configure-hooks)
- [Agent SDK Hooks](https://platform.claude.com/docs/en/agent-sdk/hooks)

### 1.1 Hook Lifecycle

Hooks fire in this sequence:

1. **SessionStart** - Session begins or resumes
2. **UserPromptSubmit** - User submits a prompt
3. **PreToolUse** - Before tool execution (can modify/block)
4. **PermissionRequest** - When permission dialog appears
5. **PostToolUse** - After tool succeeds
6. **SubagentStart** - When spawning a subagent
7. **SubagentStop** - When subagent finishes
8. **Stop** - Claude finishes responding
9. **PreCompact** - Before context compaction
10. **SessionEnd** - Session terminates
11. **Notification** - Claude Code sends notifications

### 1.2 Hook Types

**Command Hooks** (`type: "command"`):
Execute bash commands with full stdin/stdout control.

**Prompt Hooks** (`type: "prompt"`):
Use LLM evaluation for intelligent, context-aware decisions. Currently only supported for `Stop` and `SubagentStop` events.

### 1.3 Configuration Structure

Hooks are configured in settings files:
- `~/.claude/settings.json` - User settings (all projects)
- `.claude/settings.json` - Project settings (shared with team)
- `.claude/settings.local.json` - Local project settings (not committed)

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\\"$CLAUDE_PROJECT_DIR\\"/.claude/hooks/format-code.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all requested tasks are complete. If not, list what remains.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

### 1.4 Matcher Syntax

| Pattern | Description |
|---------|-------------|
| `Write` | Match exact tool name |
| `Edit\\|Write` | Match multiple tools (regex OR) |
| `Notebook.*` | Regex pattern matching |
| `*` or `""` | Match all tools |
| (omitted) | Required for Stop, SubagentStop, UserPromptSubmit |

### 1.5 Hook Input Schema

All hooks receive JSON via stdin:

```json
{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript",
  "cwd": "/project/root",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  }
}
```

### 1.6 Hook Output and Exit Codes

| Exit Code | Behavior |
|-----------|----------|
| 0 | Success - stdout shown to user or added as context |
| 2 | Blocking error - stderr shown, action blocked |
| Other | Non-blocking error - stderr shown in verbose mode |

**PreToolUse Decision Control:**

```json
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "Reason for decision",
    "updatedInput": {
      "command": "modified command"
    },
    "additionalContext": "Context for Claude"
  }
}
```

**Stop/SubagentStop Control:**

```json
{
  "decision": "block",
  "reason": "Tasks incomplete: missing test coverage"
}
```

### 1.7 Environment Variables

| Variable | Description |
|----------|-------------|
| `CLAUDE_PROJECT_DIR` | Absolute path to project root |
| `CLAUDE_CODE_REMOTE` | "true" if remote session |
| `CLAUDE_ENV_FILE` | Path to persist env vars (SessionStart/Setup only) |
| `CLAUDE_FILE_PATHS` | Space-separated file paths (PostToolUse for Write/Edit) |

### 1.8 Practical Hook Examples

**Security Firewall (block dangerous commands):**

```bash
#!/usr/bin/env bash
# .claude/hooks/pre-bash-firewall.sh
set -euo pipefail

cmd=$(jq -r '.tool_input.command // ""')

# Block dangerous patterns
if echo "$cmd" | grep -qE 'rm -rf|git reset --hard|curl.*\\|.*sh'; then
  echo '{"decision": "block", "reason": "Dangerous command blocked by security policy"}' >&2
  exit 2
fi

exit 0
```

**Auto-formatter (run after file changes):**

```bash
#!/usr/bin/env bash
# .claude/hooks/format-code.sh
set -euo pipefail

# Get changed files
files=$(jq -r '.tool_input.file_path // ""')

# Format based on extension
for file in $files; do
  case "$file" in
    *.py) black "$file" 2>/dev/null || true ;;
    *.js|*.ts) prettier --write "$file" 2>/dev/null || true ;;
  esac
done

exit 0
```

**Command Logger:**

```bash
#!/usr/bin/env bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command // ""')
printf '%s %s\\n' "$(date -Is)" "$cmd" >> .claude/bash-commands.log
exit 0
```

### 1.9 SubagentStop Hooks for Workflow Control

SubagentStop hooks fire when a subagent (Task tool) completes. This enables workflow orchestration:

```json
{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review the subagent's work. Did it complete all assigned tasks? Are there any issues that need escalation to the main agent?"
          }
        ]
      }
    ]
  }
}
```

---

## 2. Skills and Slash Commands

Skills are structured, auto-discovered capabilities that extend Claude's functionality. Custom slash commands have been merged into skills - a file at `.claude/commands/review.md` and a skill at `.claude/skills/review/SKILL.md` both create `/review`.

**Sources:**
- [Skills Documentation](https://code.claude.com/docs/en/skills)
- [Slash Commands Guide](https://code.claude.com/docs/en/slash-commands)
- [Agent Skills Standard](https://agentskills.io)
- [Anthropic Skills Repository](https://github.com/anthropics/skills)

### 2.1 Key Differences

| Feature | Slash Commands | Skills |
|---------|----------------|--------|
| Invocation | Manual `/command` | Auto or manual |
| Structure | Single markdown file | Directory with SKILL.md + resources |
| Complexity | Simple, repeatable tasks | Rich workflows with supporting files |
| Discovery | Must know command name | Claude auto-triggers when relevant |

### 2.2 Directory Structure

```
my-skill/
├── SKILL.md           # Required - instructions and metadata
├── reference.md       # Optional - detailed documentation
├── examples.md        # Optional - usage examples
└── scripts/
    └── helper.py      # Optional - executable scripts
```

**Storage Locations:**

| Location | Path | Scope |
|----------|------|-------|
| Enterprise | See managed settings | All organization users |
| Personal | `~/.claude/skills/<name>/SKILL.md` | All your projects |
| Project | `.claude/skills/<name>/SKILL.md` | Current project only |

### 2.3 SKILL.md Format

```yaml
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
argument-hint: [file-path]
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep, Glob
model: claude-sonnet-4-20250514
context: fork
agent: Explore
---

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 flow, structure, or relationships
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. For complex concepts, use multiple analogies.
```

### 2.4 Frontmatter Reference

| Field | Required | Description |
|-------|----------|-------------|
| `name` | No | Display name (lowercase, max 64 chars). Defaults to directory name |
| `description` | Recommended | What skill does and when to use it (max 1024 chars) |
| `argument-hint` | No | Autocomplete hint, e.g., `[issue-number]` |
| `disable-model-invocation` | No | `true` = manual only. Default: `false` |
| `user-invocable` | No | `false` = hidden from `/` menu. Default: `true` |
| `allowed-tools` | No | Tools Claude can use without permission |
| `model` | No | Specific model when skill is active |
| `context` | No | `fork` = run in isolated subagent context |
| `agent` | No | Subagent type: `Explore`, `Plan`, `general-purpose` |
| `hooks` | No | Lifecycle hooks for this skill |

### 2.5 Invocation Control Patterns

**Manual Only (side effects):**
```yaml
---
name: deploy
description: Deploy to production
disable-model-invocation: true
---
```

**Background Knowledge (auto-only):**
```yaml
---
name: legacy-context
description: How the legacy payment system works
user-invocable: false
---
```

**Full Access (default):**
```yaml
---
name: review
description: Code review with best practices
---
```

### 2.6 Dynamic Context Injection

Use shell command syntax to inject dynamic content:

```yaml
---
name: pr-summary
description: Summarize PR changes
context: fork
agent: Explore
allowed-tools: Bash(gh:*)
---

## Pull request context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Summarize this pull request...
```

### 2.7 String Substitutions

| Variable | Description |
|----------|-------------|
| `$ARGUMENTS` | All arguments passed when invoking |
| `${CLAUDE_SESSION_ID}` | Current session ID |

### 2.8 Subagent Execution

```yaml
---
name: deep-research
description: Research a topic thoroughly
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
```

### 2.9 Skill-Scoped Hooks

```yaml
---
name: secure-operations
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
  once: true
---
```

### 2.10 Context Budget

Skill descriptions are loaded into context. Default budget: 15,000 characters.

```bash
# Check for warnings
/context

# Increase limit
export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000
```

---

## 3. MCP Server Implementation

The Model Context Protocol (MCP) is an open standard for connecting AI models to external tools, data sources, and services.

**Sources:**
- [MCP in Claude Code](https://code.claude.com/docs/en/mcp)
- [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25)
- [MCP Registry](https://registry.modelcontextprotocol.io)
- [Agent SDK MCP](https://platform.claude.com/docs/en/agent-sdk/mcp)

### 3.1 Overview

MCP provides three core capabilities:

| Capability | Description |
|------------|-------------|
| **Tools** | Functions that can perform actions or fetch data |
| **Resources** | Read-only content accessible via `@` mentions |
| **Prompts** | Reusable prompt templates available as `/mcp__server__prompt` |

### 3.2 Configuration Methods

**CLI Wizard:**
```bash
claude mcp add
```

**Direct Configuration (`.mcp.json` or settings):**

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    },
    "custom-api": {
      "url": "https://your-api.com/mcp",
      "transport": "http"
    }
  }
}
```

### 3.3 Transport Types

| Transport | Description |
|-----------|-------------|
| `stdio` | Subprocess with JSON-RPC over stdin/stdout (most common) |
| `http` | Remote HTTP server (recommended for cloud services) |
| `sse` | Server-Sent Events |

### 3.4 Building Custom MCP Servers

**Python SDK:**
```bash
pip install mcp
```

**TypeScript SDK:**
```bash
npm install @modelcontextprotocol/sdk
```

**Example Server (TypeScript):**

```typescript
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'my-server',
  version: '1.0.0',
}, {
  capabilities: {
    tools: {},
    resources: {},
    prompts: {},
  },
});

// Define a tool
server.setRequestHandler('tools/list', async () => ({
  tools: [{
    name: 'get_weather',
    description: 'Get current weather for a location',
    inputSchema: {
      type: 'object',
      properties: {
        location: { type: 'string', description: 'City name' },
      },
      required: ['location'],
    },
  }],
}));

server.setRequestHandler('tools/call', async (request) => {
  if (request.params.name === 'get_weather') {
    const { location } = request.params.arguments;
    // Fetch weather data...
    return { content: [{ type: 'text', text: `Weather in ${location}: Sunny, 72F` }] };
  }
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
```

### 3.5 Using MCP Resources

```
@mcp__filesystem__readme.md
```

Resources appear alongside files in the `@` autocomplete menu.

### 3.6 Dynamic Tool Loading

When MCP tool descriptions exceed 10% of context, Tool Search activates automatically, loading tools on-demand.

### 3.7 Security Considerations

- MCP servers run with your user permissions
- Validate and sanitize all inputs
- Be cautious with servers that fetch untrusted content (prompt injection risk)
- Review third-party servers before installation

---

## 4. Agent SDK Patterns

The Claude Agent SDK lets you build AI agents programmatically with the same capabilities that power Claude Code.

**Sources:**
- [Agent SDK Overview](https://docs.claude.com/en/docs/agent-sdk/overview)
- [Python SDK](https://github.com/anthropics/claude-agent-sdk-python)
- [TypeScript SDK](https://github.com/anthropics/claude-agent-sdk-typescript)
- [Building Agents Blog](ht

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/claude-code-reference) · https://claudary.paisolsolutions.com