🔬 Claude Code Deep Dive

Tool Architecture

Mỗi tool implement interface Tool<Input, Output, Progress> (file Tool.ts — 793 lines). Tools được register qua buildTool() factory function cung cấp defaults fail-closed. Kiến trúc rất mature với:

• Zod schema validation cho inputs
• Permission checking 3 lớp: validateInput → checkPermissions → hook system
• Concurrency safety declarations (isConcurrencySafe)
• Read-only / Destructive annotations cho auto-mode classification
• Deferred loading via ToolSearch — lazy load tools chỉ khi cần
• Progress reporting — live progress UI while tool runs
• Interrupt behavior — tool có thể bị cancel hay block khi user submits new message

const TOOL_DEFAULTS = {
  isEnabled: () => true,
  isConcurrencySafe: (_input?) => false,  // assume not safe
  isReadOnly: (_input?) => false,         // assume writes
  isDestructive: (_input?) => false,
  checkPermissions: (input, _ctx?) =>     // defer to general system
    Promise.resolve({ behavior: 'allow', updatedInput: input }),
  toAutoClassifierInput: (_input?) => '', // skip classifier
  userFacingName: (_input?) => '',
}

export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return { ...TOOL_DEFAULTS, userFacingName: () => def.name, ...def }
}

Complete Tool Catalog

Permission System (3 layers)

Permission checking rất sophisticated với 3 lớp defense-in-depth:

// Layer 1: Tool-level validation
tool.validateInput(input, context)  // structural/semantic checks

// Layer 2: Tool-specific permission check 
tool.checkPermissions(input, context)  // tool's own rules

// Layer 3: General permission system (permissions.ts)
// - Check deny rules (blanket deny by tool name or pattern)
// - Check allowedTools/blockedTools from settings
// - Check auto-mode classifier (yoloClassifier.ts)
// - Prompt user if needed

// Layer 3.5: Hook system (PreToolUse hooks from CLAUDE.md)
// User-defined shell commands that run before tool execution

Commands vs Tools

Quan trọng: Commands ≠ Tools. Commands là slash commands user gõ (/compact, /help), Tools là AI-callable functions. Commands can inject prompts, modify state, or render UI — tools execute actions cho AI.

Command Types

• prompt — Inject content into conversation (e.g., /commit injects git commit prompt)
• local — Run locally, return result (e.g., /cost shows token usage)
• local-jsx — Render React component (e.g., /theme shows color picker)

Full Command Catalog

Dynamic Skills as Commands

Ngoài built-in commands, Claude Code load thêm skills từ 4 nguồn:

1. Skill directories — .claude/skills/ (project) + ~/.claude/skills/ (user)
2. Plugin skills — From installed plugins
3. Bundled skills — Ship with CLI
4. Built-in plugin skills — From enabled built-in plugins

3 Modes of Multi-Agent

AgentTool (230KB) — The Heart

AgentTool.tsx (230KB) là tool phức tạp nhất toàn codebase. Nó handle:

• Spawning sub-agents with isolated context
• Fork mode (inherits parent context + cache)
• Background execution with completion notifications
• Agent memory snapshots
• Git worktree isolation mode
• Remote CCR (Claude Code Remote) execution
• Agent color management for UI

Coordinator System Prompt (key excerpt)

// The coordinator gets a massive system prompt teaching it to:
`You are Claude Code, an AI assistant that orchestrates software 
engineering tasks across multiple workers.

## Your Role
- Help the user achieve their goal
- Direct workers to research, implement and verify code changes
- Synthesize results and communicate with the user
- Answer questions directly when possible

## Task Workflow Phases:
| Phase          | Who      | Purpose                    |
|----------------|----------|----------------------------|
| Research       | Workers  | Investigate, find files    |
| Synthesis      | YOU      | Understand, craft specs    |
| Implementation | Workers  | Make changes, commit       |
| Verification   | Workers  | Test changes work          |

**Never delegate understanding.** Don't write "based on your 
findings, fix the bug" — synthesize yourself first.`

Worker Communication

Workers communicate via <task-notification> XML injected as user-role messages:

