Inkdown
Start writing

Claude-Code

62 files·4 subfolders

Shared Workspace

Claude-Code
codex

00-overview

Shared from "Claude-Code" on Inkdown

Claude Code — Architecture Overview

Written like a senior engineer giving KT to a junior. Read this first, then dive into the per-module docs.

What Is This?

This is Claude Code — Anthropic's agentic coding assistant that runs in your terminal. It's a TypeScript/Bun application that:

  1. Provides an interactive TUI (terminal UI) built with a custom React renderer called Ink
  2. Connects to Anthropic's API to stream AI responses with tool-use capabilities
  3. Can execute shell commands, read/write/edit files, search codebases, and more
  4. Supports multi-agent orchestration (coordinator mode, swarms)
  5. Can be controlled remotely via mobile/web (bridge system)
  6. Extends via plugins and skills

High-Level Architecture

Plain text
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

Key Concepts

1. The Query Loop (query.ts)

The heart of the system. Every time the user sends a message, a query loop starts:

Plain text

The loop handles recovery from errors (prompt too long, max output tokens, model fallback), context compaction, and streaming.

2. Tools

Tools are how the AI interacts with the world. Each tool has:

  • A JSON Schema definition (sent to the API)
  • An execution function
  • Permission checks (ask user, auto-allow, auto-deny)

Core tools: Bash, FileRead, FileEdit, FileWrite, Grep, Glob, WebSearch, WebFetch, TodoWrite, AskUserQuestion, Skill, and 30+ more.

3. Commands (Slash Commands)

User-facing commands typed as /command in the REPL: /compact, /model, /help, /clear, /plan, etc. Commands can be:

  • builtin — shipped with the app
  • skills — loaded from /skills/ directories
  • plugin — loaded from installed plugins
  • MCP — loaded from MCP servers
4. State Management

Two layers:

Bootstrap State (bootstrap/state.ts): A singleton module with getter/setter functions for global session state (session ID, cost, cwd, model, telemetry). This is the "global variables" layer.

AppState (state/): A Redux-like store using useSyncExternalStore. Holds all UI state (which panels are open, MCP connections, tasks, permissions, settings). Components subscribe to slices via useAppState(selector).

5. Ink Rendering

A custom React renderer that renders to the terminal instead of the DOM. Uses:

  • react-reconciler for the React fiber tree
  • Yoga (WASM) for flexbox layout
  • Double-buffered frame system for efficient terminal updates
  • ANSI escape sequences for output
6. Bridge (Remote Control)

Allows controlling a local Claude Code session from claude.ai/code (web) or the mobile app. Two modes:

  • Standalone bridge: claude remote-control — runs as a server, spawns child processes
  • REPL bridge: /remote-control — bridges an existing session

Uses WebSocket (v1) or SSE (v2) transport with JWT authentication.

7. Multi-Agent (Coordinator Mode)

The AI can act as a coordinator that spawns worker agents (sub-processes) to work on tasks in parallel. Workers report back via <task-notification> blocks.

8. Plugins & Skills
  • Plugins: Versioned packages that can add tools, commands, hooks, and MCP servers
  • Skills: Prompt-based capabilities discovered from /skills/ directories in the project

File Structure Map

Plain text

How a Session Flows

  1. main.tsx starts → parses CLI args → runs migrations → calls init()
  2. setup.ts runs → sets cwd, restores terminal backups, initializes hooks, starts prefetches
  3. REPL renders → Ink renders the main screen with prompt, status bar, and message history
  4. User types a prompt → goes through processUserInput → enters the query loop
  5. query.ts builds messages → calls Anthropic API → streams response
  6. If AI uses a tool → tool execution runs → result goes back into messages → loop continues
  7. If context gets too large → compaction summarizes old messages
  8. When done → response renders in the TUI → user types next prompt

Read Next

Each module has its own deep-dive doc:

DocCovers
01-entry-points.mdmain.tsx, setup.ts, CLI parsing, entrypoints
02-query-engine.mdThe query loop, API calls, streaming, compaction
03-tools-and-tasks.mdTool system, task system, AgentTool, permissions
04-commands-and-skills.mdSlash commands, skills, plugins
05-state-management.mdBootstrap state, AppState store, selectors
06-ink-rendering.mdCustom React renderer, layout, terminal output
07-bridge-remote.mdRemote control, web/mobile connectivity
08-mcp-services.mdModel Context Protocol servers
09-services-overview.mdAll services (analytics, compact, tools, etc.)
10-multi-agent.mdCoordinator mode, swarms, sub-agents