1. Conduid
  2. Documentation
  3. Claude Code Internals
MCP server · Documentation

Claude Code Internals

· github.com/claytonsandham/claude-code-internals

A documentation only view into the inner workings of Claude Code

Unclaimed docs
InstallView source
34Low

Scored 6 months ago · breakdown

About Claude Code Internals

Claude Code Internals is an MCP server in the Documentation category: a documentation only view into the inner workings of Claude Code.

Install

From source
git clone https://github.com/claytonsandham/claude-code-internals

This server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.

Ask AI

✦

Ask AI about Claude Code Internals

Powered by Claude · Grounded in docs

I know everything about Claude Code Internals. Ask me about installation, configuration, usage, or troubleshooting.

Security checks

  • ✓README presentThe repository ships documentation.

5 checks have not been run yet.

README

Claude Code — Source Code Documentation

Note: This repository does not contain Claude Code's source code. It is a documentation project — file-by-file and directory-level write-ups that explain the architecture, purpose, and behaviour of Claude Code, Anthropic's interactive AI-powered command-line interface. Each directory in the documented codebase has its own README.md, and individual source files have corresponding documentation entries. This repo exists purely for educational and reference purposes.

Claude Code itself is a TypeScript codebase (~1,300+ files) that powers the claude CLI tool — an AI assistant that can read files, write code, run commands, search codebases, and much more, all from your terminal.

Table of Contents

What is Claude Code?

Claude Code is a terminal-based AI assistant that:

  1. Reads and understands code — It can read any file, search with grep/glob, and understand project structure
  2. Writes and edits code — It can create files, make surgical edits, and refactor across a codebase
  3. Runs commands — It executes shell commands (with user permission) to build, test, and deploy
  4. Uses external tools — It connects to MCP servers, LSP servers, and other development tools
  5. Manages sub-agents — It can spawn background agents for parallel work
  6. Remembers context — It has a persistent memory system and conversation history

The user interacts via a terminal REPL (read-eval-print loop). They type natural language, Claude responds with text and tool calls, and the cycle repeats.

Platform Support

  • CLI: Terminal on macOS, Linux, Windows
  • Desktop App: Mac, Windows
  • Web App: claude.ai/code
  • IDE Extensions: VS Code, JetBrains

Architecture Overview

Claude Code is built with React + Ink (a React renderer for terminal UIs) and communicates with the Claude API for AI responses. Here's the high-level architecture:

┌─────────────────────────────────────────────────────────────┐
│                        Terminal UI                           │
│  ┌─────────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ PromptInput │  │   Messages   │  │   Permissions     │  │
│  │ (user types)│  │  (responses) │  │  (approve/deny)   │  │
│  └──────┬──────┘  └──────▲───────┘  └────────▲──────────┘  │
│         │                │                    │             │
│  ┌──────▼────────────────┴────────────────────┴──────────┐  │
│  │                    React + Ink                         │  │
│  │              (Terminal UI Framework)                   │  │
│  └──────────────────────┬────────────────────────────────┘  │
├─────────────────────────┼───────────────────────────────────┤
│                   Core Engine                                │
│  ┌──────────────────────▼────────────────────────────────┐  │
│  │                 QueryEngine                            │  │
│  │         (Conversation loop orchestrator)               │  │
│  └───────┬──────────────┬──────────────────┬─────────────┘  │
│          │              │                  │                 │
│  ┌───────▼──────┐ ┌────▼─────────┐ ┌──────▼──────────┐     │
│  │  Claude API  │ │ Tool System  │ │  Hook System    │     │
│  │  (streaming) │ │ (42+ tools)  │ │ (20+ events)    │     │
│  └──────────────┘ └──────────────┘ └─────────────────┘     │
│                                                              │
│  ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐     │
│  │  MCP Client  │ │ Permissions  │ │  State Store    │     │
│  │  (external   │ │ (rule-based  │ │  (Zustand-like) │     │
│  │   tools)     │ │  security)   │ │                 │     │
│  └──────────────┘ └──────────────┘ └─────────────────┘     │
└─────────────────────────────────────────────────────────────┘

Entry Points

Entry Points
├── cli.tsx          → Fast-path version check, feature gates
├── main.tsx         → Bootstrap, lazy loading, CLI dispatch (~19K LOC)
├── setup.ts         → Pre-session config (Node check, worktree, watchers)
└── replLauncher.tsx → Launch REPL or headless mode

Core Loop (QueryEngine.ts)