<task-notification>
  <task-id>agent-a1b</task-id>
  <status>completed</status>
  <summary>Agent "Investigate auth bug" completed</summary>
  <result>Found null pointer in src/auth/validate.ts:42...</result>
  <usage>
    <total_tokens>15234</total_tokens>
    <tool_uses>8</tool_uses>
    <duration_ms>45000</duration_ms>
  </usage>
</task-notification>

🐣 BUDDY — Tamagotchi Pet System

Feature Flag: BUDDY Đây là feature thú vị nhất — một hệ thống Tamagotchi/Gacha pet sống bên cạnh input box của Claude Code!

export const RARITY_WEIGHTS = {
  common: 60,
  uncommon: 25,
  rare: 10,
  epic: 4,
  legendary: 1,  // 1% chance!
} as const

export const RARITY_STARS = {
  common: '★',
  uncommon: '★★',
  rare: '★★★',
  epic: '★★★★',
  legendary: '★★★★★',
} as const

Companions are deterministically generated from hash(userId) using Mulberry32 PRNG. ASCII art sprites animate with 3 frames per species. The companion "sits beside the user's input box and occasionally comments in a speech bubble."

🌟 KAIROS — Always-On Proactive Assistant

Feature Flag: KAIROS KAIROS biến Claude Code thành một always-on assistant có khả năng:

• Proactive mode — Agent tự động chạy, tìm việc để làm
• SleepTool — Sleep giữa các ticks (proactive polling)
• PushNotificationTool — Gửi push notifications cho user
• SendUserFileTool — Gửi files cho user
• SubscribePRTool — Theo dõi GitHub PR events via webhooks
• BriefTool — Tạo brief summaries
• CronTools — Scheduled task execution (CronCreate/Delete/List)
• MonitorTool — System monitoring
• RemoteTriggerTool — Remote agent triggers

🧠 autoDream — Background Memory Consolidation

Feature Flag: via isAutoDreamEnabled() autoDream chạy background memory consolidation — literally "dreaming"! Nó:

1. Time gate: ≥24h since last consolidation
2. Session gate: ≥5 new sessions since last consolidation
3. Lock: Only one consolidation at a time
4. Fork agent: Spawns a read-only forked agent that reviews transcripts
5. Consolidate: Updates MEMORY.md index, merges new info, prunes stale memories

// Phase 1 — Orient: ls memory dir, read MEMORY.md
// Phase 2 — Gather: search transcripts for new signal
// Phase 3 — Consolidate: merge into topic files
// Phase 4 — Prune and index: keep MEMORY.md under 200 lines

// Tool constraints: Read-only bash only!
// `ls`, `find`, `grep`, `cat`, `stat`, `wc`, `head`, `tail`
// Anything that writes will be denied.

// Key insight: "Converting relative dates to absolute dates 
// so they remain interpretable after time passes"

🗺️ ULTRAPLAN — Remote Opus Planning

Feature Flag: ULTRAPLAN User types "ultraplan" as keyword in prompt → launches remote Opus planning session via CCR (Claude Code Remote). Keyword detection with smart exclusion of quoted strings, paths, questions.

🕵️ Undercover Mode — Anti-Leak System

Security ant-only Ironic that this got leaked! Undercover mode prevents Claude Code from leaking Anthropic-internal info when contributing to public repos:

• Strips model codenames (Capybara, Tengu, etc.) from commits/PRs
• Removes Co-Authored-By lines and AI attribution
• "Write commit messages as a human developer would"
• Auto-activates for all non-internal repos (safe default)
• No force-OFF option — guards against accidental leaks

🎤 Voice Mode

Feature Flag: VOICE_MODE Voice interaction via voice_stream endpoint on claude.ai. Requires Anthropic OAuth. Kill-switch via GrowthBook flag tengu_amber_quartz_disabled.

🌉 Bridge Mode

Feature Flag: BRIDGE_MODE Remote control via daemon process. Enables IDE integrations, desktop apps, and remote sessions to control Claude Code.

🔍 Other Hidden Features

System Prompt Architecture

System prompt được built dynamically từ nhiều sections. Có boundary marker chia static (cacheable globally) và dynamic (per-session) content:

// STATIC sections (cached globally across users):
getSimpleIntroSection()      // Identity + cyber risk instruction
getSimpleSystemSection()     // System rules, tool results, hooks
getSimpleDoingTasksSection() // Coding guidelines, security
getActionsSection()          // Careful action execution
getUsingYourToolsSection()   // Tool usage patterns
getSimpleToneAndStyleSection() // Communication style
getOutputEfficiencySection()  // Output efficiency rules

