How kuberwastaken/claude-code works
1. This repository is a monorepo-style TypeScript/Bun CLI application for Claude Code. The top-level runtime starts in main.tsx / entrypoints/cli.tsx, then fans out into command handlers, the terminal UI, tool execution, background services, and optional remote/bridge modes.
2. The core execution loop is a conversational agent loop: user input enters through the CLI/UI layer, gets parsed into commands or prompts, then is turned into model/tool requests. state/, context/, hooks/, and services/tools/ coordinate that loop, while tools/ contains the actual action implementations the model can invoke.
3. The terminal UI is built on a custom Ink-like renderer under ink/, with React components in components/ and screens/ driving the visible app. This layer owns prompt input, transcript rendering, dialogs, keybindings, notifications, and status indicators, but it does not directly implement business logic; it mostly reflects and manipulates app state.
4. Command handling is split into two layers: commands/ contains user-facing slash commands and full-screen flows, while cli/handlers/ handles CLI subcommands and noninteractive entry paths. commands.ts acts as the registry/dispatch surface. This is the main boundary between “interactive app features” and “operational CLI utilities.”
5. Tooling is a major subsystem. tools/ defines dozens of model-callable capabilities: shell execution, file read/write/edit, web search/fetch, LSP integration, MCP access, agent spawning, task management, notebook edits, and remote triggers. Each tool typically has its own prompt, UI wrapper, validation, and result rendering, so the model sees a curated interface rather than raw host APIs.
6. Permissioning and safety form a separate control plane around tools. utils/permissions/, hooks/toolPermission/, and components/permissions/ implement mode selection, path/risk validation, user approval dialogs, and auto-approval logic. The security boundary is especially important for shell and filesystem tools, where command semantics, sandboxing, and protected-file rules prevent unsafe actions.
7. Model and API access are abstracted through services/api/, utils/model/, constants/, and QueryEngine.ts. These layers assemble prompts, beta flags, context limits, model routing, cost tracking, and Anthropic-specific request metadata. The app depends on Anthropic’s API as the primary external model service, but wraps it with caching, retries, prompt composition, and feature gating.
8. Remote and multi-session behavior is a second major boundary. bridge/, remote/, server/, upstreamproxy/, replLauncher.tsx, and related hooks handle remote control sessions, CCR/bridge flows, websocket/session relays, trusted-device/JWT auth, and worktree or same-directory execution modes. This is where local terminal state can be mirrored, resumed, or controlled from another client.
9. Background intelligence and persistence are handled by dedicated services. services/autoDream/, services/compact/, services/SessionMemory/, services/extractMemories/, memdir/, and history.ts manage transcript summarization, memory consolidation, pruning, and retrieval. The data flow here is from session history and logs into durable memory files, then back into future prompts and context selection.
10. Plugins, skills, and MCP are extensibility layers. plugins/, skills/, services/mcp/, and tools/MCPTool support loading third-party or bundled capabilities, registering commands/tools/hooks, and connecting to external MCP servers. This expands the agent’s action surface without baking every integration into the core runtime.
11. Several subsystems are explicitly feature-gated or environment-gated. migrations/, constants/betas.ts, utils/plugins/*, buddy/, coordinator/, voice/, and some commands/hooks are only enabled for certain builds, org types, or runtime flags. Architecturally, this means the repository contains both public and internal product paths, with compile-time dead-code elimination used to produce different shipped binaries.
12. Telemetry, analytics, and operational safeguards are cross-cutting concerns. services/analytics/, utils/telemetry/, utils/log.ts, utils/debug.ts, services/notifier.ts, and utils/diagnosticTracking.ts collect events, traces, and usage signals. These systems feed product analytics, debugging, rate-limit handling, and session observability without being part of the core conversational loop.
13. If you’re drawing the architecture, the cleanest high-level split is: local CLI/UI frontend, agent/tool orchestration layer, safety/permission layer, model/API boundary, background memory/persistence services, and optional remote/extension boundaries. Most other directories hang off one of those six pillars.
Main entry points: toolOrchestration.ts Tool Orchestrator · useMainLoopModel.ts Hooks · App.tsx App Shell · store.ts State
Components 22
CLI & UI
Interactive terminal entrypoints, React screens, and Ink renderer.
- Main · Top-level runtime bootstrap for the CLI app.
main.tsx - CLI Entry · CLI startup and subcommand wiring.
entrypoints/cli.tsx - REPL · Primary terminal conversation surface.
screens/REPL.tsx - Ink UI · Custom terminal renderer and event/layout system.
ink/ink.tsx - App Shell · Top-level React app and UI composition.
components/App.tsx
Agent Core
Conversation loop, state, context, commands, and tool orchestration.
- Commands · Registry and dispatch surface for slash commands.
commands.ts - Input Parse · Turns user text, slash commands, and shell input into actions.
utils/processUserInput/processUserInput.ts - State · App state, selectors, and store coordination.
state/store.ts - Context · Shared app contexts for prompt, overlays, notifications, and queueing.
context.ts - Hooks · Lifecycle, command, tool, IDE, and queue hooks that drive the loop.
hooks/useMainLoopModel.ts
Tools
Model-callable actions and their shared execution boundaries.
- Tool Orchestrator · Streaming tool execution, orchestration, and tool hooks.
services/tools/toolOrchestration.ts - Shell Tool · Shell execution with semantics, sandboxing, and permission checks.
tools/BashTool/BashTool.tsx - File Tools · Read/write/edit and notebook/file boundary tools.
tools/FileEditTool/FileEditTool.ts - Search Tools · Glob, grep, web, and resource lookup capabilities.
tools/WebSearchTool/WebSearchTool.ts
Remote & Sessions
Bridge, server, and relay paths for multi-session control.
- Bridge · Bridge protocol, session relay, and remote control flows.
bridge/bridgeMain.ts - Remote Server · Direct-connect and websocket session infrastructure.
server/directConnectManager.ts
Memory & Persistence
Summaries, memory files, history, and compaction pipelines.
Platform Services
Model/API access, permissions, plugins, telemetry, and supporting services.
- Model API · Prompt assembly, routing, retries, limits, and Anthropic requests.
services/api/claude.ts - Permissions · Approval dialogs, rules, and auto-approval logic.
utils/permissions/permissions.ts - Plugins & MCP · Plugin loading, skills, and MCP integration.
services/plugins/PluginInstallationManager.ts - Telemetry · Analytics, logging, diagnostics, and usage tracking.
services/analytics/index.ts
Connections 25
- Main → CLI Entry: boot · Main runtime hands off to CLI entrypaths.
- CLI Entry → App Shell: start UI · Interactive mode mounts the app shell.
- CLI Entry → REPL: launch · REPL and resume modes enter the terminal conversation screen.
- App Shell → Ink UI: rendered by · React UI is rendered through the custom Ink runtime.
- REPL → App Shell: compose · Screen content is composed inside the app shell.
- App Shell → State: reads/writes · UI reflects and updates central app state.
- Context → State: shares · Contexts carry state-adjacent coordination data.
- Hooks → State: subscribes · Hooks drive stateful behavior and lifecycle effects.
- Input Parse → Commands: slash cmds · User commands are parsed and dispatched through the registry.
- Input Parse → Hooks: prompt flow · Prompt and input processing feed the agent loop hooks.
- Hooks → Model API: requests · Loop hooks assemble prompts and call the model boundary.
- Model API → Tool Orchestrator: tool calls · Model responses are translated into tool execution requests.
- Tool Orchestrator → Shell Tool: executes · Shell actions are routed to the shell tool.
- Tool Orchestrator → File Tools: executes · Filesystem edits and reads are routed to file tools.
- Tool Orchestrator → Search Tools: executes · Search and fetch actions are routed to search-oriented tools.
- Permissions → Shell Tool: gates · Shell execution is mediated by permission and sandbox rules.
- Permissions → File Tools: gates · File operations pass through approval and safety checks.
- Bridge → Remote Server: relays · Bridge flows connect local sessions to remote control paths.
- Bridge → State: mirrors · Remote control mirrors session state and UI updates.
- Memory → History: persists · Summaries and memories are derived from transcript history.
- Hooks → Memory: compact/extract · Background hooks trigger memory consolidation and compaction.
- Plugins & MCP → Tool Orchestrator: extends · Plugins and MCP add commands, tools, and hooks to execution.
- Plugins & MCP → Commands: registers · Extension systems can add user-facing commands.
- Telemetry → Model API: observes · Model and API activity is instrumented for analytics and diagnostics.
- Telemetry → Tool Orchestrator: observes · Tool execution and failures feed observability pipelines.