# housetan218/claude-code-haha architecture

> Architecture diagram of the GitHub repository housetan218/claude-code-haha, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/housetan218/claude-code-haha
- Repository: https://github.com/housetan218/claude-code-haha

## Overview

1. **This is a terminal-first AI agent client, not a web app.**  
   The repository packages a Claude Code–style interactive TUI plus a `--print` headless mode, all running on Bun/TypeScript with React + Ink for terminal rendering. The main external dependency boundary is an Anthropic-compatible API endpoint, which can be customized for providers like MiniMax or OpenRouter.

2. **Launch path starts at the wrapper script and preload.**  
   `bin/claude-haha` is the user-facing executable, `preload.ts` prepares runtime globals/environment, and `src/entrypoints/cli.tsx` is the main CLI entry. From there the app can route into the full TUI, headless print mode, or the recovery CLI fallback in `src/localRecoveryCli.ts`.

3. **Startup and session bootstrap form the first major subsystem.**  
   `src/setup.ts`, `src/bootstrap/*`, `src/state/*`, and `src/projectOnboardingState.ts` establish app state, settings, workspace context, and session identity before the interface becomes interactive. This is where environment/config, user settings, and persisted session data are loaded and normalized.

4. **The terminal UI is a React/Ink application with custom rendering infrastructure.**  
   `src/main.tsx`, `src/screens/*`, `src/components/*`, and the large `src/ink/*` subtree make up the interactive interface. Ink is not just used as a component library here; the repo includes a substantial custom terminal renderer, event system, layout engine, and text measurement logic, which is a key architectural boundary for diagramming.

5. **User input flows through command parsing, keybinding resolution, and prompt processors.**  
   Keystrokes and slash commands are handled through `src/keybindings/*`, `src/commands/*`, and `src/utils/processUserInput/*`. The app distinguishes freeform prompts, slash commands, and shell-style inputs, then routes them into the appropriate execution or UI action.

6. **The agent/tool execution pipeline is the core runtime loop.**  
   `src/tools/*`, `src/services/tools/*`, `src/query/*`, `src/QueryEngine.ts`, `src/Task.ts`, and `src/tasks/*` model the work the assistant performs. Tool implementations cover file I/O, bash/powershell, LSP, web fetch/search, MCP, tasks, agents, and remote triggers; `services/tools/*` orchestrates streaming execution, hooks, and result aggregation.

7. **Permissions and sandboxing are a major architectural boundary.**  
   Tool use is mediated by `src/hooks/toolPermission/*`, `src/components/permissions/*`, `src/utils/permissions/*`, and sandbox-related code under `src/components/sandbox/*` and `src/utils/sandbox/*`. This boundary decides whether a tool can run, whether user approval is required, and how destructive or risky commands are classified.

8. **Conversation state, history, and memory are tracked separately from the UI.**  
   `src/history.ts`, `src/assistant/sessionHistory.ts`, `src/hooks/useAssistantHistory.ts`, `src/memdir/*`, and `src/services/SessionMemory/*` handle message history, memory files, summaries, and retrieval. This data layer feeds prompt construction and session resume/rewind features.

9. **There is a substantial integration layer for remote/control-plane workflows.**  
   `src/bridge/*`, `src/remote/*`, `src/server/*`, `src/upstreamproxy/*`, and `src/services/oauth/*` support remote sessions, bridges, direct connect, and authenticated control channels. These modules separate local interactive execution from remote session management and transport concerns.

10. **MCP, LSP, plugins, and skills are the extensibility surface.**  
   `src/services/mcp/*`, `src/services/lsp/*`, `src/plugins/*`, `src/skills/*`, and the corresponding UI/command surfaces in `src/components/mcp/*`, `src/components/agents/*`, and `src/commands/*` provide pluggable capabilities. Skills and plugins extend behavior, MCP exposes external tool servers, and LSP adds code-aware operations.

11. **Supporting services handle model selection, usage, telemetry, and safety.**  
   `src/services/api/*`, `src/services/analytics/*`, `src/services/compact/*`, `src/services/voice*`, `src/services/tokenEstimation.ts`, and rate-limit / policy modules manage network calls, cost-aware behavior, telemetry, and operational constraints. The app is designed to adapt model choice, prompt size, and usage reporting without coupling those concerns to the UI.

12. **Persistence and configuration are file- and settings-driven.**  
   `src/utils/settings/*`, `src/services/settingsSync/*`, `src/services/remoteManagedSettings/*`, `src/utils/sessionStorage*`, and `src/migrations/*` show a strong local-state model with migrations and sync layers. The app persists workspace/session configuration, permissions, plugins, and user preferences across runs.

