How nirholas/claude-code works
1. This repo is a Bun/TypeScript monorepo centered on a terminal-first Claude Code client, with two major adjacent deliverables: a Next.js-based web companion app under web/ and a separate MCP explorer server under mcp-server/. The core product lives in src/.
2. The main runtime path starts at src/main.tsx and the src/entrypoints/* modules. Startup does environment/bootstrap work, loads settings and auth state, initializes feature flags/telemetry, then mounts the React + Ink terminal UI from src/components/ and src/ink/.
3. The central control loop is the query pipeline: src/QueryEngine.ts plus src/query/ and src/services/tools/. This is where user prompts become LLM requests, streaming responses, tool calls, retries, token accounting, and turn transitions. It is the orchestration boundary for “assistant talks, decides, uses tools, continues.”
4. Tool execution is a first-class subsystem. Each tool in src/tools/* owns its schema, UI, permission expectations, and execution logic. The main categories are file editing/search, shell execution, web access, MCP/LSP access, sub-agents, task/team coordination, and mode/state toggles like plan mode or worktree mode.
5. Permissions are enforced as a cross-cutting boundary rather than a single gate. src/hooks/toolPermission/ and src/utils/permissions/ decide whether a tool action is allowed, denied, or escalated to user approval, with special handling for shell/file operations, plan mode, sandboxing, and bypass/auto modes. This layer sits directly in the tool invocation path.
6. The UI is split between an Ink terminal app and reusable UI primitives. src/components/ contains the terminal screens, dialogs, permission prompts, task views, command palettes, and message renderers, while src/ink/ provides the custom terminal renderer/runtime that powers the TUI. The state driving these views lives in src/state/, src/context/, and hooks under src/hooks/.
7. Slash commands are another major entry path. src/commands.ts registers the command set, and src/commands/* implements discrete workflows such as /review, /compact, /config, /mcp, /memory, /tasks, /resume, /doctor, /share, and /desktop. Commands are user-facing orchestration, usually calling into the same services and state as the main chat loop.
8. External integration logic is concentrated in src/services/. This includes Anthropic API access, OAuth, analytics/feature flags, LSP management, MCP connection management, plugin loading, compacting conversations, memory extraction/sync, policy limits, and managed settings. These services form the “infrastructure layer” beneath both commands and tools.
9. IDE and REPL collaboration runs through the bridge subsystem in src/bridge/. That layer provides bidirectional messaging, session control, permission callbacks, JWT/auth helpers, and REPL bridge transport so external editors like VS Code or JetBrains can coordinate with the CLI session.
10. The repo supports multi-agent and background work through several connected subsystems: src/coordinator/, src/tasks/, src/tools/AgentTool, src/services/tools/, and src/utils/swarm/. Together they model local shell tasks, remote agent tasks, in-process teammates, agent spawning, task lifecycle, and team/multi-worker coordination.
11. Persistence and session continuity are handled by src/utils/session*, src/history.ts, src/memdir/, src/services/teamMemorySync/, and remote/session code under src/remote/ and src/server/. This is where conversation history, memory files, resumable sessions, remote session transport, and server-side session management are kept separate from the live query loop.
12. Plugins, skills, and output styling extend the core without changing it. src/plugins/ and src/skills/ load user/bundled extensions; src/outputStyles/ adjusts presentation; src/constants/ and src/schemas/ define shared configuration and validation contracts. This keeps extension points modular around the core tool/query pipeline.
13. The web/ package is a companion client, not a thin asset bundle. It has its own API routes for chat, export, file read/write, and share, plus a collaboration layer, notifications, file viewer, and streaming/chat UI. It likely consumes the same conversation/file/session concepts as the CLI, but through HTTP and browser state instead of Ink.
14. Operationally, the repo is built around local execution plus external services: Anthropic for model calls, GrowthBook/analytics for feature flags and telemetry, OAuth/JWT/keychain for auth, LSP/MCP for tool ecosystems, and Git/GitHub for repo-aware workflows. For an architecture diagram, the main boundaries are: terminal UI, query/tool orchestration, permission gate, service integrations, bridge/remote transport, and the separate web/MCP packages.
Main entry points: QueryEngine.ts Query engine · services Services · scripts Build scripts · app Web app
Components 18
Core CLI
Terminal-first Claude Code client and its orchestration/runtime layers.
- Main entry · Starts the Bun app, performs startup/bootstrap, and mounts the terminal UI.
src/main.tsx - Entrypoints · CLI, init, MCP, and SDK-facing entry modules that fan into the core app.
src/entrypoints - Query engine · Central assistant loop: prompt handling, streaming turns, retries, tool calls, and token/turn transitions.
src/QueryEngine.ts - Tools · All tool implementations and schemas for file, shell, web, MCP/LSP, agents, tasks, and mode toggles.
src/tools - Permissions · Cross-cutting tool approval, denial, and escalation logic for shell, file, sandbox, and auto modes.
src/hooks/toolPermission - TUI + UI · Ink runtime, reusable React components, prompts, dialogs, and message renderers for the terminal client.
src/components - Slash commands · Command registry and discrete workflows such as review, compact, config, mcp, memory, tasks, resume, and desktop.
src/commands.ts - Services · Model API, auth, analytics, MCP/LSP, plugin, memory, compacting, policy, voice, and other shared integrations.
src/services - Bridge · Bidirectional editor/REPL bridge with session control, messaging, permissions, and auth helpers.
src/bridge - Tasks + swarm · Background tasks, teammates, coordinator logic, and swarm utilities for local and remote parallel work.
src/tasks - State + context · Application state, context providers, stores, and selectors that drive the UI and execution flow.
src/state - Shared utils · Repository-wide helpers for sessions, permissions, prompts, files, git, telemetry, plugins, and runtime plumbing.
src/utils
Web Companion
Next.js browser client and API surface.
- Web app · Browser companion app with its own API routes, chat UI, collaboration, file viewing, and export surfaces.
web/app - Web libs · Client-side API adapters, stores, collaboration, performance, search, export, and compatibility helpers.
web/lib - Web UI · Chat, file viewer, command palette, settings, notifications, and shared browser components.
web/components
MCP Server
Standalone MCP explorer/server package.
- MCP server · Separate MCP explorer/server package with HTTP/server bootstrapping.
mcp-server/src
Shared Infra
Build, packaging, and repository-level tooling.
- Build scripts · Repository scripts for bundling, dev, testing, packaging, and CI builds.
scripts - Repo config · Top-level package, lockfile, Docker, CI, and deployment configuration.
package.json
Connections 21
- Main entry → Entrypoints: boots via · Startup routes through CLI/init/MCP entrypoints before the app is mounted.
- Entrypoints → Query engine: starts loop · Entrypoints initialize and hand control to the query orchestration pipeline.
- Query engine → Tools: invokes tools · The assistant loop dispatches tool schemas and execution requests.
- Tools → Permissions: checks access · Tool execution consults the permission gate before performing sensitive actions.
- Permissions → TUI + UI: prompts user · Denied or escalated actions surface approval dialogs and permission UI.
- Query engine → Services: uses services · Query orchestration depends on model, memory, compacting, and infrastructure services.
- Slash commands → Services: calls workflows · Slash commands reuse service-layer integrations and orchestration helpers.
- Slash commands → Query engine: shares loop · Many commands delegate back into the same core assistant/session machinery.
- TUI + UI → State + context: reads state · Screens and dialogs are driven by centralized app state and context providers.
- State + context → Shared utils: built on · State management depends on shared session, prompt, permission, and persistence utilities.
- Bridge → Services: integrates · Bridge sessions reuse auth, session, and messaging services.
- Bridge → Query engine: coordinates · External editors and REPL sessions coordinate with the live assistant loop.
- Tasks + swarm → Tools: spawns work · Agent/task coordination uses tool execution to perform background work.
- Tasks + swarm → Permissions: polls permissions · Multi-agent and worker flows still pass through the same approval model.
- Web app → Web libs: uses · Server routes and browser pages share client, export, collaboration, and store logic.
- Web app → Web UI: renders · The Next.js app is assembled from browser UI components and layouts.
- Web UI → Web libs: drives · UI components depend on shared browser libraries, stores, and helpers.
- MCP server → Services: bridges to core · The standalone MCP server relies on shared service/integration patterns from the main repo.
- Build scripts → Repo config: orchestrates · Scripts are governed by the workspace package and deployment configuration.
- Build scripts → Web app: builds · One script path specifically builds the web companion package.
- Build scripts → MCP server: packages · Separate scripts and workflows produce the MCP server artifacts.