# l3tchupkt/claudex architecture

> Architecture diagram of the GitHub repository l3tchupkt/claudex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/l3tchupkt/claudex
- Repository: https://github.com/l3tchupkt/claudex

## Overview

Claudex is a terminal coding assistant fork that runs Claude Code’s tool-and-session workflow against configurable model providers, including OpenAI-compatible services and local inference. Users submit prompts in the terminal; the query engine coordinates model requests and tool use, then the CLI presents results. Documented branches include provider selection, smart routing, Telegram access, and persistent memory. The excerpts support core query, command, session, and state relationships; provider-shim internals and Telegram implementation are not shown, so those links are documented at subsystem level.

Main entry points: [`src/Tool.ts`](https://github.com/l3tchupkt/claudex/blob/main/src/Tool.ts) (Tool system), [`src/QueryEngine.ts`](https://github.com/l3tchupkt/claudex/blob/main/src/QueryEngine.ts) (Query engine), [`src/query.ts`](https://github.com/l3tchupkt/claudex/blob/main/src/query.ts) (Query loop), [`src/utils/sessionStorage.ts`](https://github.com/l3tchupkt/claudex/blob/main/src/utils/sessionStorage.ts) (Session storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["CLI interaction"]
  node_terminal["Terminal app<br/>[App.tsx]"]
  node_commands["Slash commands<br/>[commands.ts]"]
  node_telegram["Telegram gateway"]
end

subgraph group_execution["Assistant execution"]
  node_engine["Query engine<br/>[QueryEngine.ts]"]
  node_query["Query loop<br/>[query.ts]"]
  node_tooling["Tool system<br/>[Tool.ts]"]
  node_coding["Coding tools"]
  node_mcp["MCP integration"]
  node_lsp["LSP integration"]
end

subgraph group_providers["Model access"]
  node_provider["Provider shim"]
  node_model(("Model providers"))
  node_router["Smart router"]
end

subgraph group_state["Sessions and state"]
  node_session[("Session storage<br/>[sessionStorage.ts]")]
  node_portable[("Portable transcripts")]
  node_bootstrap["Runtime state<br/>[state.ts]"]
  node_memory[("Persistent memory")]
end

node_user(("CLI user"))

node_user -->|"enters prompts"| node_terminal
node_user -->|"runs commands"| node_commands
node_user -.->|"uses gateway"| node_telegram
node_terminal -->|"initializes state"| node_bootstrap
node_engine -->|"loads commands"| node_commands
node_engine -->|"coordinates tools"| node_tooling
node_engine -->|"uses query loop"| node_query
node_query -->|"dispatches tools"| node_tooling
node_tooling -->|"provides coding tools"| node_coding
node_tooling -->|"supports MCP"| node_mcp
node_tooling -->|"supports LSP"| node_lsp
node_query -.->|"requests completions"| node_provider
node_provider -->|"translates requests"| node_model
node_router -.->|"selects provider"| node_model
node_query -.->|"uses session history"| node_session
node_session -->|"reads transcripts"| node_portable
node_session -->|"reads runtime state"| node_bootstrap
node_engine -.->|"supports memory"| node_memory

click node_terminal "https://github.com/l3tchupkt/claudex/blob/main/src/ink/components/App.tsx"
click node_commands "https://github.com/l3tchupkt/claudex/blob/main/src/commands.ts"
click node_telegram "https://github.com/l3tchupkt/claudex/tree/main/src/commands/telegram"
click node_engine "https://github.com/l3tchupkt/claudex/blob/main/src/QueryEngine.ts"
click node_query "https://github.com/l3tchupkt/claudex/blob/main/src/query.ts"
click node_tooling "https://github.com/l3tchupkt/claudex/blob/main/src/Tool.ts"
click node_coding "https://github.com/l3tchupkt/claudex/tree/main/src/tools"
click node_mcp "https://github.com/l3tchupkt/claudex/blob/main/src/services/mcp/MCPConnectionManager.tsx"
click node_lsp "https://github.com/l3tchupkt/claudex/blob/main/src/services/lsp/LSPServerManager.ts"
click node_provider "https://github.com/l3tchupkt/claudex/tree/main/src/services/api"
click node_router "https://github.com/l3tchupkt/claudex/tree/main/src/services/api"
click node_session "https://github.com/l3tchupkt/claudex/blob/main/src/utils/sessionStorage.ts"
click node_portable "https://github.com/l3tchupkt/claudex/blob/main/src/utils/sessionStoragePortable.ts"
click node_bootstrap "https://github.com/l3tchupkt/claudex/blob/main/src/bootstrap/state.ts"
click node_memory "https://github.com/l3tchupkt/claudex/tree/main/src/memdir"

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_terminal,node_commands,node_telegram,node_user toneBlue
class node_engine,node_query,node_tooling,node_coding,node_mcp,node_lsp toneAmber
class node_provider,node_model,node_router toneMint
class node_session,node_portable,node_bootstrap,node_memory toneRose
```

## Components

### CLI interaction

- [Terminal app](https://github.com/l3tchupkt/claudex/blob/main/src/ink/components/App.tsx): `src/ink/components/App.tsx`
- [Slash commands](https://github.com/l3tchupkt/claudex/blob/main/src/commands.ts): `src/commands.ts`
- [Telegram gateway](https://github.com/l3tchupkt/claudex/tree/main/src/commands/telegram): `src/commands/telegram`

### Assistant execution

- [Query engine](https://github.com/l3tchupkt/claudex/blob/main/src/QueryEngine.ts): `src/QueryEngine.ts`
- [Query loop](https://github.com/l3tchupkt/claudex/blob/main/src/query.ts): `src/query.ts`
- [Tool system](https://github.com/l3tchupkt/claudex/blob/main/src/Tool.ts): `src/Tool.ts`
- [Coding tools](https://github.com/l3tchupkt/claudex/tree/main/src/tools): `src/tools`
- [MCP integration](https://github.com/l3tchupkt/claudex/blob/main/src/services/mcp/MCPConnectionManager.tsx): `src/services/mcp/MCPConnectionManager.tsx`
- [LSP integration](https://github.com/l3tchupkt/claudex/blob/main/src/services/lsp/LSPServerManager.ts): `src/services/lsp/LSPServerManager.ts`

### Model access

- [Provider shim](https://github.com/l3tchupkt/claudex/tree/main/src/services/api): `src/services/api`
- **Model providers**
- [Smart router](https://github.com/l3tchupkt/claudex/tree/main/src/services/api): `src/services/api`

### Sessions and state

- [Session storage](https://github.com/l3tchupkt/claudex/blob/main/src/utils/sessionStorage.ts): `src/utils/sessionStorage.ts`
- [Portable transcripts](https://github.com/l3tchupkt/claudex/blob/main/src/utils/sessionStoragePortable.ts): `src/utils/sessionStoragePortable.ts`
- [Runtime state](https://github.com/l3tchupkt/claudex/blob/main/src/bootstrap/state.ts): `src/bootstrap/state.ts`
- [Persistent memory](https://github.com/l3tchupkt/claudex/tree/main/src/memdir): `src/memdir`

### Other components

- **CLI user**

## Connections

- CLI user → Terminal app: enters prompts (evidence: `README.md`)
- CLI user → Slash commands: runs commands (evidence: `src/commands.ts`)
- CLI user → Telegram gateway: uses gateway (evidence: `README.md`)
- Terminal app → Runtime state: initializes state (evidence: `src/ink/components/App.tsx`)
- Query engine → Slash commands: loads commands (evidence: `src/QueryEngine.ts`)
- Query engine → Tool system: coordinates tools (evidence: `src/QueryEngine.ts`)
- Query engine → Query loop: uses query loop (evidence: `src/QueryEngine.ts`)
- Query loop → Tool system: dispatches tools (evidence: `src/query.ts`)
- Tool system → Coding tools: provides coding tools (evidence: `README.md`)
- Tool system → MCP integration: supports MCP (evidence: `README.md`)
- Tool system → LSP integration: supports LSP (evidence: `README.md`)
- Query loop → Provider shim: requests completions (evidence: `README.md`)
- Provider shim → Model providers: translates requests (evidence: `README.md`)
- Smart router → Model providers: selects provider (evidence: `README.md`)
- Query loop → Session storage: uses session history (evidence: `src/query.ts`)
- Session storage → Portable transcripts: reads transcripts (evidence: `src/utils/sessionStorage.ts`)
- Session storage → Runtime state: reads runtime state (evidence: `src/utils/sessionStorage.ts`)
- Query engine → Persistent memory: supports memory (evidence: `README.md`)