// === BOUNDARY MARKER ===
SYSTEM_PROMPT_DYNAMIC_BOUNDARY  // Cache break point

// DYNAMIC sections (per-session, per-user):
session_guidance  // Agent tool section, skill guidance
memory            // Memory files (MEMORY.md, auto-memory)
env_info          // OS, CWD, shell, model info
language          // Language preference
output_style      // Custom output style
mcp_instructions  // MCP server instructions
scratchpad        // Scratchpad directory path
frc               // Function result clearing
token_budget      // Token budget instructions

Identity Prompt

const DEFAULT_PREFIX = 
  `You are Claude Code, Anthropic's official CLI for Claude.`

// SDK mode:
const AGENT_SDK_PREFIX = 
  `You are a Claude agent, built on Anthropic's Claude Agent SDK.`

// Frontier model reference:
const FRONTIER_MODEL_NAME = 'Claude Opus 4.6'

Cyber Risk Instruction (Security-critical)

// DO NOT MODIFY WITHOUT SAFEGUARDS TEAM REVIEW
// Owners: David Forsythe, Kyla Guru

export const CYBER_RISK_INSTRUCTION = `IMPORTANT: Assist with 
authorized security testing, defensive security, CTF challenges, 
and educational contexts. Refuse requests for destructive 
techniques, DoS attacks, mass targeting, supply chain compromise, 
or detection evasion for malicious purposes. Dual-use security 
tools (C2 frameworks, credential testing, exploit development) 
require clear authorization context.`

Key Prompt Engineering Patterns

1. "Don't Over-Engineer" Instructions

Claude Code has extensive anti-sloppy-code instructions:

- Don't add features, refactor code, or make "improvements" beyond 
  what was asked. A bug fix doesn't need surrounding code cleaned up.
- Don't add error handling for scenarios that can't happen.
- Don't create helpers or abstractions for one-time operations.
- Three similar lines of code is better than a premature abstraction.
- Default to writing no comments. Only add when the WHY is non-obvious.
- Don't remove existing comments unless you're removing the code.

2. False-Claims Mitigation

Report outcomes faithfully: if tests fail, say so with the relevant 
output; if you did not run a verification step, say that rather than 
implying it succeeded. Never claim "all tests pass" when output shows 
failures, never suppress or simplify failing checks to manufacture a 
green result, and never characterize incomplete work as done.

3. Numeric Length Anchors

// Research shows ~1.2% output token reduction vs qualitative "be concise"
'Length limits: keep text between tool calls to ≤25 words. 
 Keep final responses to ≤100 words unless the task requires more.'

4. Prompt Cache Optimization

Anthropic optimizes prompt caching obsessively:

• Static vs dynamic boundary marker prevents cache busting
• MCP instructions moved to delta attachments to avoid cache invalidation
• Agent list moved to attachments (saved 10.2% of fleet cache_creation tokens!)
• Tool sorting ensures cache stability
• systemPromptSection() registry allows lazy evaluation and caching

Memory Architecture

Claude Code has a sophisticated multi-layer memory system:

4 Memory Types (Taxonomy)

Memory File Format

---
type: feedback
title: Integration tests must use real DB
created: 2026-03-05
---
Integration tests must hit a real database, not mocks.

**Why:** Prior incident where mock/prod divergence masked a broken migration.
**How to apply:** When writing tests for database-touching code, always use 
test database, never mocks.

What NOT to Save

Claude Code explicitly excludes:

• Code patterns, architecture, file paths (derivable from code)
• Git history (use git log)
• Debugging solutions (fix is in the code)
• Anything in CLAUDE.md files
• Ephemeral task details
• Even when user explicitly asks — redirect to "what was surprising?"

Background Memory Extraction

After each conversation turn, a background agent extracts memories. It runs as a "perfect fork" of the main conversation — same system prompt, same context. Only fires when the main agent didn't already write memories.

Permission Modes

• Normal mode — Prompts user for each tool execution
• Auto-accept (YOLO) mode — Auto-classifier decides safety
• bypassPermissions — Skip all checks (dangerous, blocked on root)

