Architecture Overview — What's Actually in the Claude Code Repository

If you navigate to github.com/anthropics/claude-code expecting to find the source code behind Claude Code's terminal UI, context window management, or tool execution engine, you'll be disappointed. This is the most common misconception about this repository — and the starting point for understanding what it actually contains.

This repository is the public-facing extensibility and operations layer for Claude Code. It houses the official plugin ecosystem, the GitHub automation infrastructure that manages thousands of issues, a DevContainer sandbox configuration, and enterprise deployment examples. It's the surface area where Claude Code meets the outside world.

What This Repository Is (and Isn't)

Claude Code the product is distributed as a closed-source npm package (@anthropic-ai/claude-code) and native installers. The readme makes this clear — it points users to installation methods and official documentation, not to source files:

README.md#L7

The actual code for context window management, the terminal UI, the tool execution sandbox, model routing, and everything that makes Claude Code work lives elsewhere. This repository is the companion — it demonstrates extensibility, automates operations, and provides reference configurations.

Think of it like this: if Claude Code were an operating system, this repository would contain the app store catalog, the system administration scripts, the container configuration, and the enterprise deployment guides. Not the kernel.

Repository Map: Four Zones

The repository divides cleanly into four functional zones. Here's the territory:

graph TD
    ROOT["anthropics/claude-code"] --> PLUGINS["plugins/<br/>Extension Ecosystem"]
    ROOT --> AUTOMATION[".github/workflows/ + scripts/<br/>Automation Infrastructure"]
    ROOT --> SANDBOX[".devcontainer/<br/>Sandbox Environment"]
    ROOT --> EXAMPLES["examples/<br/>Enterprise Configuration"]
    ROOT --> COMMANDS[".claude/commands/<br/>Repo-Level Commands"]

    PLUGINS --> P1["13 official plugins"]
    PLUGINS --> P2["Commands, agents, skills, hooks"]

    AUTOMATION --> A1["12 GitHub Actions workflows"]
    AUTOMATION --> A2["TypeScript lifecycle scripts"]
    AUTOMATION --> A3["Sandboxed CLI wrappers"]

    SANDBOX --> S1["Dockerfile + firewall"]
    SANDBOX --> S2["Network restrictions"]

    EXAMPLES --> E1["3 enterprise settings profiles"]
    EXAMPLES --> E2["Hook examples"]

    style PLUGINS fill:#4CAF50,color:#fff
    style AUTOMATION fill:#2196F3,color:#fff
    style SANDBOX fill:#FF9800,color:#fff
    style EXAMPLES fill:#9C27B0,color:#fff
    style COMMANDS fill:#607D8B,color:#fff

Zone	Path	What Lives Here
Plugins	plugins/	13 official plugins with commands, agents, skills, hooks
Marketplace	.claude-plugin/	Plugin registry manifest for discovery
Automation	.github/workflows/ + scripts/	12 workflows, lifecycle scripts, sandboxed CLI wrappers
Sandbox	.devcontainer/	Docker + iptables firewall for isolated execution
Enterprise	examples/settings/	Three deployment profiles (lax, strict, bash-sandbox)
Repo Commands	.claude/commands/	Slash commands specific to this repository's operations

Tip: The .claude/commands/ directory contains commands used by this repository itself (triage, deduplication) — not plugin commands. Plugin commands live inside each plugin's commands/ directory. This distinction matters when you're building your own setup.

The Plugin Marketplace

The marketplace manifest at .claude-plugin/marketplace.json registers all 13 official plugins across four categories:

Category	Plugins	Purpose
development	agent-sdk-dev, claude-opus-4-5-migration, feature-dev, frontend-design, plugin-dev, ralph-wiggum	Building features, migrating code, creating plugins
productivity	code-review, commit-commands, hookify, pr-review-toolkit	Automating workflows, reviewing PRs, git operations
learning	explanatory-output-style, learning-output-style	Educational modes that inject teaching context
security	security-guidance	Runtime security pattern monitoring

Each plugin entry in the manifest provides a name, description, source path, category, and optional version/author metadata. The source field uses relative paths (./plugins/feature-dev), tying the marketplace registry to the directory structure:

.claude-plugin/marketplace.json#L62-L71

The marketplace schema ("$schema": "https://anthropic.com/claude-code/marketplace.schema.json") hints at a broader plugin marketplace infrastructure beyond this repository. Users install plugins via the /plugin command inside Claude Code, and this manifest is one discovery source.

The Plugin Component Model

Every plugin follows a convention-over-configuration architecture with five possible component types. A plugin only needs to include the components it uses:

flowchart LR
    MANIFEST[".claude-plugin/<br/>plugin.json"] --> DISCOVERY["Auto-Discovery<br/>Engine"]
    COMMANDS["commands/<br/>*.md"] --> DISCOVERY
    AGENTS["agents/<br/>*.md"] --> DISCOVERY
    SKILLS["skills/<br/>*/SKILL.md"] --> DISCOVERY
    HOOKS["hooks/<br/>hooks.json"] --> DISCOVERY
    MCP[".mcp.json"] --> DISCOVERY

    DISCOVERY --> REGISTER["Component<br/>Registration"]

    style MANIFEST fill:#FF5722,color:#fff
    style DISCOVERY fill:#3F51B5,color:#fff

The canonical plugin structure, documented in the plugin-dev skill at plugins/plugin-dev/skills/plugin-structure/SKILL.md#L22-L37, is:

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagent definitions (.md files)
├── skills/                   # Agent skills (subdirectories)
│   └── skill-name/
│       └── SKILL.md
├── hooks/
│   └── hooks.json           # Event handler configuration
├── .mcp.json                # MCP server definitions
└── scripts/                 # Helper scripts and utilities

The minimum viable plugin is just a plugin.json with a name field. Here's the feature-dev plugin's manifest — it's nine lines:

plugins/feature-dev/.claude-plugin/plugin.json#L1-L9

A critical design detail: all intra-plugin path references use ${CLAUDE_PLUGIN_ROOT} rather than hardcoded paths. This environment variable resolves to wherever the plugin is installed, making plugins portable across installation methods and operating systems. You'll see this pattern everywhere in hook configurations and script references.

Component Types at a Glance

Before we dive deep into each component type in the next article, here's a quick orientation:

Component	Format	Discovery	Invocation
Commands	.md with YAML frontmatter	All .md in commands/	User types /command-name
Agents	.md with YAML frontmatter	All .md in agents/	Orchestrated by commands or Claude
Skills	SKILL.md in subdirectories	All SKILL.md in skills/*/	Auto-activated by context
Hooks	JSON in hooks/hooks.json	Loaded at plugin enable	Event-driven (PreToolUse, Stop, etc.)
MCP Servers	JSON in .mcp.json	Loaded at plugin enable	Tool calls from Claude

The five types form a spectrum from explicit user control (commands) to fully automatic behavior (skills and hooks). This layered design lets plugin authors choose the right level of user involvement for each capability.

What Documentation Gets Wrong

Several documentation sources — including auto-generated wikis — conflate this repository with Claude Code's internals. To be explicit about what you will not find here:

• No context window management code — that's in the closed-source npm package
• No terminal UI implementation — same
• No tool execution engine — the sandbox and permission system are internal
• No model routing logic — how Claude Code selects between Haiku, Sonnet, and Opus is not here
• No conversation state management — session handling is internal

What you will find is the extension surface that Claude Code exposes: how to write plugins that Claude Code loads, how to configure hooks that Claude Code executes, and how to set up enterprise policies that Claude Code enforces. The boundary is clear: this repository defines what Claude Code should do in specific contexts; the closed-source core defines how it does it.

What's Next

With the map drawn, we're ready to explore the terrain. In Part 2, we'll crack open the plugin system and examine each component type in detail — the YAML frontmatter that configures commands and agents, the auto-activation mechanism that powers skills, and the event-driven hook system with its exit code protocol. We'll work with real examples from the 13 official plugins, starting with the feature-dev workflow that orchestrates parallel AI agents through a seven-phase development process.