dive-into-claude-code-analysis
Analyze and apply architectural patterns from Claude Code's system design for building AI agent systems
How do I install this agent skill?
npx skills add https://github.com/reason-machines/claude-code-skills --skill dive-into-claude-code-analysisIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides architectural guidance and design patterns for building AI agent systems based on an analysis of the Claude Code project. It includes educational code snippets and instructions to download research documentation from GitHub and arXiv.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Dive into Claude Code Analysis
Skill by ara.so — Claude Code Skills collection.
This skill provides expertise in understanding and applying the architectural patterns, design principles, and implementation strategies documented in the VILA-Lab "Dive into Claude Code" analysis — a comprehensive study of Claude Code v2.1.88 (~512K lines of TypeScript across 1,884 files).
What This Project Provides
The Dive into Claude Code project is a systematic analysis that reveals:
- Architectural blueprint: How Claude Code structures its 98.4% deterministic infrastructure around 1.6% AI decision logic
- Design principles: 5 core values → 13 design principles → concrete implementation patterns
- Safety patterns: 7-layer defense-in-depth permission system with graduated trust spectrum
- Context management: 5-stage compaction pipeline for token budget management
- Agent loop implementation: ReAct-pattern while-loop with streaming execution and graceful recovery
- Extensibility mechanisms: 4 graduated extension points (hooks, skills, plugins, MCP)
Installation
# Clone the repository
git clone https://github.com/VILA-Lab/Dive-into-Claude-Code.git
cd Dive-into-Claude-Code
# Read the paper (PDF in repo or arXiv)
open paper/Dive_into_Claude_Code.pdf
# or visit https://arxiv.org/abs/2604.14228
Core Architecture Patterns
The 98/2 Split
Claude Code demonstrates that production AI agents are primarily infrastructure:
- 1.6%: AI decision logic (LLM reasoning, tool selection)
- 98.4%: Deterministic harness (permissions, context management, recovery, routing)
Key insight: The agent loop is a simple while-loop. The engineering complexity lives in the systems around it.
Five Architectural Layers
┌─────────────────────────────────────────┐
│ User & Interfaces (CLI, SDK, IDE) │
├─────────────────────────────────────────┤
│ Agent Loop (queryLoop) │
│ • Context Assembly │
│ • Model Invocation │
│ • Tool Dispatch │
├─────────────────────────────────────────┤
│ Permission System (7 modes, deny-first) │
├─────────────────────────────────────────┤
│ Tools & Extensions (54 base + MCP) │
├─────────────────────────────────────────┤
│ State & Execution Environment │
└─────────────────────────────────────────┘
Design Principles Framework
The 5 Core Values
// Values that drive all architectural decisions
enum CoreValue {
HumanDecisionAuthority = "human-control",
SafetySecurityPrivacy = "safe-by-default",
ReliableExecution = "does-what-meant",
CapabilityAmplification = "unix-utility-philosophy",
ContextualAdaptability = "evolves-with-trust"
}
The 13 Design Principles
Apply these when designing your AI agent:
- Deny-first with human escalation: Unrecognized actions → escalate to human
- Graduated trust spectrum: 7 permission modes users traverse over time
- Defense in depth: Multiple overlapping safety layers
- Externalized programmable policy: Configs with lifecycle hooks
- Context as scarce resource: 5-stage graduated compaction pipeline
- Append-only durable state: Immutable history logs
- Minimal scaffolding, maximal harness: Invest in operational infrastructure
- Values over rules: Contextual judgment + deterministic guardrails
- Composable multi-mechanism extensibility: 4 extension layers at different costs
- Reversibility-weighted risk assessment: Lighter oversight for reversible actions
- Transparent file-based config: User-visible files over opaque DBs
- Isolated subagent boundaries: Separate context/permissions per subagent
- Graceful recovery and resilience: Silent recovery over hard failures
Implementing the Agent Loop Pattern
Basic ReAct Loop Structure
async function* agentLoop(
initialPrompt: string,
context: AgentContext,
permissions: PermissionSystem
): AsyncGenerator<AgentEvent> {
let turnCount = 0;
const MAX_TURNS = 25;
const conversationHistory: Message[] = [];
while (turnCount < MAX_TURNS) {
// 1. Context assembly
const assembledContext = await assembleContext(
conversationHistory,
context.workspaceState,
context.availableTools
);
// 2. Five-stage compaction (if needed)
const compactedContext = await compactIfNeeded(
assembledContext,
context.tokenBudget
);
// 3. Model invocation
const modelResponse = await callModel({
messages: compactedContext.messages,
tools: compactedContext.availableTools,
streaming: true
});
// 4. Tool dispatch
const toolCalls = extractToolCalls(modelResponse);
if (toolCalls.length === 0) {
yield { type: 'complete', message: modelResponse.content };
break;
}
// 5. Permission gate
const authorizedCalls = await permissions.authorize(toolCalls);
// 6. Execute with streaming
for await (const toolResult of executeTools(authorizedCalls)) {
yield { type: 'tool_result', data: toolResult };
conversationHistory.push({
role: 'tool',
content: toolResult.output
});
}
turnCount++;
}
}
Five-Stage Compaction Pipeline
// Run sequentially, cheapest-first
async function compactIfNeeded(
context: AssembledContext,
tokenBudget: number
): Promise<CompactedContext> {
let current = context;
const currentTokens = estimateTokens(current);
if (currentTokens <= tokenBudget) {
return current;
}
// Stage 1: Budget Reduction (remove low-priority items)
current = await budgetReduction(current, tokenBudget);
if (estimateTokens(current) <= tokenBudget) return current;
// Stage 2: Snip (truncate long individual messages)
current = await snipLongMessages(current, tokenBudget);
if (estimateTokens(current) <= tokenBudget) return current;
// Stage 3: Microcompact (remove whitespace, comments)
current = await microcompact(current);
if (estimateTokens(current) <= tokenBudget) return current;
// Stage 4: Context Collapse (merge related messages)
current = await contextCollapse(current);
if (estimateTokens(current) <= tokenBudget) return current;
// Stage 5: Auto-Compact (LLM-based summarization)
current = await autoCompact(current, tokenBudget);
return current;
}
Permission System Implementation
Seven Permission Modes (Graduated Trust)
enum PermissionMode {
Plan = "plan", // Show what would happen, no execution
Default = "default", // Ask for every action
AcceptEdits = "acceptEdits", // Auto-approve file edits only
Auto = "auto", // ML classifier decides
DontAsk = "dontAsk", // Auto-approve in current directory
BypassPermissions = "bypassPermissions", // Trust completely
Bubble = "bubble" // Internal: defer to parent
}
Deny-First Authorization Pipeline
interface PermissionRule {
scope: 'global' | 'directory' | 'file';
pattern: string;
decision: 'allow' | 'deny' | 'ask';
priority: number;
}
class DenyFirstPermissionSystem {
async authorize(toolCalls: ToolCall[]): Promise<ToolCall[]> {
const authorized: ToolCall[] = [];
for (const call of toolCalls) {
// 1. Pre-filtering: strip denied tools entirely
if (this.isDeniedTool(call.tool)) {
continue;
}
// 2. Evaluate rules (deny-first: broadest deny wins)
const decision = this.evaluateRules(call);
if (decision === 'deny') {
continue;
}
if (decision === 'ask') {
const userApproved = await this.promptUser(call);
if (!userApproved) continue;
}
// 3. Execute hooks (can still block)
const hookResult = await this.runPreToolUseHooks(call);
if (hookResult.blocked) {
continue;
}
authorized.push(call);
}
return authorized;
}
private evaluateRules(call: ToolCall): 'allow' | 'deny' | 'ask' {
const matchingRules = this.rules
.filter(rule => this.matches(rule, call))
.sort((a, b) => b.priority - a.priority);
// Deny-first: any deny rule wins
const denyRule = matchingRules.find(r => r.decision === 'deny');
if (denyRule) return 'deny';
const allowRule = matchingRules.find(r => r.decision === 'allow');
if (allowRule) return 'allow';
return 'ask'; // Default: escalate to human
}
}
Seven Independent Safety Layers
class DefenseInDepth {
async executeTool(call: ToolCall, context: ExecutionContext): Promise<ToolResult> {
// Layer 1: Tool pre-filtering (denied tools removed from tool pool)
// (already applied during context assembly)
// Layer 2: PreToolUse hooks
await this.runHooks('PreToolUse', call);
// Layer 3: Deny-first rule evaluation
const permissionDecision = await this.permissions.authorize([call]);
if (permissionDecision.length === 0) {
throw new Error('Permission denied');
}
// Layer 4: Auto-mode classifier (if in auto mode)
if (context.mode === PermissionMode.Auto) {
const classifierResult = await this.classifier.evaluate(call);
if (!classifierResult.safe) {
const userOverride = await this.promptUser(call);
if (!userOverride) throw new Error('Classifier rejected');
}
}
// Layer 5: Reversibility assessment
const risk = this.assessReversibility(call);
if (risk === 'irreversible' && !call.userApproved) {
throw new Error('Irreversible action requires explicit approval');
}
// Layer 6: Resource limits (timeout, memory, file size)
const result = await this.executeWithLimits(call, {
timeout: 30000,
maxMemory: 512 * 1024 * 1024,
maxFileSize: 10 * 1024 * 1024
});
// Layer 7: PostToolUse hooks (can still intervene)
await this.runHooks('PostToolUse', call, result);
return result;
}
}
Extensibility Patterns
Four Graduated Extension Mechanisms
// Cost spectrum: Hooks < Skills < Plugins < MCP
// 1. HOOKS (zero context cost)
interface Hook {
event: HookEvent; // 27 available events
handler: string | Function;
blocking?: boolean;
}
// Example: PreToolUse hook
const securityHook: Hook = {
event: 'PreToolUse',
handler: async (call: ToolCall) => {
if (call.tool === 'execute_command' && call.args.command.includes('rm -rf')) {
return { allow: false, reason: 'Dangerous command blocked' };
}
},
blocking: true
};
// 2. SKILLS (low context cost - injected only when triggered)
interface Skill {
name: string;
description: string;
triggers: string[];
content: string; // Markdown with examples
}
// 3. PLUGINS (medium cost - loaded at startup)
interface PluginManifest {
name: string;
components: {
commands?: CommandDefinition[];
agents?: AgentDefinition[];
skills?: Skill[];
hooks?: Hook[];
mcpServers?: MCPServerConfig[];
settings?: Setting[];
};
}
// 4. MCP (high cost - persistent tool pool expansion)
interface MCPServerConfig {
name: string;
command: string;
args?: string[];
env?: Record<string, string>;
}
Tool Pool Assembly
async function assembleToolPool(context: AgentContext): Promise<Tool[]> {
// Step 1: Base enumeration (up to 54 tools)
let tools = [...BASE_TOOLS];
// Step 2: Mode filtering (e.g., plan mode removes write tools)
tools = filterByMode(tools, context.mode);
// Step 3: Deny pre-filtering (remove denied tools)
tools = tools.filter(tool => !isDenied(tool, context.permissions));
// Step 4: MCP integration (add external tools)
const mcpTools = await loadMCPTools(context.mcpServers);
tools.push(...mcpTools);
// Step 5: Deduplication (by tool name)
tools = deduplicateTools(tools);
return tools;
}
Session Persistence Pattern
Append-Only State Management
interface SessionState {
id: string;
createdAt: number;
events: SessionEvent[]; // Append-only
metadata: {
workspaceRoot: string;
permissionMode: PermissionMode;
trustLevel: number;
};
}
class SessionPersistence {
// Never mutate history - only append
async appendEvent(sessionId: string, event: SessionEvent): Promise<void> {
const session = await this.loadSession(sessionId);
session.events.push({
...event,
timestamp: Date.now(),
sequenceNumber: session.events.length
});
await this.saveSession(session);
}
// Replay from events for recovery
async replaySession(sessionId: string): Promise<AgentContext> {
const session = await this.loadSession(sessionId);
let context = this.createInitialContext(session.metadata);
for (const event of session.events) {
context = await this.applyEvent(context, event);
}
return context;
}
}
Configuration Patterns
Transparent File-Based Config
// .claude/config.json
interface ClaudeConfig {
permissionMode: PermissionMode;
customInstructions?: string;
deniedTools?: string[];
allowedDirectories?: string[];
hooks?: Hook[];
mcpServers?: MCPServerConfig[];
}
// CLAUDE.md hierarchy (most specific wins)
// workspace/subdir/CLAUDE.md > workspace/CLAUDE.md > ~/.claude/CLAUDE.md
async function loadConfig(workspacePath: string): Promise<ClaudeConfig> {
const configs: ClaudeConfig[] = [];
// Load from most general to most specific
const homeClaude = await loadIfExists('~/.claude/CLAUDE.md');
if (homeClaude) configs.push(homeClaude);
const workspaceClaude = await loadIfExists(path.join(workspacePath, 'CLAUDE.md'));
if (workspaceClaude) configs.push(workspaceClaude);
const configJson = await loadIfExists(path.join(workspacePath, '.claude/config.json'));
if (configJson) configs.push(configJson);
// Merge (most specific wins)
return mergeConfigs(configs);
}
Subagent Delegation Pattern
Isolated Context Boundaries
interface SubagentConfig {
isolatedContext: boolean; // Always true in Claude Code
inheritPermissions: boolean; // Always false
parentVisibility: 'none' | 'summary' | 'full';
}
async function delegateToSubagent(
task: string,
parentContext: AgentContext
): Promise<SubagentResult> {
// Create isolated context (never inherits permissions)
const subagentContext: AgentContext = {
workspaceRoot: parentContext.workspaceRoot,
permissionMode: PermissionMode.Default, // Start at lowest trust
conversationHistory: [], // Empty history
availableTools: assembleToolPool({ /* fresh context */ }),
tokenBudget: parentContext.tokenBudget,
parentSessionId: null // No access to parent
};
// Run isolated agent loop
const result = await runAgentLoop(task, subagentContext);
// Return only summary to parent (not full context)
return {
summary: result.summary,
outcome: result.outcome,
// Full conversation history NOT returned
};
}
Graceful Recovery Patterns
Five Recovery Strategies
class RecoverySystem {
async executeWithRecovery(call: ToolCall): Promise<ToolResult> {
try {
return await this.execute(call);
} catch (error) {
// Strategy 1: Max output token escalation
if (error.code === 'OUTPUT_TOO_LONG') {
return await this.retryWithIncreasedTokens(call, {
attempt: 1,
maxAttempts: 3,
tokenMultiplier: 2
});
}
// Strategy 2: Reactive compaction
if (error.code === 'CONTEXT_TOO_LONG') {
const compacted = await this.compactContext();
return await this.execute(call);
}
// Strategy 3: Streaming fallback
if (error.code === 'STREAMING_FAILED') {
return await this.executeNonStreaming(call);
}
// Strategy 4: Fallback model
if (error.code === 'MODEL_UNAVAILABLE') {
return await this.executeWithFallbackModel(call);
}
// Strategy 5: Graceful degradation
if (error.code === 'TOOL_UNAVAILABLE') {
return {
success: false,
message: `Tool ${call.tool} unavailable, continuing with reduced capabilities`
};
}
throw error; // Unrecoverable
}
}
}
Common Patterns from the Analysis
Pattern: Context Assembly with Hooks
async function assemble(context: AgentContext): Promise<AssembledContext> {
// 1. Run PreContextAssembly hooks
await runHooks('PreContextAssembly', context);
// 2. Gather base context
let assembled = {
messages: [...context.conversationHistory],
tools: await assembleToolPool(context),
systemPrompt: await loadSystemPrompt(context)
};
// 3. Inject custom instructions (CLAUDE.md)
const customInstructions = await loadCustomInstructions(context.workspaceRoot);
if (customInstructions) {
assembled.systemPrompt += '\n\n' + customInstructions;
}
// 4. Inject skills (triggered by user message)
const triggeredSkills = await findTriggeredSkills(
context.lastUserMessage,
context.availableSkills
);
for (const skill of triggeredSkills) {
assembled.messages.push({
role: 'system',
content: skill.content
});
}
// 5. Run PostContextAssembly hooks
assembled = await runHooks('PostContextAssembly', assembled);
return assembled;
}
Pattern: Streaming Tool Execution
async function* streamingToolExecutor(
toolCalls: ToolCall[],
executor: ToolExecutor
): AsyncGenerator<ToolResult> {
// Classify as concurrent-safe or exclusive
const { concurrent, exclusive } = classifyTools(toolCalls);
// Execute concurrent tools in parallel
const concurrentPromises = concurrent.map(call => executor.execute(call));
for await (const result of yieldAsCompleted(concurrentPromises)) {
yield result;
}
// Execute exclusive tools sequentially
for (const call of exclusive) {
const result = await executor.execute(call);
yield result;
}
}
function classifyTools(calls: ToolCall[]): { concurrent: ToolCall[], exclusive: ToolCall[] } {
const concurrent: ToolCall[] = [];
const exclusive: ToolCall[] = [];
for (const call of calls) {
// File writes, shell commands → exclusive
if (['write_file', 'execute_command', 'apply_diff'].includes(call.tool)) {
exclusive.push(call);
} else {
concurrent.push(call);
}
}
return { concurrent, exclusive };
}
Pattern: Auto-Mode Classifier
interface ClassifierResult {
safe: boolean;
reasoning: string;
confidence: number;
}
async function classifyToolCall(call: ToolCall): Promise<ClassifierResult> {
// Fast-filter heuristics (avoid LLM call if obviously safe/unsafe)
if (isTriviallyReversible(call)) {
return { safe: true, reasoning: 'Read-only operation', confidence: 1.0 };
}
if (isObviouslyDangerous(call)) {
return { safe: false, reasoning: 'Irreversible system modification', confidence: 1.0 };
}
// Chain-of-thought classifier
const prompt = `
Analyze this tool call for safety:
Tool: ${call.tool}
Arguments: ${JSON.stringify(call.args, null, 2)}
Context: ${call.context}
Consider:
1. Is this operation reversible?
2. Does it modify system-critical files?
3. Could it leak sensitive data?
4. Is the scope appropriate for the task?
Think step-by-step, then answer: SAFE or UNSAFE
`;
const response = await callClassifierModel(prompt);
return {
safe: response.includes('SAFE') && !response.includes('UNSAFE'),
reasoning: response,
confidence: extractConfidence(response)
};
}
Security Considerations
Pre-Trust Execution Window (CVE Pattern)
// ANTI-PATTERN: Executing code before trust established
// ❌ Vulnerable: Extension runs during init
async function initializeWorkspace() {
await loadMCPServers(); // Executes server processes
await runHooks('WorkspaceInit'); // Runs arbitrary code
// Trust dialog appears AFTER extensions already ran
await promptForTrust();
}
// ✅ Safe: Defer privileged operations until after trust
async function initializeWorkspace() {
await promptForTrust();
// Only after user approval:
if (trusted) {
await loadMCPServers();
await runHooks('WorkspaceInit');
}
}
Shared Failure Modes in Defense-in-Depth
// WARNING: Multiple safety layers share performance constraints
async function analyzeCommand(command: string): Promise<SecurityAnalysis> {
const subcommands = parseSubcommands(command);
// If command too complex (>50 subcommands), ALL layers degrade:
if (subcommands.length > 50) {
// Layer 1: Security analysis skipped (event loop starvation)
// Layer 2: Classifier times out
// Layer 3: Hooks don't run
// Result: Command executes with minimal oversight
return {
analyzed: false,
reason: 'Command too complex for analysis',
fallbackToPermissionMode: true
};
}
return await fullSecurityAnalysis(command);
}
Troubleshooting
Context Overflow Despite Compaction
// Check compaction effectiveness
async function debugContextOverflow(context: AssembledContext) {
console.log('Token breakdown:');
console.log(' System prompt:', estimateTokens(context.systemPrompt));
console.log(' Conversation:', estimateTokens(context.messages));
console.log(' Tools:', estimateTokens(context.tools));
// Check if a single message is too large
const largeMessages = context.messages.filter(m =>
estimateTokens(m.content) > 10000
);
if (largeMessages.length > 0) {
console.log('Large messages detected - consider manual snipping');
}
// Verify compaction stages ran
if (!context.compactionMetadata) {
console.log('WARNING: Compaction metadata missing - pipeline may not have run');
}
}
Permission Denied Despite Allow Rules
// Debug deny-first rule resolution
function debugPermissionDenial(call: ToolCall, rules: PermissionRule[]) {
const matchingRules = rules.filter(r => matches(r, call));
console.log(`Matching rules for ${call.tool}:`);
matchingRules.forEach(rule => {
console.log(` [${rule.decision}] ${rule.scope}:${rule.pattern} (priority: ${rule.priority})`);
});
const denyRule = matchingRules.find(r => r.decision === 'deny');
if (denyRule) {
console.log(`\n❌ DENIED by rule: ${denyRule.pattern}`);
console.log(' Deny-first policy means this overrides all allow rules');
}
}
Subagent Not Inheriting Expected Behavior
// Remember: Subagents are ALWAYS isolated
function debugSubagentIsolation() {
console.log('Subagent isolation checklist:');
console.log(' ❌ Does NOT inherit parent permissions');
console.log(' ❌ Does NOT see parent conversation history');
console.log(' ❌ Does NOT share parent context');
console.log(' ✅ DOES start at default permission mode');
console.log(' ✅ DOES get fresh tool pool');
console.log('\nIf you need shared context, use Skills instead of Subagents');
}
Further Reading
- Full Paper: arXiv:2604.14228
- Architecture Deep Dive:
docs/architecture.mdin repo - Design Guide:
docs/build-your-own-agent.md - Cross-System Comparison: Claude Code vs OpenClaw vs Hermes-Agent analysis
- Community Projects: Curated list of related research and implementations
Key Takeaways for Agent Builders
- Invest in infrastructure, not scaffolding: The 98/2 split is intentional
- Context is your bottleneck: Plan your compaction strategy early
- Deny-first prevents surprises: Explicit allow lists scale better than deny lists
- Defense-in-depth shares failure modes: Test your safety layers under degraded conditions
- Isolated subagents prevent permission escalation: Never share context/permissions
- Append-only state enables time-travel debugging: Make history immutable
- Hooks inject at zero context cost: Use them for cross-cutting concerns
- Graduated trust beats binary trust: Users traverse a spectrum over time
License: CC-BY-NC-SA-4.0 (per upstream project)
Repository: https://github.com/VILA-Lab/Dive-into-Claude-Code
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/claude-code-skills/dive-into-claude-code-analysis">View dive-into-claude-code-analysis on skillZs</a>