BashTool Security (103KB!)

bashSecurity.ts alone is 103KB — more security code than most entire projects:

• Command parsing — Full bash command parser (132KB bashParser.ts)
• Path validation — 44KB of path security checks
• Sed validation — 22KB of sed command analysis
• Read-only validation — 69KB for enforcing read-only mode
• Destructive command detection — Warns before rm, git reset, etc.
• Sandbox mode — filesystem read/write allowlists, network restrictions

cch Attestation — Custom Bun Runtime

Security A fascinating anti-piracy/verification mechanism:

// cch=00000 placeholder in HTTP header
// Bun's NATIVE HTTP stack (Zig implementation) finds this placeholder
// in the serialized request body and OVERWRITES the zeros with a 
// computed hash AFTER JavaScript has finished.
// Server verifies this token to confirm request came from real 
// Claude Code client.

// Implementation: bun-anthropic/src/http/Attestation.zig
const cch = feature('NATIVE_CLIENT_ATTESTATION') 
  ? ' cch=00000;'  // same-length replacement avoids Content-Length changes
  : ''

Undercover Mode (Detailed)

## UNDERCOVER MODE — CRITICAL

NEVER include in commit messages or PR descriptions:
- Internal model codenames (Capybara, Tengu, etc.)
- Unreleased model versions (opus-4-7, sonnet-4-8)
- Internal repo/project names
- Internal Slack channels or short links
- "Claude Code" or any mention that you are an AI
- Co-Authored-By lines

GOOD: "Fix race condition in file watcher initialization"
BAD:  "Fix bug found while testing with Claude Capybara"
BAD:  "1-shotted by claude-opus-4-6"

Safety in Actions Prompt

The system prompt has detailed guidance on reversibility and blast radius:

• Freely allowed: editing files, running tests (local, reversible)
• Requires confirmation: git push, creating PRs, sending messages, force operations
• "Measure twice, cut once" — investigate before deleting
• Lock files: investigate what holds it, don't just delete
• Merge conflicts: resolve, don't discard changes
• User approving once ≠ blanket approval

API Layer (claude.ts — 126KB)

The API service handles all communication with Anthropic's API. Key features:

• Streaming — Full streaming support with tool use progress
• Prompt caching — Global scope + per-session scope with cache-break detection
• Retry logic — 28KB withRetry.ts with sophisticated error handling
• Rate limit handling — Claude.ai subscription limits, quota status extraction
• Model selection — Opus/Sonnet/Haiku with fast mode switching
• Task budgets — API-level task_budget for agentic turns
• Effort levels — Configurable effort (low/medium/high) per request

MCP Integration (119KB client)

Model Context Protocol client is a major component:

• client.ts (119KB) — Full MCP client implementation
• auth.ts (89KB) — OAuth flow for MCP servers
• config.ts (52KB) — MCP server configuration management
• Support for stdio, SSE, and in-process transports
• Elicitation handler for interactive MCP server UIs
• Channel notifications and permissions

Analytics & Telemetry

• GrowthBook (41KB) — Feature flags + A/B testing (cached to disk)
• Datadog — Metrics export
• First-party event logging — Custom event pipeline
• logEvent() — Standardized event tracking throughout codebase
• Events use tengu_ prefix (internal codename)

Cost Tracking

Full cost tracking with per-model breakdowns:

• Input/output token counting
• Cache read/creation token tracking
• USD cost calculation per model
• Session-level cost persistence
• Lines added/removed tracking
• API duration tracking (with and without retries)

Compact / Context Management

• Auto-compact — Automatic conversation compaction when approaching context limits
• Reactive compact — Feature-gated advanced compaction
• Context collapse — Collapse tool results into summaries
• History snip — Prune old history intelligently
• Microcompact — Fine-grained compaction boundaries

Model Codenames Decoded

React Ink Architecture

The entire terminal UI is built with React components rendered via Ink. This is unconventional but powerful — React's component model, hooks, and state management work naturally for complex TUIs.

Key UI Components

Vim Mode (1,358 lines)

Full Vim mode implementation with:

