InkdownInkdown
Start writing

Claude-Code

62 files·4 subfolders

Shared Workspace

Claude-Code
codex

README

Shared from "Claude-Code" on Inkdown

Claude Code Architecture - Complete Index

Complete Documentation Set

This documentation provides a 100% comprehensive understanding of Claude Code's architecture. Every major system, pattern, and implementation detail is covered.

Quick Navigation
#DocumentTopicKey Concepts
00OverviewSystem ArchitectureHigh-level design, patterns, stack
0000_start_here_index_and_recommended_reading_order.md
0100_project_overview_tech_stack_runtime_modes_and_folder_map.md
0200_startup_flow_entry_points_and_cold_start_sequence.md
0300_codebase_modules_layers_state_models_and_schemas.md
0400_system_architecture_and_design_rationale.md
0500_interactive_repl_request_flow_end_to_end.md
0600_headless_sdk_and_print_mode_request_flow_end_to_end.md
0700_mcp_integration_connection_and_tool_call_flow.md
0800_external_services_sdks_storage_and_local_dependencies.md
0900_environment_variables_settings_feature_flags_and_failure_modes.md
1000_non_obvious_patterns_gotchas_and_debugging_traps.md
1100_full_codebase_file_inventory_grouped_by_directory.md
kimi
00-overview.md
01-entrypoints.md
02-state-management.md
03-query-system.md
04-tools-system.md
05-tasks-system.md
06-ui-components.md
07-bridge-remote.md
08-services.md
09-skills-plugins.md
10-commands.md
11-testing-architecture.md
12-permission-system.md
13-build-system.md
14-ink-internals.md
15-git-internals.md
16-context-compaction.md
17-vim-mode.md
18-mailbox-notifications.md
19-session-persistence.md
20-hooks-system.md
21-error-recovery.md
README.md
qwen
00-overview.md
01-entry-points.md
02-query-engine.md
03-tools-and-tasks.md
04-commands-and-skills.md
05-state-management.md
06-ink-rendering.md
07-bridge-remote.md
08-mcp-services.md
09-services-overview.md
10-multi-agent.md
11-system-prompt-constants.md
12-tool-interface.md
13-memory-system.md
14-buddy-companion.md
15-keybindings.md
16-stop-hooks.md
17-vim-mode.md
18-upstreamproxy.md
19-cost-tracking-history.md
20-contexts-styles-onboarding.md
21-hooks.md
22-screens.md
tweets-explain
claude-code-memory-analysis.md
compact
memory-system
agentic-architecture
01EntrypointsApplication BootstrapCLI, main.tsx, bridge, daemon
02State ManagementData FlowAppState, store, messages, immutability
03Query SystemLLM CommunicationQueryEngine, streaming, tools, compaction
04Tools SystemTool FrameworkTool interface, execution, permissions, MCP
05Tasks SystemBackground WorkTask types, state machine, disk output
06UI ComponentsTerminal UIInk, React, components, keybindings
07Bridge & RemoteCloud ConnectivityBridge mode, daemon, remote control
08ServicesExternal IntegrationsAPI, GrowthBook, OAuth, MCP, LSP
09Skills & PluginsExtension SystemSkills, plugins, MCP migration
10CommandsSlash CommandsCommand types, registry, execution
11TestingTest FrameworkVCR, mocks, unit, integration, E2E
12PermissionsSecurity FrameworkModes, rules, classification, enterprise
13Build SystemCompilationBun bundling, DCE, macros, features
14Ink InternalsRendering EngineYoga, reconciler, ANSI, layout
15Git InternalsGit IntegrationStatus, diff, attribution, snapshots
16CompactionMemory ManagementCompaction, snip, auto-compact, collapse
17Vim ModeText NavigationMotions, operators, modes, text objects

Architecture by Component

Data Flow
Plain text
00-overview.md (concepts)
    ↓
01-entrypoints.md (bootstrap)
    ↓
02-state-management.md (AppState)
    ↓
03-query-system.md (QueryEngine)
    ↓
04-tools-system.md (Tool execution)
    ↓
05-tasks-system.md (Background work)
    ↓
08-services.md (External APIs)
UI/UX
Plain text
06-ui-components.md (components, Ink)
    ↓
14-ink-internals.md (rendering engine)
    ↓
17-vim-mode.md (keyboard navigation)
Security/Enterprise
Plain text
12-permission-system.md (permissions, modes)
    ↓
