Claude Code Overview

Relevant source files

• CHANGELOG.md
• LICENSE.md
• README.md
• demo.gif

Purpose and Scope

This document provides a technical introduction to the Claude Code codebase, describing its dual nature as both a developer CLI tool and a GitHub automation platform. It covers the core architectural components, execution modes, and how major subsystems interact. For detailed information on specific subsystems, refer to:

• System architecture details: System Architecture
• Installation and user-facing features: User Guide
• Internal component documentation: Core Systems
• Plugin ecosystem: Official Plugins
• GitHub automation workflows: GitHub Automation
• Development environment setup: Development Environment

What is Claude Code

Claude Code is an agentic coding tool distributed as both a standalone CLI application and a reusable agent system for GitHub automation. The repository at https://github.com/anthropics/claude-code serves two primary functions:

1. Developer CLI Tool: An interactive terminal application (claude command) that provides an AI coding assistant with natural language interaction, file operations, bash execution, and session management.

2. GitHub Automation Platform: A collection of GitHub Actions workflows that use the same agent system to automate issue triage, duplicate detection, stale issue management, and oncall escalation.

The shared agent architecture enables both use cases to leverage the same tools, permission systems, and plugin infrastructure.

Sources: README.md1-73 CHANGELOG.md1-2200

System Architecture Overview

The following diagram shows the primary architectural layers and their interactions:

Sources: README.md1-73 CHANGELOG.md222-225 CHANGELOG.md372-373

Entry Points and Execution Modes

Claude Code provides multiple execution modes depending on how it's invoked:

CLI Command Structure

Interactive Mode (default): Starts a REPL session where users can send messages, execute slash commands (e.g., /help, /model, /compact), and interact with Claude iteratively. Session state is preserved in ~/.claude/sessions/.

Non-interactive Mode (-p flag): Executes a single prompt and exits. Used for scripting and GitHub Actions workflows.

Session Management: The --resume flag allows resuming previous conversations by session ID, custom title, or interactive picker. Sessions can be forked with --fork to create branches from previous states.

Worktree Isolation (--worktree flag): Creates an isolated git worktree for experimentation, enabling safe parallel development without affecting the main branch.

Sources: CHANGELOG.md5-7 CHANGELOG.md156-157 CHANGELOG.md279-280 CHANGELOG.md359-360

GitHub Actions Workflows

The repository includes automated workflows that run the same agent system in headless mode:

These workflows execute Claude Code in non-interactive mode (-p flag) with specialized prompts for issue classification, duplicate detection, and lifecycle management. See GitHub Automation for detailed workflow documentation.

Sources: CHANGELOG.md1-2200 GitHub workflows structure from Diagram 3

Core Subsystems

Agent System

The agent architecture supports multiple orchestration patterns:

• Main Agent: User-facing conversation handler that processes messages and executes tools
• Subagents: Spawned via TaskTool for parallel or background execution, optionally running in isolated git worktrees
• Agent Teams: Experimental multi-agent collaboration using tmux for inter-agent communication

