---
name: claude-code-patterns
last_verified: 2026-04-02
description: "Architecture patterns from the Claude Code CLI for building AI-powered developer tools. Covers tool registry systems, permission models, agent orchestration (sub-agents, swarms, teams), skill/plugin architectures, CLI-as-React-app (Ink), deferred tool loading, bridge patterns for IDE integration, and conversation state management. Triggers on: build CLI agent, tool system design, agent orchestration pattern, skill system architecture, permission system, IDE bridge, CLI React, Ink framework, AI developer tool, agent tool registry, or any question about building AI-powered CLI tools or agent systems."
---

# Claude Code Architecture Patterns

Architektur-Patterns destilliert aus der Analyse des geleakten Claude Code CLI Source Codes (2026-03-31 Leak). Alle Informationen stammen aus der oeffentlich dokumentierten Struktur -- kein Quellcode wird reproduziert.

**Legal Disclaimer:** Diese Patterns sind allgemeine Software-Engineering-Patterns (Tool Registry, Permission System, Agent Orchestration). KEINEN Code aus dem Leak kopieren oder veroeffentlichen. Nur als Architektur-Referenz verwenden.

---

## Architecture Overview

| Aspekt | Technologie |
|--------|------------|
| Runtime | Bun (schnelle JS-Runtime mit nativem TypeScript) |
| Terminal UI | React + Ink (React-Renderer fuer CLI, KEIN Browser) |
| CLI Parsing | Commander.js (mit extra-typings) |
| Schema Validation | Zod v4 |
| Code Search | ripgrep (via GrepTool) |
| Protocols | MCP SDK, LSP |
| API | Anthropic SDK |
| Telemetry | OpenTelemetry + gRPC |
| Auth | OAuth 2.0, JWT, macOS Keychain |
| Feature Flags | GrowthBook |
| Scale | ~1.900 Files, 512.000+ Lines of Code |

---

## Pattern 1: Tool Registry

**Problem:** Ein AI-Agent braucht erweiterbare Faehigkeiten, ohne dass der Core-Code bei jeder neuen Faehigkeit geaendert werden muss.

**Loesung:** Jedes Tool ist ein selbst-contained Modul mit drei Teilen:
1. **Input Schema** (Zod) -- was das Tool erwartet
2. **Permission Model** -- welche Berechtigungen noetig sind
3. **Execution Logic** -- was das Tool tut

**Implementierung in Claude Code:**
- `Tool.ts` (~29K Zeilen) definiert Basis-Types und Interfaces
- ~40 Tools registriert: BashTool, FileReadTool, FileWriteTool, FileEditTool, GlobTool, GrepTool, WebFetchTool, AgentTool, SkillTool, MCPTool, LSPTool, etc.
- Jedes Tool definiert seine eigenen Permission-Requirements
- `ToolSearchTool` ermoeglicht Deferred Discovery (nicht alle Tools beim Start geladen)

**Key Insight:** Tools sind die Einheit der Faehigkeit. Ein neues Tool hinzufuegen erweitert den Agent, ohne Core-Logik zu aendern.

**Anwendbar wenn:** Du ein Plugin/Tool-System fuer einen AI-Agent baust.

### Implementierungs-Template

```typescript
// Jedes Tool implementiert dieses Interface
interface Tool {
  name: string;
  description: string;
  inputSchema: ZodSchema;       // Was das Tool erwartet
  permissionModel: PermissionConfig; // Welche Rechte noetig sind
  execute(input: ToolInput): Promise<ToolOutput>; // Was es tut
}

// Registry verwaltet alle Tools
class ToolRegistry {
  private tools: Map<string, Tool> = new Map();

  register(tool: Tool): void { ... }
  get(name: string): Tool | undefined { ... }
  list(): Tool[] { ... }

  // Deferred Loading: Tools erst laden wenn gebraucht
  async loadDeferred(query: string): Promise<Tool[]> { ... }
}
```

---

## Pattern 2: Permission System (Cross-Cutting Concern)

**Problem:** Verschiedene Tools haben verschiedene Risiko-Level. Manche duerfen automatisch laufen, andere brauchen User-Bestaetigung.

**Loesung:** Permissions als Cross-Cutting Concern, geprueft VOR jeder Tool-Ausfuehrung, nicht innerhalb jedes Tools.

**Implementierung in Claude Code:**
- `hooks/toolPermission/` -- zentraler Permission-Check
- Prueft bei JEDER Tool-Invocation
- Modi: `default` (User fragen), `plan` (nur Lesen), `bypassPermissions` (alles erlaubt), `auto` (automatisch)
- Per-Tool Permission-Konfiguration moeglich

**Key Insight:** Permission ist ein Querschnittsthema. Jedes Tool deklariert seine Anforderungen, die Permission-Engine entscheidet.

**Anwendbar wenn:** Du ein Agent-System mit unterschiedlichen Sicherheitsstufen baust.

### Permission Level Matrix