Core Loop
├── Process user input (slash commands, attachments)
├── Build context (system prompt, git status, memory)
├── Load tools dynamically (MCP, plugins, skills)
├── Stream API call to Claude
├── Execute tools via StreamingToolExecutor
├── Auto-compact history if needed
└── Render results to UI

Technology Stack

Layer Technology Purpose
Language TypeScript ~1,300+ files, 33MB source
Runtime Bun Fast startup, native APIs, build-time dead code elimination via feature() gates
UI Framework React + Custom Ink Terminal UI rendering with React component model
Layout Engine Yoga Flexbox-style layout for terminal
State Zustand-style store Global application state (450+ fields)
Validation Zod Runtime type validation for tool inputs, schemas, settings
API Client @anthropic-ai/sdk Claude API communication with streaming
MCP Client @modelcontextprotocol/sdk Connect to external tool servers
CLI Parsing Commander.js Command-line argument parsing

How a Conversation Works

Understanding this flow is key to understanding the entire codebase:

1. USER TYPES A MESSAGE
   └─▶ PromptInput component captures input
       └─▶ processUserInput() routes it (text, /command, or !shell)

2. MESSAGE SENT TO CLAUDE API
   └─▶ QueryEngine.submit() sends conversation history + system prompt
       └─▶ services/api/claude.ts handles streaming, retries, caching
           └─▶ Response streams back token-by-token

3. CLAUDE RESPONDS (text and/or tool calls)
   └─▶ Text is rendered immediately in the terminal
   └─▶ Tool calls enter the tool execution pipeline:

4. TOOL EXECUTION
   └─▶ Tool.checkPermissions() evaluates permission rules
       ├─▶ "allow" → execute immediately
       ├─▶ "deny" → reject with explanation
       └─▶ "ask" → render PermissionRequest component
           └─▶ User approves/denies in the terminal
   └─▶ Tool.call() executes the action (read file, run command, etc.)
   └─▶ Result sent back to Claude as a tool_result message

5. LOOP CONTINUES
   └─▶ Claude sees tool results, may call more tools or respond with text
   └─▶ Loop repeats until Claude has no more tool calls

6. POST-PROCESSING
   └─▶ Hooks fire (PostToolUse, Stop, etc.)
   └─▶ Memory extraction runs in background
   └─▶ Session is saved to disk

Project Structure

All source code lives in src/. There are no other top-level source directories.

Claude Code Source/
├── README.md              ← You are here (project entry point)
├── CLAUDE.md              ← Instructions for Claude itself
└── src/                   ← All source code
    ├── main.tsx           ← Main bootstrap (~19K LOC)
    ├── QueryEngine.ts     ← Core conversation loop
    ├── Tool.ts            ← Tool interface definition
    ├── tools.ts           ← Tool registry
    ├── commands.ts        ← Command registry
    ├── query.ts           ← Query logic
    ├── tasks.ts           ← Task system types
    │
    ├── entrypoints/       ← Application entry points (CLI, SDK, MCP)
    ├── bootstrap/         ← Startup initialization
    ├── state/             ← Global state store
    ├── context/           ← React contexts
    │
    ├── tools/             ← 42+ tool implementations
    ├── commands/          ← 90+ slash commands
    ├── skills/            ← Bundled skills (/commit, /review)
    ├── plugins/           ← Plugin system
    │
    ├── components/        ← 146+ terminal UI components
    ├── ink/               ← Custom terminal renderer
    ├── screens/           ← Top-level screen components
    │
    ├── services/          ← 20 core services (API, MCP, analytics...)
    ├── hooks/             ← 76+ React hooks
    ├── utils/             ← 331+ utility modules
    │
    ├── cli/               ← CLI infrastructure & transports
    ├── bridge/            ← Remote bridge mode
    ├── coordinator/       ← Multi-agent coordination
    ├── server/            ← Direct Connect server mode
    ├── tasks/             ← Background task types
    │
    ├── vim/               ← Vim mode implementation
    ├── voice/             ← Voice input support
    ├── keybindings/       ← Keybinding system
    ├── constants/         ← Application constants
    ├── types/             ← TypeScript type definitions
    ├── schemas/           ← Zod validation schemas
    ├── migrations/        ← Data migrations
    ├── native-ts/         ← Native TS ports (layout, search, diff)
    ├── memdir/            ← Persistent memory system
    ├── buddy/             ← Companion pet system
    └── ...                ← Additional modules

Start here: src/README.md — detailed overview of every directory and file with navigation links.

Key Concepts

1. Tools

Tools are capabilities that Claude can invoke during a conversation. Each tool is defined with buildTool() and has:

  • Input schema (Zod) — validated parameters
  • Permission model — what requires user approval
  • Execution logic — the actual implementation

