InkdownInkdown
Start writing

Claude-Code

62 filesยท4 subfolders

Shared Workspace

Claude-Code
codex

0400_system_architecture_and_design_rationale

Shared from "Claude-Code" on Inkdown

System Architecture And Why The Codebase Is Designed This Way

The Architecture In One Sentence

This is one runtime with several entry surfaces. Interactive REPL, headless SDK and print mode, remote-control bridge, and remote-session viewing all share the same model, tool, and session core, then diverge only where transport or UI requirements force them to.

Major Architectural Decisions

1. One shared query and tool core for both TUI and SDK
  • query.ts owns the turn-level state machine.
  • QueryEngine.ts owns conversation-level state for headless and SDK flows.
  • Tool.ts, , and own tool contracts and execution behavior.
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
tools.ts
services/tools/*
  • services/api/claude.ts owns provider and model API communication.
  • Why: feature parity is easier when both interactive and headless modes use the same execution kernel.
    • 2. Trust-sensitive staging of startup work
    • The client distinguishes safe work that can happen before trust from risky work that must wait in interactive mode.
    • Headless mode documents that trust is implicit.
    • Why: git, plugin LSP servers, shell helpers, and environment mutation can meaningfully change risk posture.
    3. File-backed persistence instead of a traditional database
    • Persistent state is mostly stored as local files under config, session, or plugin directories plus OS keychain and remote services where needed.
    • Why: the product is fundamentally a local CLI and TUI. Session transcripts, worktree state, plugin caches, and settings are natural file-backed concerns.
    4. Extensibility is split across commands, tools, skills, plugins, and MCP
    • Commands are human-invoked workflows.
    • Tools are model-callable runtime actions.
    • Skills influence prompt and system guidance behavior.
    • Plugins are packaged bundles that can contribute commands, hooks, MCP servers, agents, and output styles.
    • MCP provides runtime-discovered external tools and resources.
    • Why: each surface has different safety, lifecycle, and UX needs.
    5. utils/ is the platform layer
    • The codebase intentionally centralizes a massive amount of behavior in utils/*.
    • Why: most hard problems here are cross-cutting, including settings precedence, persistence, prompt assembly, git and worktree handling, file caches, telemetry, permissions, plugin loading, and platform quirks.
    6. Performance work is structural, not cosmetic
    • Lazy imports, feature-gated requires, cache warming, and explicit startup comments are architectural decisions.
    • Why: the first-render path is expensive in a large TypeScript CLI and TUI, and the team has clearly optimized module-evaluation and child-process cost.

    Architecture Summary For A Junior Engineer

    1. entrypoints/cli.tsx and main.tsx decide how the process starts.
    2. screens/REPL.tsx and cli/print.ts are the two big surfaces built on the same execution core.
    3. Tool.ts, tools.ts, query.ts, and services/api/claude.ts are the execution backbone.
    4. utils/, services/, and state/ contain most of the answers to why the client behaves the way it does.