🤖 Sub-Agents

Specialized AI assistants that handle specific tasks in their own context window, returning only a summary.

What & Why

• Own context window — verbose output stays there, not in your main chat
• No nesting — subagents cannot spawn other subagents
• Custom system prompt — subagents only get their own body (not Claude Code's default)
• Preserve context · Enforce constraints · Reuse configs · Specialize · Control costs
• vs Agent Teams: subagents = single session; teams = separate independent sessions

Built-In Agents

Creating Sub-Agents

Scope & Priority (higher wins on name conflict)

All Frontmatter Fields

Invocation Methods

8 Key Rules

• No nesting — subagents cannot spawn other subagents. Chain from main conversation or use Skills.
• Higher scope wins on name conflict: managed › CLI › project › user › plugin.
• Model resolution: env var → per-invocation → frontmatter → main conversation.
• bypassPermissions is risky — .git, .claude, .vscode, .idea, .husky still prompt.
• Memory default = project — shareable via git. Use user for cross-project knowledge.
• Description quality = delegation quality — Claude reads it to decide when to delegate.
• No inherited system prompt — subagents only get their own body. Write it fully.
• Background agents pre-approve — permissions locked upfront. Missing ones = failure, not prompt.

👥 Agent Teams Experimental

Coordinate multiple Claude Code instances working together — each with its own context window, communicating directly with each other via shared task list.

Sub-Agents vs Agent Teams

Best Use Cases

• Research & review — multiple teammates investigate different aspects simultaneously
• New modules / features — each teammate owns a separate piece without stepping on others
• Competing hypotheses — teammates test different theories, debate, converge on root cause
• Cross-layer — changes spanning frontend, backend, tests each owned by different teammate

Architecture

Display Modes

Key Controls

• Shift+Down — cycle through teammates (in-process mode)
• Ctrl+T — toggle task list
• Esc — interrupt teammate's current turn
• Tell lead: "Wait for teammates to finish before proceeding"
• Tell lead: "Spawn a teammate with plan approval required"
• Clean up: always ask the lead — never let a teammate clean up

Hook Events for Teams

Best Practices

• Team size: start with 3–5 teammates. 5–6 tasks per teammate keeps everyone productive.
• Task size: self-contained units producing a clear deliverable (a function, test file, review)
• Avoid file conflicts — two teammates editing the same file leads to overwrites
• Include context in spawn prompt — teammates don't inherit lead's conversation history
• Start with research — reviewing/researching before parallel implementation
• Monitor and steer — don't let a team run unattended too long

Limitations

• No session resumption with in-process teammates (/resume / /rewind don't restore them)
• Task status can lag — sometimes teammates fail to mark tasks complete
• One team per session — clean up before starting a new one
• No nested teams — teammates can't spawn their own teams
• Lead is fixed — can't promote a teammate to lead
• Split panes not supported in VS Code terminal, Windows Terminal, or Ghostty

🔌 Model Context Protocol (MCP)

Connect Claude Code to external tools and services — databases, APIs, GitHub, Slack, and more — through a standardized protocol.

What is MCP?

• Standard protocol for connecting AI models to external tools and data sources
• MCP servers expose tools, resources, and prompts that Claude can use
• Each server runs as a separate process; Claude communicates with it during the session
• Tools from MCP servers appear alongside built-in tools in Claude's context

Installation Methods

Server Config Format (stdio)

# .mcp.json at repository root
{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@my/mcp-server"],
      "env": { "API_KEY": "${MY_API_KEY}" }
    }
  }
}

Connection Types

Scope & Priority

Popular Official Marketplace MCP Plugins

Key Commands