• Motions — h, j, k, l, w, b, e, $, ^, 0, gg, G, f/t + char
• Operators — d, c, y (delete, change, yank) with motion composition
• Text Objects — iw, aw, i", a", i(, a(, etc.
• Transitions — Normal → Insert → Visual mode state machine
• Types — Full TypeScript types for cursor, mode, registers

Theme System

Customizable color themes with named semantic colors (not raw hex). The /theme command renders a color picker UI.

Skills Architecture

Skills are markdown files with frontmatter that get injected as prompts. 4 loading sources:

1. Skill directories — .claude/skills/ per project + ~/.claude/skills/ user-global
2. Plugin skills — From npm-style plugins with manifest
3. Bundled skills — Ship with the CLI binary
4. Built-in plugin skills — From enabled built-in plugins

Skill Frontmatter Format

---
name: commit
description: Create a git commit with staged changes
whenToUse: After code changes are ready to commit
tools: [Bash, FileRead]
disallowedTools: [Agent, TodoWrite]
model: sonnet  # optional model override
effort: high   # optional effort level
shell:         # optional shell commands in prompt
  - "git status --short"
  - "git diff --cached"
---

# Commit Skill

Review the staged changes and create a meaningful commit message...

Plugin System

Plugins are npm-style packages with manifest, hooks, skills, and MCP servers:

• Built-in plugins — Ship with CLI, enable/disable via /plugin UI
• Marketplace plugins — External plugins with name@marketplace IDs
• Hot reload — Plugin hooks hot-reload when settings change
• Plugin-only policy — Restrict certain tools to plugin-provided only

Experimental: Skill Search

Feature Flag: EXPERIMENTAL_SKILL_SEARCH DiscoverSkillsTool + local search index for finding relevant skills automatically during conversation.

✅ Patterns Worth Adopting

❌ Things They Do Wrong / We Should Avoid

🔄 Things We Already Do Better

Overall Assessment: ⭐⭐⭐⭐ (4/5)

Strengths

• TypeScript usage: Excellent — strict types, sophisticated generics (BuiltTool<D>), branded types, proper Zod integration
• Error handling: Very thorough — try-catch everywhere, graceful degradation, error boundaries
• Documentation: Extensive JSDoc comments with architectural context, not just "what" but "why"
• Separation of concerns: Tool system is well-abstracted with clean interfaces
• Security mindset: Defense-in-depth throughout — fail-closed defaults, multiple validation layers
• Performance awareness: Memoization, lazy loading, cache optimization, scan throttling

Weaknesses

• File sizes: Multiple files >100KB — REPL.tsx (879KB), PromptInput.tsx (349KB). These are maintenance nightmares
• Monolithic architecture: Despite React components, too much logic in too few files
• Feature flag complexity: 30+ flags create testing combinatorial explosion
• Import complexity: Heavy use of conditional require() and lazy imports makes dependency graph hard to follow
• Comments hint at tech debt: Multiple "@[MODEL LAUNCH]" TODOs, "un-gate once validated" notes

Notable Code Patterns

1. Memoized Config with Cache Clearing

export const getUserContext = memoize(async () => {
  const claudeMd = getClaudeMds(await getMemoryFiles())
  return { claudeMd, currentDate: `Today's date is ${getLocalISODate()}.` }
})
// Cache cleared explicitly when state changes:
getUserContext.cache.clear?.()

2. Feature-Gated Dead Code Elimination

// bun:bundle feature() evaluates at BUILD TIME
// Entire code blocks are stripped from output when false
const buddy = feature('BUDDY')
  ? require('./commands/buddy/index.js').default
  : null  // DCE removes the require() entirely

3. Defensive Config Reading

// GrowthBook cache can return stale wrong-type values
function getConfig(): AutoDreamConfig {
  const raw = getFeatureValue_CACHED_MAY_BE_STALE('tengu_onyx_plover', null)
  return {
    minHours:
      typeof raw?.minHours === 'number' &&
      Number.isFinite(raw.minHours) &&
      raw.minHours > 0
        ? raw.minHours
        : DEFAULTS.minHours,
    // ... same for each field
  }
}

Testing Approach

Based on code patterns (test utilities, TestingPermissionTool, test environment checks), the project uses:

• Unit tests with mock/stub patterns
• Integration tests for tool execution
• Eval-driven prompt testing (referenced in memory type comments)
• Transcript search fidelity tests
• Feature flag testing via environment variables