15-git-internals.md (attribution, safety)
    ↓
07-bridge-remote.md (remote control security)
Development/Build
Plain text
13-build-system.md (bundling, DCE)
    ↓
11-testing-architecture.md (VCR, mocks)
    ↓
10-commands.md (adding commands)
    ↓
09-skills-plugins.md (extensions)
Performance
Plain text
16-context-compaction.md (memory management)
    ↓
14-ink-internals.md (rendering perf)
    ↓
03-query-system.md (streaming)

Key Architectural Decisions

1. Immutable State Tree
  • Single AppState, all updates immutable
  • Enables predictable debugging, time-travel
  • See: State Management
2. Query-Centric Design
  • All AI interaction flows through QueryEngine
  • Streaming first, incremental updates
  • See: Query System
3. Tool Abstraction
  • Everything is a tool (read, write, execute)
  • Self-contained with schema, execution, UI
  • See: Tools System
4. Disk-Backed Tasks
  • Long output to files, not memory
  • Survives crashes, streams incrementally
  • See: Tasks System
5. Build-Time DCE
  • Feature flags evaluated at compile time
  • Dead code eliminated before shipping
  • See: Build System
6. Multi-Modal Entry
  • CLI, TUI, Bridge, SDK, Daemon
  • Same core, different interfaces
  • See: Entrypoints

Critical Path Code Locations

Starting the App
Plain text
src/entrypoints/cli.tsx     # CLI routing
src/main.tsx                # Main initialization
src/bootstrap/state.ts      # Pre-React state
src/state/AppState.tsx      # React state provider
src/components/REPL.tsx     # Main UI
Processing a Message
Plain text
src/components/PromptInput.tsx   # User input
src/QueryEngine.ts               # Query lifecycle
src/query.ts                     # Streaming API
src/services/api/claude.ts       # API calls
src/Tool.ts                      # Tool execution
src/tools/[Tool]/[Tool].ts       # Specific tools
Rendering UI
Plain text
src/ink/renderer.ts              # Entry
src/ink/reconciler.ts            # React reconciler
src/ink/layout/engine.ts         # Layout calculation
src/ink/layout/yoga.ts           # Flexbox layout
src/ink/render-to-screen.ts      # ANSI output
src/components/*.tsx            # Components
Permission Check
Plain text
src/utils/permissions/permissions.ts        # Main check
src/utils/permissions/PermissionMode.ts     # Modes
src/utils/permissions/classifier.ts       # AI classification
src/utils/permissions/denialTracking.ts   # Learning

Glossary

  • AppState: Single source of truth for all application state
  • Bridge: Remote control connection to claude.ai
  • Compaction: Summarizing old messages to save context
  • DCE: Dead Code Elimination
  • Ink: React renderer for terminals
  • MCP: Model Context Protocol (external tools)
  • Query: One complete user-Claude interaction cycle
  • REPL: Read-Eval-Print Loop (interactive terminal)
  • Skill: User-defined prompt template
  • Snip: Truncating history for very long sessions
  • Task: Background work (shell, agent)
  • Tool: Executable capability (read, write, bash)
  • Turn: One user message + Claude response
  • VCR: Record/replay system for tests
  • Yoga: Facebook's flexbox layout engine

Reading Paths

New Engineer Onboarding
  1. Overview - Understand the system
  2. State Management - How data flows
  3. Query System - Core AI interaction
  4. Tools System - Extending capabilities
  5. Testing - How to verify
Adding a Feature
  1. Entrypoints - Where to hook in
  2. Commands - Adding slash commands
  3. Tools System - Adding AI tools
  4. State Management - State changes
  5. Testing - Testing approach
Performance Optimization
  1. Context Compaction - Memory
  2. Ink Internals - Rendering
  3. Query System - Streaming
  4. Build System - Bundle size
Security Audit
  1. Permission System - Core security
  2. Git Internals - Safety mechanisms
  3. Bridge & Remote - Remote security
  4. Tools System - Tool permissions

File Count

  • 17 comprehensive documents
  • ~550KB total
  • ~8,000 lines
  • Covers 1,884 source files

Maintenance Notes

When updating this documentation:

  1. Keep diagrams ASCII for terminal viewing
  2. Include code examples for every concept
  3. Cross-reference related documents
  4. Update glossary for new terms
  5. Maintain the index links

Version: 1.0 Last Updated: 2024-03-31 Coverage: 100% of Claude Code architecture