• /mcp — view all servers, connection status, approve project servers
• Project servers require one-time approval — if dismissed, server stays disabled
• Use absolute paths for local server commands (relative paths fail from different directories)
• Set env vars in .mcp.json per-server, not in settings.json env (doesn't propagate)
• claude --debug mcp — see server stderr if tools not showing up

🧩 Plugins

Self-contained directories that extend Claude Code with skills, agents, hooks, MCP servers, LSP servers, and monitors. Share across teams or distribute via marketplaces.

Standalone Config vs Plugins

Plugin Structure

my-plugin/
├── .claude-plugin/
│   └── plugin.json     # manifest (name, description, version)
├── skills/
│   └── my-skill/SKILL.md
├── agents/
│   └── my-agent.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── .lsp.json           # language server config
├── monitors/
│   └── monitors.json   # background monitors
├── bin/                # executables added to PATH
└── settings.json       # default settings (agent, subagentStatusLine)

Plugin Manifest (plugin.json)

{
  "name": "my-plugin",       # namespace for skills: /my-plugin:hello
  "description": "...",
  "version": "1.0.0",
  "author": { "name": "..." }
}

Discovering & Installing Plugins

• Official marketplace: /plugin install github@claude-plugins-official
• Browse: /plugin → Discover tab, or claude.com/plugins
• Scopes: User (all projects) · Project (team, in settings.json) · Local (personal, not shared)
• Reload without restart: /reload-plugins
• Test locally: claude --plugin-dir ./my-plugin

Marketplace Commands

Plugin Components

Code Intelligence Plugins (LSP)

LSP gives Claude: auto diagnostics after every edit + code navigation (jump to def, find refs, type info)

⚡ Skills

Create SKILL.md files to add reusable instructions, workflows, and domain knowledge. Invoke with /skill-name or let Claude trigger automatically.

Skills vs CLAUDE.md

• CLAUDE.md: always in context, facts and conventions the model applies continuously
• Skills: loaded only when invoked — great for long procedures, reference docs, checklists
• Custom commands (.claude/commands/deploy.md) = skills. Same behavior, skills add features.

Where Skills Live

Skill File Structure

my-skill/
├── SKILL.md        # required — frontmatter + instructions
├── reference.md    # detailed docs loaded on demand
├── examples.md     # example outputs
└── scripts/
    └── helper.py   # scripts Claude can execute

Frontmatter Reference

Invocation Control

String Substitutions

Dynamic Context Injection

• Use !`command` to run shell commands — output replaces the placeholder before Claude sees anything
• Multi-line: use fenced code block opened with ```!
• This is preprocessing, not something Claude executes
• Add ultrathink anywhere in skill content to enable extended thinking

🪝 Hooks

User-defined shell commands, HTTP endpoints, or LLM prompts that execute automatically at specific points in Claude Code's lifecycle. Automate workflows, enforce policies, validate actions.

Hook Configuration Structure

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",         # tool name, regex, or pipe-separated list
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Where to Configure

All Hook Events

✋ = can block with exit code 2

Handler Types

Exit Codes (command hooks)

Matcher Patterns

Common Patterns

• Block destructive Bash: PreToolUse + matcher "Bash" + exit 2 if command has rm -rf
• Auto-lint after edit: PostToolUse + matcher "Edit|Write" + run linter
• DB read-only guard: PreToolUse + validate SQL for INSERT/UPDATE/DELETE/DROP
• Notify on stop: Stop + send desktop notification
• View configured hooks: type /hooks in Claude Code
• Debug: claude --debug hooks to watch evaluation live

Common Mistakes

• Matcher is JSON array instead of string — use "Edit|Write" not ["Edit","Write"]
• Tool name lowercase ("bash") — must be capitalized: "Bash", "Edit", "Write"
• Hooks in standalone .claude/hooks.json — no such file; use "hooks" key in settings.json
• Using exit code 1 expecting a block — use exit code 2 to block

⏰ Automation

Run Claude Code programmatically, schedule recurring tasks, and push external events into sessions.

Scheduling Options Comparison

/loop — Session Scheduling

One-Time Reminders

• "remind me at 3pm to push the release branch"
• "in 45 minutes, check whether integration tests passed"
• Claude schedules a single-fire task that deletes itself after running

Task Management Tools

Cron Expression Reference

Fields: minute hour day-of-month month day-of-week. All times = local timezone. Max 50 tasks per session. Recurring tasks expire after 7 days.

Programmatic Usage (CLI -p)

--bare Mode (Recommended for CI)

• Skips auto-discovery of hooks, skills, plugins, MCP servers, auto memory, CLAUDE.md
• Load what you need explicitly: --settings, --mcp-config, --agents, --plugin-dir
• Auth must come from ANTHROPIC_API_KEY or apiKeyHelper in settings JSON
• Will become the default for -p in a future release

Permission Modes for Automation

loop.md — Custom Default Loop

• Create .claude/loop.md (project) or ~/.claude/loop.md (user)
• Replaces built-in maintenance prompt for bare /loop
• Edits take effect on next iteration (no restart needed)
• Max 25,000 bytes; project takes precedence over user

Disable Scheduling

CLAUDE_CODE_DISABLE_CRON=1 — disables scheduler entirely. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 — disables background tasks.

🔧 Troubleshooting & Debug

Diagnose installation issues, configuration problems, and unexpected behavior.

Diagnostic Commands

Debug Flags

Common Config Problems

Installation Quick Fixes

Configuration File Locations

Performance Issues

• Use /compact regularly to reduce context size
• Install system ripgrep for search/agent/skills to work properly
• WSL on Windows filesystem (/mnt/c/) = slow search. Move project to /home/
• /heapdump — write JS heap snapshot to Desktop for memory debugging
• Autocompact thrashing: use /compact with focus, or move large-file work to subagent

📡 Channels Research Preview

Push external events into a running Claude Code session from an MCP server. Requires Claude Code v2.1.80+, claude.ai login.

What is a Channel?

• MCP server that pushes events into your running session — not polled, but pushed in real-time
• Two-way: Claude reads the event and can reply back through the same channel (chat bridge)
• Events only arrive while session is open — run Claude in background/persistent terminal for always-on
• Reply text appears on the other platform, not in your terminal; terminal shows the tool call + confirmation
• Install channels as plugins, configured with your own credentials

Supported Channels

Quickstart (Fakechat demo)

• Install: /plugin install fakechat@claude-plugins-official
• Restart with channel: claude --channels plugin:fakechat@claude-plugins-official
• Open http://localhost:8787 and type a message — arrives in your session as a <channel source="fakechat"> event
• Claude replies, answer shows back in browser. Can pass multiple plugins space-separated.

Setup Pattern (Telegram/Discord)

• Create bot on platform → get token
• /plugin install telegram@claude-plugins-official → /reload-plugins
• Configure: /telegram:configure <token>
• Restart: claude --channels plugin:telegram@claude-plugins-official
• Send any message to bot → bot replies with pairing code
• In Claude: /telegram:access pair <code> → /telegram:access policy allowlist

Security

• Sender allowlist: only approved IDs can push messages, others silently dropped
• Pairing bootstrap: send to bot → get code → approve in Claude → added to allowlist
• iMessage: texting yourself bypasses gate; add others with /imessage:access allow +15551234567
• --channels flag required: being in .mcp.json alone is not enough
• Permission relay: allowlisted senders can approve/deny tool use remotely — only allow trusted senders

Enterprise Controls

• Enable via claude.ai Admin console or set channelsEnabled: true in managed settings
• allowedChannelPlugins example: [{"marketplace":"claude-plugins-official","plugin":"telegram"}]
• Empty allowedChannelPlugins array blocks all allowlist plugins (dev flag can still bypass)
• To block everything including dev flag: leave channelsEnabled unset
• Pro/Max users (no org) skip checks entirely — opt in per session with --channels

Channels vs Other Integration Methods

Use Cases

🚨 Error Reference

Runtime errors Claude Code displays, what each means, and how to recover. Install errors (command not found, TLS failures) are in Troubleshooting.

Server Errors

Usage Limits

Authentication Errors

Network Errors

Request Errors

Quality Seems Lower Than Usual

• /model — confirm you are on expected model (ANTHROPIC_MODEL env may point to smaller model)
• /effort — check reasoning level, raise for hard debugging; try "ultrathink" shortcut
• /context — if near capacity, /compact at natural breakpoint or /clear to start fresh
• /doctor — flags oversized CLAUDE.md and subagent definitions that consume context
• Rewind, don't correct: Esc×2 or /rewind to step back before bad turn, rephrase. Keeping wrong attempt in context anchors future answers to it.
• /feedback — includes transcript, fastest way for Anthropic to diagnose a regression

Quick Recovery Commands

📄 Example Files

Annotated real-world files for every Claude Code extension type. Each comment explains why, not just what.

---
name: code-reviewer             # lowercase-with-hyphens, matches filename
description: Review changed files for bugs, security issues, and style
                                   # Claude reads this to decide WHEN to delegate
model: sonnet                      # sonnet | opus | haiku | inherit | full model id
tools: Read, Grep, Glob, Bash      # allowlist — omit to inherit all tools
permissionMode: plan              # plan = read-only, never edits files
memory: project                   # project = .claude/agent-memory/, shareable via git
maxTurns: 20                      # cap to avoid runaway token usage
---

You are a focused code reviewer. When invoked you receive changed file paths.

Steps:
1. Read each changed file in full
2. Check for: bugs, security issues (injection, auth bypass, secrets), style violations
3. Return a concise review — one finding per line, with severity (critical/warn/info) and line number

Do not suggest refactors unless asked. Focus on correctness and safety only.

---
name: debugger
description: Diagnose and fix errors, stack traces, and failing tests
model: inherit                     # use whatever model the parent is using
tools: Read, Edit, Bash, Grep, Glob
isolation: worktree               # isolated git copy — auto-cleaned if no changes made
maxTurns: 40
---

You are an expert debugger. You will:
1. Reproduce the error by reading logs and running the failing command
2. Trace the root cause through the call stack
3. Apply the minimal fix — do not refactor surrounding code
4. Confirm the fix works by running the test or command again

Always explain what caused the bug before showing the fix.

---
name: deploy
description: Run the full deployment pipeline for this project
disable-model-invocation: true    # only YOU can trigger this — not Claude autonomously
context: fork                      # runs in isolated subagent, keeps main context clean
---

# Deploy Procedure

Run these steps in order. Stop and report if any step fails.

1. `npm run build` — build production assets, check for errors
2. `npm test` — run full test suite, report failures before continuing
3. `git tag v$(date +%Y%m%d-%H%M)` — create a timestamped release tag
4. `git push origin main --tags` — push code and tag
5. Confirm the GitHub Actions CI pipeline passes (check Actions tab)

Report: build status, test count passed/failed, tag name, CI link.

---
name: pr-review
description: Review open pull requests and post summary comments
user-invocable: false             # hidden from / menu — Claude uses internally
context: fork
---

Use the GitHub MCP tool to:
1. List open PRs on this repo
2. For each PR: read the diff, check CI status, read existing review comments
3. Post a short review comment summarising: what changed, any risks, suggested next step

Be concise. One paragraph per PR. Flag blockers clearly.

{
  "hooks": {

    "PreToolUse": [
      {
        "matcher": "Bash",          // fire before every Bash call
        "hooks": [{
          "type": "command",
          // exit 2 = BLOCK the tool + send stderr to Claude as error
          // exit 0 = allow  |  exit 1 = log but allow
          "command": "bash -c 'cmd=$(echo $CLAUDE_TOOL_INPUT | jq -r .command); echo \"$cmd\" >> ~/claude-audit.log; if echo \"$cmd\" | grep -qE \"rm -rf|DROP TABLE\"; then echo \"Blocked: destructive command\" >&2; exit 2; fi'"
        }]
      },
      {
        "matcher": "Write|Edit",    // pipe-separate multiple tools
        "hooks": [{
          "type": "command",
          "command": "bash -c 'path=$(echo $CLAUDE_TOOL_INPUT | jq -r .path // .file_path); if [[ $path == *.env* ]]; then echo \"Blocked: .env file\" >&2; exit 2; fi'"
        }]
      }
    ],

    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          // auto-format every file Claude writes or edits
          "command": "bash -c 'path=$(echo $CLAUDE_TOOL_INPUT | jq -r .path // .file_path); npx prettier --write \"$path\" 2>/dev/null || true'"
        }]
      }
    ],

    "Stop": [
      {
        "hooks": [{
          "type": "command",
          // notify when Claude finishes a long task
          "command": "osascript -e 'display notification \"Claude finished\" with title \"Claude Code\"'"
        }]
      }
    ]
  }
}

{
  "mcpServers": {

    "github": {
      "type": "stdio",            // local process via stdin/stdout
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        // put tokens in env here, NOT in args (args appear in process list)
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },

    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
                                 // no env needed — launches browser headlessly
    },

    "postgres": {
      "type": "stdio",
      "command": "/usr/local/bin/mcp-server-postgres",
                                 // use ABSOLUTE paths for local scripts
                                 // relative paths break when launched from different dirs
      "args": ["--connection-string", "postgresql://localhost/mydb"]
    },

    "remote-api": {
      "type": "http",             // remote HTTP endpoint (no local process needed)
      "url": "https://mcp.example.com/tools",
      "headers": {
        "Authorization": "Bearer ${MY_API_TOKEN}"
      }
    }

  }
}

my-plugin/
├── .claude-plugin/
│   └── plugin.json             ← manifest lives here
├── skills/
│   └── deploy.md               ← skills at plugin root level
├── agents/
│   └── reviewer.md
├── hooks/
│   └── pre-commit.sh
└── .mcp.json                   ← MCP config at plugin root

{
  "name": "my-plugin",           // used for namespacing: /my-plugin:skill-name
  "version": "1.0.0",
  "description": "Code review + deploy tools for this monorepo",
  "author": "your-team",
  "minClaudeCodeVersion": "2.0.0" // optional minimum version gate
}

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

Spawn a team to build the login feature:
- One teammate writes the backend API (Node/Express, JWT auth)
- One teammate writes the frontend form (React, form validation)
- One teammate writes the tests (Jest + React Testing Library)
Coordinate via the shared task list. Don't duplicate work.

// Each teammate gets its own context + terminal
// They message each other directly via shared task list
// Use Shift+Down to cycle between teammate terminals (in-process mode)
// Or launch with --display split-panes for tmux/iTerm2 split view

// A teammate sends a message to another teammate by name:
@frontend-agent The API endpoint is POST /api/auth/login
Request body: { email: string, password: string }
Response: { token: string, user: { id, email, role } }
Ready for you to wire up the form.

#!/bin/bash
# Run Claude Code headlessly in CI to review a PR diff

# --bare: reproducible, skips local config discovery
# --output-format json: machine-readable result
# ANTHROPIC_API_KEY must be set as a CI secret

DIFF=$(git diff origin/main...HEAD)

RESULT=$(claude -p \
  --bare \
  --output-format json \
  "Review this diff for bugs and security issues. Be concise.

$DIFF")

# Parse result field from JSON output
echo "$RESULT" | jq -r '.result'

# Exit non-zero if Claude found critical issues
if echo "$RESULT" | jq -r '.result' | grep -qi "critical"; then
  exit 1
fi

# Get schema-conformant output (Claude Code v2+)
claude -p "Analyse this file and return findings" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "severity": {"type": "string", "enum": ["low","medium","high","critical"]},
      "findings": {"type": "array", "items": {"type": "string"}},
      "safe_to_merge": {"type": "boolean"}
    },
    "required": ["severity","findings","safe_to_merge"]
  }'

# Continue a previous session by ID
SESSION_ID=$(cat .claude-session-id)
claude -p "Continue where you left off" --resume "$SESSION_ID"