42+ built-in tools including:

  • File I/O: Read, Write, Edit, Glob, Grep
  • Execution: Bash, PowerShell, REPL
  • Web: WebSearch, WebFetch
  • Code Intelligence: LSP (goToDefinition, findReferences, hover)
  • Orchestration: Agent, Skill, TodoWrite, Task*
  • MCP: MCPTool, ListMcpResources, ReadMcpResource
  • Planning: EnterPlanMode, ExitPlanMode
  • Worktree: EnterWorktree, ExitWorktree
  • Interaction: AskUserQuestion, SendMessage
  • Scheduling: CronCreate, CronDelete, CronList

Deep dive: src/tools/README.md

2. The Permission System

Every potentially dangerous action goes through a permission check:

  • alwaysAllow — auto-approve (e.g., reading files in the project)
  • alwaysDeny — auto-reject (e.g., blocked commands)
  • alwaysAsk — prompt the user every time

Permissions support pattern matching: "Bash(npm test)" allows only npm test, "Bash(git:*)" allows all git commands, "FileWrite(src/**)" allows writing to src/.

Permission modes: default (ask), plan (pause before execution), bypassPermissions, auto.

Deep dive: src/utils/permissions/README.md

3. The Hook System

Hooks are user-configured automations that trigger on events:

  • Lifecycle: SessionStart, Stop, SessionEnd, Setup
  • Tool: PreToolUse, PostToolUse, PostToolUseFailure
  • User: UserPromptSubmit, PermissionDenied, Notification
  • MCP: ElicitationRequest, ElicitationResult
  • Subagent: SubagentStart, SubagentStop, TeammateIdle

Hooks execute as shell commands, HTTP endpoints, or in-process TypeScript callbacks, configured in settings.json.

Deep dive: src/utils/hooks/README.md

4. MCP (Model Context Protocol)

MCP lets Claude connect to external tool servers. An MCP server might provide database access, API integrations, or specialized tools. Claude Code includes a full MCP client supporting 6 transport types (stdio, SSE, HTTP, WebSocket, SDK, SSE-IDE).

Deep dive: src/services/mcp/README.md

5. Commands (Slash Commands)

Users type /command in the REPL to trigger actions. There are 90+ commands supporting two types:

  • PromptCommand — Injects a prompt into the conversation (e.g., /commit, /review)
  • LocalJSXCommand — Renders local JSX UI (e.g., /config, /help)

Deep dive: src/commands/README.md

6. Skills

Skills are reusable prompts bundled as markdown files with YAML frontmatter. They can be invoked via /skill-name and inject specialized instructions into the conversation. Skills can come from:

  • Bundled: batch, claudeApi, debug, loop, simplify, skillify, etc.
  • User: ~/.claude/skills/
  • Project: .claude/skills/
  • Plugins: From installed plugins
  • MCP: From connected MCP servers

Deep dive: src/skills/README.md

7. State Management

The app uses a Zustand-style store (AppStateStore) with 450+ fields covering settings, permissions, tasks, MCP connections, UI state, and more. React components subscribe to specific slices via useAppState().

Deep dive: src/state/README.md

8. The Terminal UI (Ink)

Claude Code uses a custom fork of Ink (React for terminals) with:

  • Yoga layout engine — flexbox-style layout for terminal
  • DOM-style event system — keyboard, click, focus events with capture/bubble
  • Custom components — Box, Text, ScrollBox, Button, Link, etc.

Deep dive: src/ink/README.md

9. Background Tasks & Sub-Agents

Claude can spawn background tasks:

  • LocalAgentTask — sub-agents that run queries in parallel
  • LocalShellTask — long-running shell commands
  • RemoteAgentTask — agents running on remote infrastructure
  • DreamTask — memory consolidation tasks
  • InProcessTeammateTask — swarm teammates with shared context

Deep dive: src/tasks/README.md

10. Feature Gates

Many features are gated behind build-time flags using Bun's dead code elimination:

import { feature } from "bun:bundle";
if (feature("BRIDGE_MODE")) { /* only in bridge builds */ }

Common gates: BRIDGE_MODE, KAIROS, COORDINATOR_MODE. Gated code may reference modules not present in this extraction.

Configuration

Settings are loaded from multiple sources with precedence:

  1. Environment variables (highest priority)
  2. MDM (macOS/Windows/Linux enterprise management)
  3. Remote managed settings (cloud-based policies)
  4. Project config: .claude/config.json
  5. Global config: ~/.claude/config.json

