DOC: Claude Code Architecture Deep Dive - Partner SDE Research

1. Overall Architecture

Claude Code is Anthropic's official CLI for Claude - an agentic coding tool that lives in the terminal.

Core Structure

claude-code/
├── .claude/                    # Project configuration
│   └── commands/               # Local custom commands
├── .claude-plugin/
│   └── marketplace.json        # Plugin registry (13 plugins)
├── plugins/                    # Production plugins
│   ├── agent-sdk-dev/          # SDK scaffolding
│   ├── code-review/            # Automated PR review
│   ├── feature-dev/            # 7-phase workflow
│   ├── hookify/                # Custom rule engine
│   ├── ralph-wiggum/           # Self-referential loops
│   └── [8 more plugins]
├── examples/hooks/             # Hook script examples
└── scripts/                    # Utility scripts

Key Entry Points

1. CLI: Users invoke claude in terminal
2. GitHub Actions: claude.yml triggers on @claude mentions
3. Plugin System: Auto-discovery via marketplace.json

Technology Stack

• Node.js 18+ (core CLI)
• Python 3.7+ (hooks/extensions)
• TypeScript (automation)
• GitHub Actions (CI/CD)

2. Plugin Architecture

Plugin Structure

plugin-name/
├── .claude-plugin/plugin.json   # Metadata
├── commands/*.md                # Slash commands
├── agents/*.md                  # Agent system prompts
├── skills/skill-name/SKILL.md   # Progressive disclosure
├── hooks/hooks.json             # Event handlers
└── .mcp.json                    # MCP server config

Command Definition (Markdown + YAML)

---
allowed-tools: Bash(git:*), Edit(*), Read
description: Create a git commit
---
[System prompt markdown]

Agent Architecture

• Agents are specialized Claude instances with focused prompts
• Pattern: code-explorer, code-architect, code-reviewer
• Run in parallel for distributed analysis
• Confidence-based filtering (≥80 threshold)

13 Production Plugins

| Plugin | Purpose |
|--------|---------|
| feature-dev | 7-phase feature workflow |
| code-review | Multi-agent PR review |
| hookify | Custom rule engine |
| ralph-wiggum | Autonomous iteration loops |
| security-guidance | Pattern detection |
| plugin-dev | Development toolkit |
| agent-sdk-dev | SDK scaffolding |
| frontend-design | High-quality UI generation |

3. Tool System

Built-in Tools

• Bash - Shell commands with filtering (Bash(git:*))
• Read/Write/Edit - File operations
• Glob/Grep - Search operations
• WebFetch/WebSearch - Web access
• Task - Subagent spawning
• TaskCreate/Update/Get/List - Task management

MCP Integration (Model Context Protocol)

• 4 transport types: stdio, SSE, HTTP, WebSocket
• Tool naming: mcp__plugin_<name>_<server>__<tool>
• Auto-discovery at plugin load
• OAuth and Bearer token authentication

Permission Model

{
  "allowedTools": ["Read", "Bash(git:*)"],
  "disallowedTools": ["Bash(rm:*)"]
}

Bash Pattern Matching

• Bash(git:*) - All git commands
• Bash(npm install:*) - Specific npm commands
• Bash(* install) - Wildcard patterns
• Shell injection prevention via continuation validation

Closing - created in wrong repo

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.