| Level | Lesen | Schreiben | Shell | Netzwerk | Beispiel |
|-------|-------|-----------|-------|----------|---------|
| Read-Only | Ja | Nein | Nein | Nein | Plan Mode |
| Default | Ja | Mit Frage | Mit Frage | Mit Frage | Normal Mode |
| Auto | Ja | Ja (safe) | Mit Frage | Mit Frage | Trusted Workspace |
| Bypass | Ja | Ja | Ja | Ja | CI/CD Pipeline |

---

## Pattern 3: Agent Orchestration (Recursive Delegation)

**Problem:** Komplexe Aufgaben koennen nicht von einem einzigen Agent-Call geloest werden.

**Loesung:** Agents koennen Sub-Agents spawnen, die wiederum Sub-Agents spawnen koennen. Jeder Agent hat eigenen Kontext und Tool-Zugriff.

**Implementierung in Claude Code:**
- `AgentTool`: Spawnt autonome Sub-Agents
- `coordinator/`: Multi-Agent-Koordination
- `TeamCreateTool` / `TeamDeleteTool`: Team-Level parallele Arbeit
- `SendMessageTool`: Inter-Agent-Messaging

**Orchestrierungs-Patterns:**

```
1. Sequential Delegation:
   Main Agent -> Sub-Agent A -> Sub-Agent B -> Result

2. Parallel Fan-Out:
   Main Agent -> [Sub-Agent A, Sub-Agent B, Sub-Agent C] -> Merge Results

3. Team Pattern:
   Main Agent -> Create Team -> [Agent 1, Agent 2] work in parallel
                              -> Inter-Agent Messaging
                              -> Team Result

4. Recursive:
   Agent -> Sub-Agent -> Sub-Sub-Agent -> ... (mit Depth-Limit)
```

**Key Insight:** Agents sind rekursiv -- ein Agent kann Agents spawnen, die Agents spawnen. Das ermoeglicht emergente Problemloesung.

**Anwendbar wenn:** Du Multi-Agent-Systeme baust (z.B. Code-Review + Fix + Test parallel).

---

## Pattern 4: Skill System (Reusable Knowledge)

**Problem:** Bestimmte Workflows wiederholen sich (z.B. "X-Post optimieren", "PR erstellen"). Das Wissen sollte wiederverwendbar sein.

**Loesung:** Skills sind Prompt-Templates + Metadata, die das Verhalten des LLM steuern. Keine Code-Ausfuehrung, sondern Wissens-Injection.

**Implementierung in Claude Code:**
- `skills/` -- Skill-Verzeichnis
- `SkillTool` -- Ausfuehrung via Tool-System
- SKILL.md Dateien mit Frontmatter (name, description, triggers)
- On-Demand geladen, nicht beim Start

**Key Insight:** Skills sind KEIN Code, sondern strukturiertes Wissen. Sie aendern wie der Agent denkt, nicht was er kann.

**Anwendbar wenn:** Du ein System brauchst, in dem Domain-Wissen modular hinzugefuegt werden kann.

### Skill vs Tool vs Command vs Plugin

| Konzept | Einheit von | Wer initiiert | Beispiel |
|---------|------------|---------------|---------|
| **Tool** | Faehigkeit | Agent | FileReadTool, BashTool |
| **Command** | User-Interaktion | User (via /) | /commit, /review |
| **Skill** | Wiederverwendbares Wissen | User oder Agent | x-post-optimizer |
| **Plugin** | Extension | System | Third-Party-Integrationen |

---

## Pattern 5: CLI as React App (Ink)

**Problem:** Terminal-UIs sind komplex (Input-Handling, Layout, State, Rendering). Traditionelle ncurses/blessed-Ansaetze sind fehleranfaellig.

**Loesung:** React + Ink -- derselbe Component-Tree wie im Browser, aber gerendert im Terminal.

**Implementierung in Claude Code:**
- `components/` -- ~140 Ink UI Components
- `hooks/` -- React Hooks fuer Terminal-Interaktion
- `screens/` -- Full-Screen UIs (Doctor, REPL, Resume)
- React State Management fuer UI-State
- Flexbox-Layout im Terminal

**Key Insight:** React's Component-Modell funktioniert hervorragend fuer CLI-UIs. State Management, Lifecycle, und Composition sind dieselben Konzepte.

**Anwendbar wenn:** Du eine interaktive CLI-Anwendung baust, die ueber einfache Prompts hinausgeht.

### Tech Stack fuer CLI-as-React

```
Runtime:     Bun (oder Node.js)
UI:          React + Ink (npm: ink)
CLI Parsing: Commander.js (npm: commander)
Input:       Ink's useInput Hook
Layout:      Ink's Box, Text, Flexbox
State:       React useState/useReducer
Effects:     React useEffect
```

---

## Pattern 6: Bridge Pattern (IDE Integration)

**Problem:** Der Agent soll sowohl als CLI als auch in IDEs (VS Code, JetBrains) funktionieren, ohne den Core zu duplizieren.

**Loesung:** Bidirektionale Bridge zwischen CLI (Brain) und IDE (Thin UI Layer).