Agents can be customized through .claude/agents/*.md files with frontmatter defining model, tools, memory scope, and hooks. See Agent System & Subagents for implementation details.

Sources: CHANGELOG.md5-8 CHANGELOG.md222-224 CHANGELOG.md566-567

Tool System

Tools provide capabilities for file operations, shell execution, web search, and external integrations:

Tool	Purpose	Permission Required
BashTool	Execute shell commands	Bash classifier
FileReadTool	Read file contents	Read classifier
FileWriteTool	Create/overwrite files	Write classifier
FileEditTool	Modify file ranges	Edit classifier
TaskTool	Spawn subagents	Task classifier
WebSearch	Search web content	WebSearch classifier
MCPTools	External MCP servers	Per-server rules

Each tool invocation passes through the permission classifier, which applies configured rules (allow, ask, or deny). See Tool System & Permissions for complete tool documentation.

Sources: CHANGELOG.md243-244 CHANGELOG.md562-563

Context Window Management

Context management operates on multiple levels:

The system tracks token usage continuously and automatically triggers compaction when approaching context limits. Compaction sends conversation history to the API for intelligent summarization while preserving important context. The memory system stores persistent facts across sessions. See Context Window & Compaction for technical details.

Sources: CHANGELOG.md329 CHANGELOG.md400 CHANGELOG.md452

Plugin and Skill System

Extensions are loaded from multiple sources with hierarchical discovery:

Plugin Locations:

• Marketplace definitions: plugins/marketplace/marketplace.json
• User plugins: ~/.claude/plugins/
• Project plugins: .claude/plugins/
• Additional directories via --add-dir flag

Skill Locations:

• User skills: ~/.claude/skills/
• Project skills: .claude/skills/
• Plugin-provided skills: plugins/*/skills/*.md

Skills use SKILL.md format with YAML frontmatter defining invocation patterns, arguments, and required permissions. Plugins extend functionality through custom commands, agents, hooks, and MCP servers. See Plugin System and Skill System for implementation details.

Sources: CHANGELOG.md542-544 CHANGELOG.md226 CHANGELOG.md120

Configuration Hierarchy

Settings are loaded and merged from multiple sources in priority order:

Enterprise settings can enforce organizational policies through managed-only modes (allowManagedHooksOnly, allowManagedPermissionRulesOnly, strictKnownMarketplaces). See Configuration Management for complete settings reference.

Sources: CHANGELOG.md28 CHANGELOG.md536

Development Environment

The repository includes a pre-configured DevContainer for development:

Key Components:

• Base Image: node:20 with development tools (Dockerfile)
• Security: init-firewall.sh enforces network isolation with allowlisted domains
• Orchestration: run_devcontainer_claude_code.ps1 supports Docker/Podman backends
• Configuration: devcontainer.json defines container lifecycle and volume mounts

The firewall restricts network access to GitHub, npm, Anthropic API, and telemetry services, providing defense-in-depth for sandbox development. See Development Environment for setup details.

Sources: Diagram 4 (Development Environment and Security Architecture)

Session Management and State

Sessions are the primary unit of conversation state:

Session Storage:

• Location: ~/.claude/sessions/<session-id>/
• Format: JSON transcript files with message history and metadata
• Management: Resume, fork, rename, clear operations

Session Lifecycle:

1. Creation: New session on claude invocation without --resume
2. Persistence: Automatic save after each turn
3. Compaction: Transparent history pruning when approaching token limits
4. Resumption: Restore via --resume <id> or interactive picker

Sessions can be linked to GitHub PRs (via --from-pr) and support remote access for OAuth users. See Session Management for complete documentation.

Sources: CHANGELOG.md279-280 CHANGELOG.md329 CHANGELOG.md359-360

Tool Permission Model

The permission system operates in three layers:

Rule Syntax:

• Bash(*): Allow all bash commands
• Bash(git *): Allow git commands with any arguments
• Write: Allow all file writes
• Read(/etc/*): Allow reads from /etc directory

Rules support wildcard patterns (*) and can be scoped to user, project, or session level. Managed settings can enforce centralized permission policies. See Tool System & Permissions for rule specification.

Sources: CHANGELOG.md562-563 CHANGELOG.md449 CHANGELOG.md470-471

MCP Server Integration

MCP (Model Context Protocol) servers extend Claude Code with external tool integrations:

Transport Types:

• stdio: Local process communication
• HTTP: REST API endpoints
• SSE: Server-sent events for streaming

Management Commands:

• claude mcp add <url>: Register new MCP server
• claude mcp list: Show configured servers
• claude mcp get <name>: Display server details

MCP servers provide tools, prompts, and resources that are discovered at runtime and made available to the agent. OAuth flows are supported for authenticated servers. See MCP Server Integration for protocol details.

Sources: CHANGELOG.md106 CHANGELOG.md252 CHANGELOG.md564

Hook System

Hooks provide lifecycle interception points for custom behavior:

Hook Type	Trigger Point	Common Uses
SessionStart	Session initialization	Load project context
PreToolUse	Before tool execution	Security validation
PostToolUse	After tool execution	Logging, notifications
Stop	Session termination	Cleanup operations
TeammateIdle	Subagent waiting	Coordination logic
TaskCompleted	Subagent finished	Result processing
ConfigChange	Settings modified	Audit logging

Hooks are defined in .claude/hooks/*.sh (user/project) or plugin-provided configurations. They can block execution (exit code 2), modify context, or inject additional information. See Hook System for implementation details.

Sources: CHANGELOG.md205-206 CHANGELOG.md24 CHANGELOG.md566-567

Release and Distribution

Claude Code is distributed through multiple channels:

Installation Methods:

• Native installers: curl -fsSL https://claude.ai/install.sh | bash (recommended)
• Homebrew: brew install --cask claude-code
• WinGet: winget install Anthropic.ClaudeCode
• npm: npm install -g @anthropic-ai/claude-code (deprecated)

Update Channels:

• stable: Production releases with full testing
• latest: Bleeding-edge features and fixes

Auto-update is supported for native installations. The changelog tracks all features, fixes, and breaking changes chronologically. See Feature Evolution & Release History for version history.

Sources: README.md14-44 CHANGELOG.md390 CHANGELOG.md519