13. **A “session/task” model ties everything together.**  
   Background work is represented as tasks (`src/tasks/*`), with UI views, status indicators, and resumable execution paths. This makes the app’s main flow: user input → command/tool selection → permission gate → task execution → streamed messages/UI updates → persisted history/state.

14. **One important diagram boundary is the recovery/fallback path.**  
   The project explicitly supports a simplified recovery CLI when the full Ink UI cannot start. That means the architecture has two operational modes: the primary interactive TUI and a minimal fallback shell for degraded startup conditions.

Main entry points: [`src/QueryEngine.ts`](https://github.com/housetan218/claude-code-haha/blob/main/src/QueryEngine.ts) (Tool loop), [`src/components/App.tsx`](https://github.com/housetan218/claude-code-haha/blob/main/src/components/App.tsx) (UI components), [`src/entrypoints/cli.tsx`](https://github.com/housetan218/claude-code-haha/blob/main/src/entrypoints/cli.tsx) (CLI entry), [`src/main.tsx`](https://github.com/housetan218/claude-code-haha/blob/main/src/main.tsx) (Main UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & entry"]
  node_bin_cli["CLI shim<br/>executable wrapper"]
  node_preload["Preload<br/>runtime bootstrap<br/>[preload.ts]"]
  node_cli_entry["CLI entry<br/>command router<br/>[cli.tsx]"]
  node_recovery_cli["Recovery CLI<br/>fallback shell"]
end

subgraph group_ui["Terminal UI"]
  node_main_tui["Main UI<br/>Ink app<br/>[main.tsx]"]
  node_ink_engine["Ink engine<br/>terminal renderer<br/>[renderer.ts]"]
  node_screens["Screens<br/>view layer<br/>[REPL.tsx]"]
  node_components["UI components<br/>widget library<br/>[App.tsx]"]
end

subgraph group_agent["Agent runtime"]
  node_input_cmds["Input routing<br/>command/input parser"]
  node_tool_loop["Tool loop<br/>agent runtime<br/>[QueryEngine.ts]"]
  node_toolset["Tools<br/>tool plugins<br/>[tools.ts]"]
  node_permissions["Permissions<br/>policy gate"]
  node_tasks["Tasks<br/>work tracking<br/>[tasks.ts]"]
end

subgraph group_integrations["Integrations"]
  node_remote["Remote control<br/>transport layer<br/>[bridgeMain.ts]"]
  node_mcp_lsp_plugins["Extensions<br/>extensibility layer"]
  node_service_api["Model/API services<br/>service boundary<br/>[client.ts]"]
end

subgraph group_state["State & persistence"]
  node_setup_bootstrap["Bootstrap<br/>startup pipeline<br/>[setup.ts]"]
  node_app_state["App state<br/>session store<br/>[AppState.tsx]"]
  node_settings["Settings<br/>config store<br/>[settings.ts]"]
  node_history_mem["History & memory<br/>conversation store<br/>[history.ts]"]
end

node_bin_cli -->|"starts"| node_preload
node_preload -->|"boots"| node_cli_entry
node_cli_entry -->|"interactive"| node_main_tui
node_cli_entry -->|"fallback"| node_recovery_cli
node_cli_entry -->|"initializes"| node_setup_bootstrap
node_setup_bootstrap -->|"loads"| node_settings
node_setup_bootstrap -->|"seeds"| node_app_state
node_setup_bootstrap -->|"restores"| node_history_mem
node_main_tui -->|"renders with"| node_ink_engine
node_main_tui -->|"navigates"| node_screens
node_main_tui -->|"composes"| node_components
node_components -->|"captures input"| node_input_cmds
node_input_cmds -->|"dispatches"| node_tool_loop
node_tool_loop -->|"uses"| node_toolset
node_tool_loop -->|"gates"| node_permissions
node_tool_loop -->|"tracks"| node_tasks
node_tool_loop -->|"records"| node_history_mem
node_tasks -->|"status UI"| node_components
node_permissions -->|"prompts"| node_components
node_remote -->|"drives"| node_tool_loop
node_remote -->|"bridges"| node_permissions
node_mcp_lsp_plugins -->|"extends"| node_toolset
node_mcp_lsp_plugins -->|"configures UI"| node_components
node_service_api -->|"serves model"| node_tool_loop
node_service_api -->|"reads config"| node_settings

click node_bin_cli "https://github.com/housetan218/claude-code-haha/tree/main/bin/claude-haha"
click node_preload "https://github.com/housetan218/claude-code-haha/blob/main/preload.ts"
click node_cli_entry "https://github.com/housetan218/claude-code-haha/blob/main/src/entrypoints/cli.tsx"
click node_recovery_cli "https://github.com/housetan218/claude-code-haha/blob/main/src/localRecoveryCli.ts"
click node_setup_bootstrap "https://github.com/housetan218/claude-code-haha/blob/main/src/setup.ts"
click node_app_state "https://github.com/housetan218/claude-code-haha/blob/main/src/state/AppState.tsx"
click node_settings "https://github.com/housetan218/claude-code-haha/blob/main/src/utils/settings/settings.ts"
click node_history_mem "https://github.com/housetan218/claude-code-haha/blob/main/src/history.ts"
click node_main_tui "https://github.com/housetan218/claude-code-haha/blob/main/src/main.tsx"
click node_ink_engine "https://github.com/housetan218/claude-code-haha/blob/main/src/ink/renderer.ts"
click node_screens "https://github.com/housetan218/claude-code-haha/blob/main/src/screens/REPL.tsx"
click node_components "https://github.com/housetan218/claude-code-haha/blob/main/src/components/App.tsx"
click node_input_cmds "https://github.com/housetan218/claude-code-haha/blob/main/src/utils/processUserInput/processUserInput.ts"
click node_tool_loop "https://github.com/housetan218/claude-code-haha/blob/main/src/QueryEngine.ts"
click node_toolset "https://github.com/housetan218/claude-code-haha/blob/main/src/tools.ts"
click node_permissions "https://github.com/housetan218/claude-code-haha/blob/main/src/hooks/toolPermission/PermissionContext.ts"
click node_tasks "https://github.com/housetan218/claude-code-haha/blob/main/src/tasks.ts"
click node_remote "https://github.com/housetan218/claude-code-haha/blob/main/src/bridge/bridgeMain.ts"
click node_mcp_lsp_plugins "https://github.com/housetan218/claude-code-haha/blob/main/src/services/mcp/MCPConnectionManager.tsx"
click node_service_api "https://github.com/housetan218/claude-code-haha/blob/main/src/services/api/client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bin_cli,node_preload,node_cli_entry,node_recovery_cli toneBlue
class node_main_tui,node_ink_engine,node_screens,node_components toneAmber
class node_input_cmds,node_tool_loop,node_toolset,node_permissions,node_tasks toneMint
class node_remote,node_mcp_lsp_plugins,node_service_api toneRose
class node_setup_bootstrap,node_app_state,node_settings,node_history_mem toneIndigo
```

## Components

### Runtime & entry

Executable entrypoints, preload, startup, and fallback modes.

- [CLI shim](https://github.com/housetan218/claude-code-haha/tree/main/bin/claude-haha): executable wrapper · User-facing Bun launcher for the app. · `bin/claude-haha`
- [Preload](https://github.com/housetan218/claude-code-haha/blob/main/preload.ts): runtime bootstrap · Prepares globals and process environment before app startup. · `preload.ts`
- [CLI entry](https://github.com/housetan218/claude-code-haha/blob/main/src/entrypoints/cli.tsx): command router · Main entrypoint that dispatches interactive, print, and fallback modes. · `src/entrypoints/cli.tsx`
- [Recovery CLI](https://github.com/housetan218/claude-code-haha/blob/main/src/localRecoveryCli.ts): fallback shell · Minimal degraded-mode interface when the full TUI cannot start. · `src/localRecoveryCli.ts`

### Terminal UI

Interactive Ink/React rendering, screens, and user interaction surfaces.

- [Main UI](https://github.com/housetan218/claude-code-haha/blob/main/src/main.tsx): Ink app · Top-level interactive terminal application shell. · `src/main.tsx`
- [Ink engine](https://github.com/housetan218/claude-code-haha/blob/main/src/ink/renderer.ts): terminal renderer · Custom terminal rendering, layout, events, and text measurement. · `src/ink/renderer.ts`
- [Screens](https://github.com/housetan218/claude-code-haha/blob/main/src/screens/REPL.tsx): view layer · Major app views such as REPL, doctor, and resume flows. · `src/screens/REPL.tsx`
- [UI components](https://github.com/housetan218/claude-code-haha/blob/main/src/components/App.tsx): widget library · Prompt input, messages, dialogs, permissions, tasks, and status UI. · `src/components/App.tsx`

### Agent runtime

Prompt handling, tools, tasks, permissions, history, and execution loop.

- [Input routing](https://github.com/housetan218/claude-code-haha/blob/main/src/utils/processUserInput/processUserInput.ts): command/input parser · Keybindings, slash commands, and user-input processing. · `src/utils/processUserInput/processUserInput.ts`
- [Tool loop](https://github.com/housetan218/claude-code-haha/blob/main/src/QueryEngine.ts): agent runtime · Query engine, task model, and streamed tool execution orchestration. · `src/QueryEngine.ts`
- [Tools](https://github.com/housetan218/claude-code-haha/blob/main/src/tools.ts): tool plugins · Built-in tools for files, shell, web, MCP, LSP, tasks, and agents. · `src/tools.ts`
- [Permissions](https://github.com/housetan218/claude-code-haha/blob/main/src/hooks/toolPermission/PermissionContext.ts): policy gate · Approval, sandboxing, and risk classification for tool use. · `src/hooks/toolPermission/PermissionContext.ts`
- [Tasks](https://github.com/housetan218/claude-code-haha/blob/main/src/tasks.ts): work tracking · Background and resumable task representations tied to execution. · `src/tasks.ts`

### Integrations

Remote control, MCP/LSP/plugins, and external service boundaries.

- [Remote control](https://github.com/housetan218/claude-code-haha/blob/main/src/bridge/bridgeMain.ts): transport layer · Bridges, sessions, upstream proxy, and remote execution/control paths. · `src/bridge/bridgeMain.ts`
- [Extensions](https://github.com/housetan218/claude-code-haha/blob/main/src/services/mcp/MCPConnectionManager.tsx): extensibility layer · MCP, LSP, plugins, and skills that extend agent capability. · `src/services/mcp/MCPConnectionManager.tsx`
- [Model/API services](https://github.com/housetan218/claude-code-haha/blob/main/src/services/api/client.ts): service boundary · Model selection, API access, usage, compaction, analytics, and telemetry. · `src/services/api/client.ts`

### State & persistence

Settings, session state, memory, and storage layers.

- [Bootstrap](https://github.com/housetan218/claude-code-haha/blob/main/src/setup.ts): startup pipeline · Loads config, workspace context, settings, and session identity. · `src/setup.ts`
- [App state](https://github.com/housetan218/claude-code-haha/blob/main/src/state/AppState.tsx): session store · Central application state and selectors shared across runtime. · `src/state/AppState.tsx`
- [Settings](https://github.com/housetan218/claude-code-haha/blob/main/src/utils/settings/settings.ts): config store · User and workspace settings, sync, validation, and migrations. · `src/utils/settings/settings.ts`
- [History & memory](https://github.com/housetan218/claude-code-haha/blob/main/src/history.ts): conversation store · Message history, memory files, summaries, and session retrieval. · `src/history.ts`

## Connections

- CLI shim → Preload: starts · Wrapper launches the preload phase.
- Preload → CLI entry: boots · Preload hands off to the main CLI entrypoint.
- CLI entry → Main UI: interactive · Routes normal sessions into the full terminal UI.
- CLI entry → Recovery CLI: fallback · Routes degraded startup into the recovery CLI.
- CLI entry → Bootstrap: initializes · Creates startup context before interactive rendering begins.
- Bootstrap → Settings: loads · Bootstrap normalizes configuration and persisted settings.
- Bootstrap → App state: seeds · Bootstrap creates initial session and workspace state.
- Bootstrap → History & memory: restores · Bootstrap restores prior conversation and memory context.
- Main UI → Ink engine: renders with · UI is built on the custom Ink terminal renderer.
- Main UI → Screens: navigates · Main UI switches between primary screens and flows.
- Main UI → UI components: composes · Screens are assembled from reusable terminal components.
- UI components → Input routing: captures input · Prompt widgets and keybinding surfaces feed user input routing.
- Input routing → Tool loop: dispatches · Parsed prompts and commands enter the agent execution loop.
- Tool loop → Tools: uses · The runtime loop selects and runs tools.
- Tool loop → Permissions: gates · Tool execution is mediated by approval and sandbox policy.
- Tool loop → Tasks: tracks · Execution is represented and resumed through task state.
- Tool loop → History & memory: records · Agent turns and summaries are persisted into history/memory.
- Tasks → UI components: status UI · Task progress and resumable work are surfaced in the terminal UI.
- Permissions → UI components: prompts · Approval flows are rendered as dialogs and request views.
- Remote control → Tool loop: drives · Remote sessions can feed the same execution pipeline.
- Remote control → Permissions: bridges · Remote workflows include permission callbacks and policy sync.
- Extensions → Tools: extends · Extensions add tools, commands, and capabilities.
- Extensions → UI components: configures UI · Extension management is exposed through terminal screens and dialogs.
- Model/API services → Tool loop: serves model · Model/API services provide completion, compaction, and usage plumbing.
- Model/API services → Settings: reads config · Model and service behavior is shaped by persisted settings.