**Implementierung in Claude Code:**
- `bridge/bridgeMain.ts` -- Bridge Main Loop
- `bridge/bridgeMessaging.ts` -- Message Protocol
- `bridge/replBridge.ts` -- REPL Session Bridge
- `bridge/jwtUtils.ts` -- JWT-basierte Auth zwischen IDE und CLI
- `bridge/sessionRunner.ts` -- Session-Management

**Key Insight:** Die CLI ist das Gehirn, die IDE ist ein duenner UI-Layer der delegiert. Ein Agent, viele Frontends.

**Anwendbar wenn:** Du einen Agent baust, der in mehreren Umgebungen laufen soll (CLI, IDE, Web).

### Bridge Architecture

```
VS Code Extension <--JWT--> Bridge <--Messages--> CLI Agent
JetBrains Plugin  <--JWT--> Bridge <--Messages--> CLI Agent
                                                     |
                                                  Tool System
                                                  Skill System
                                                  State System
```

---

## Pattern 7: Performance (Parallel Prefetch + Lazy Loading)

**Problem:** Startup-Zeit ist kritisch fuer CLI-Tools. Heavy Dependencies (OTel ~400KB, gRPC ~700KB) verlangsamen den Start.

**Loesung:** Mehrstufige Strategie:

1. **Parallel Prefetch:** MDM-Settings, Keychain-Reads, API-Preconnect parallel starten BEVOR schwere Module evaluiert werden
2. **Lazy Loading:** Heavy Modules erst bei Bedarf via `await import()`
3. **Dead Code Elimination:** Bun's `bun:bundle` Feature Flags strippen ungenutzten Code zur Build-Zeit

**Feature Flags in Claude Code:**
- `PROACTIVE` -- Proaktiver Modus
- `KAIROS` -- Unbekanntes Feature
- `BRIDGE_MODE` -- IDE Bridge
- `DAEMON` -- Daemon-Modus
- `VOICE_MODE` -- Sprach-Input
- `AGENT_TRIGGERS` -- Geplante Trigger
- `MONITOR_TOOL` -- Monitoring

**Key Insight:** In einer CLI ist jede Millisekunde Startup-Zeit sichtbar. Lade nur was du JETZT brauchst.

---

## Pattern 8: Layered State Management

**Problem:** Ein Agent braucht verschiedene Arten von State mit verschiedenen Lifetimes.

**Loesung:** State in Schichten, von kurzlebig bis persistent:

| Schicht | Lifetime | Speicher | Beispiel |
|---------|----------|----------|---------|
| **Conversation** | Eine Session | In-Memory | Aktueller Chat-Verlauf |
| **Task** | Eine Aufgabe | In-Memory + File | Todo-Liste, Fortschritt |
| **Memory** | Permanent | File-System (memdir/) | User-Preferences, Projekt-Kontext |
| **Team Memory** | Shared | Sync-Service | Team-weite Konventionen |

**Implementierung in Claude Code:**
- `state/` -- Zentrales State Management
- `memdir/` -- Persistent Memory (file-basiert, ueberlebt Sessions)
- `tasks/` -- Task-Tracking
- `services/compact/` -- Context-Kompression bei Limit
- `services/extractMemories/` -- Automatische Memory-Extraktion aus Konversationen
- `services/teamMemorySync/` -- Team Memory Synchronisation

**Key Insight:** File-basierte Persistenz ist einfacher und robuster als Datenbank-Dependencies fuer CLI-Tools.

---

## Design Principles (aus der Architektur abgeleitet)

1. **Tools als Einheit der Faehigkeit** -- erweiterbar ohne Core-Aenderung
2. **Commands als Einheit der User-Interaktion** -- / als Namespace
3. **Skills als Einheit des wiederverwendbaren Wissens** -- Prompts, nicht Code
4. **Plugins als Einheit der Extension** -- Third-Party-Integrationen
5. **Agents als Einheit der Delegation** -- rekursiv spawnable
6. **Permissions als Querschnittsthema** -- vor Ausfuehrung geprueft, nicht innerhalb
7. **Alles lazy geladen** -- erst bei Bedarf, nie praeventiv
8. **File-basierte Persistenz** -- keine Datenbank-Dependencies fuer CLI-Tools
9. **Ein Agent, viele Frontends** -- Bridge-Pattern fuer CLI + IDE + Web

---

## Applicability Guide

| Wenn du baust... | Relevante Patterns |
|-------------------|-------------------|
| AI-powered CLI Tool | Alle Patterns, besonders Ink, Tool Registry, Permissions |
| Tool/Plugin-System fuer LLM Agent | Tool Registry, Deferred Loading, Permissions |
| Multi-Agent-Orchestrierung | Agent Orchestration, Team Pattern, Inter-Agent Messaging |
| IDE Extension mit AI | Bridge Pattern, Session Management |
| Skill/Prompt Management | Skill System, Layered State |
| SaaS mit AI-Features | Tool Registry (als API), Permissions, State Management |