Key config areas: model selection, permission mode, MCP servers, themes, keybindings, hooks, plugins.

Deep dive: src/utils/settings/README.md

Cost Tracking

Per-model pricing with cache-aware cost calculation:

cost = (inputTokens × inputRate) + (outputTokens × outputRate)
     + (cacheReadTokens × cacheReadRate) + (cacheWriteTokens × cacheWriteRate)
     + (webSearchRequests × $0.01)

Performance Optimizations

  • Startup profiling: profileCheckpoint() tracks timing through startup
  • Lazy loading: Dynamic imports for heavy modules
  • Fast paths: --version, --dump-system-prompt skip full initialization
  • LRU caches: File state cache, skill index cache
  • Parallel I/O: Keychain, MDM reads run concurrently at startup
  • Streaming execution: Generator-based tool execution with concurrency

Getting Started Reading the Code

Each topic below has a comprehensive deep-dive guide in the docs/ directory, plus quick-reference links to the relevant source directories.

"I want to understand how Claude processes a user message"

In-Depth Guide: Message Processing (~1600 lines)

  1. Start at src/QueryEngine.ts — the main conversation loop
  2. Then src/query.ts — lower-level query orchestration
  3. Then src/services/api/README.md — how API calls are made

"I want to understand a specific tool (e.g., Bash)"

In-Depth Guide: Tool System (~700 lines)

  1. Go to src/tools/BashTool/README.md
  2. See also src/utils/bash/README.md for the security parser

"I want to understand the permission system"

In-Depth Guide: Permission System (~1000 lines)

  1. Start at src/utils/permissions/README.md — rule engine
  2. Then src/components/permissions/README.md — UI rendering
  3. Then src/hooks/toolPermission/README.md — React integration

"I want to understand how the terminal UI works"

In-Depth Guide: Terminal UI (~1000 lines)

  1. Start at src/ink/README.md — the custom renderer
  2. Then src/components/README.md — all UI components
  3. Then src/screens/README.md — top-level screens

"I want to understand MCP integration"

In-Depth Guide: MCP Integration (~1200 lines)

  1. Start at src/services/mcp/README.md — the MCP client
  2. Then src/tools/MCPTool/README.md — how MCP tools are proxied
  3. Then src/components/mcp/README.md — the management UI

"I want to understand the command/skill system"

In-Depth Guide: Commands & Skills (~1000 lines)

  1. Start at src/commands/README.md — slash command registry
  2. Then src/skills/README.md — skill loading and invocation
  3. Then src/plugins/README.md — plugin architecture

"I want to understand how settings and configuration work"

In-Depth Guide: Settings & Configuration (~1000 lines)

  1. Start at src/utils/settings/README.md — settings hierarchy
  2. Then src/utils/hooks/README.md — hook configuration
  3. Then src/utils/memory/README.md — CLAUDE.md memory files

"I want to understand multi-agent coordination"

In-Depth Guide: Multi-Agent Coordination (~900 lines)

  1. Start at src/coordinator/README.md — coordinator architecture
  2. Then src/utils/swarm/README.md — swarm coordination
  3. Then src/tasks/README.md — task types

"I want to understand remote/bridge mode"

In-Depth Guide: Remote & Bridge Mode (~700 lines)

  1. Start at src/bridge/README.md — bridge protocol
  2. Then src/server/README.md — Direct Connect server
  3. Then src/remote/README.md — remote execution

Directory Index

Every directory in the project has its own README.md with detailed documentation. Click any link to dive deeper.

Core Engine

Tools (42+)

Commands (90+)

User Interface

Terminal Renderer (Ink)

Services (20)

Infrastructure

Task System

Skills & Plugins

React Hooks (76+)

Utilities (331+)

Data & Types

Specialized Features

License

This documentation is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0).

You are free to share and adapt the material for any purpose, even commercially, as long as you give appropriate credit.

Disclaimer: This license covers the original documentation only. Claude Code and all related software are the property of Anthropic, PBC and are not covered by this license.

README copy captured when this server was indexed; it may lag the repository. The original is authoritative.

Questions

About Claude Code Internals

How do I install Claude Code Internals?

No package has been published for this server, so install it from source: clone the repository and follow its README.

Is Claude Code Internals safe to use with an AI agent?

Its trust score is 34 out of 100 (low). It passes 1 of the 1 static security checks run so far. It has no ConduID identity yet, so agent calls to it are not receipted.

Is Claude Code Internals still maintained?

Conduid hasn't recorded a commit date for this repository yet. Check the repository directly for recent activity.