# kurogoma4d/claude-code-server architecture

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

- Interactive diagram: https://gitdiagram.com/kurogoma4d/claude-code-server
- Repository: https://github.com/kurogoma4d/claude-code-server

## Overview

Claude Code Server exposes a browser-based terminal for interactive Claude Code sessions. A browser connects to the Socket.io server, whose event handlers validate the requested working directory and delegate session, input, resize, and termination operations to a PTY manager. The manager starts and tracks Claude CLI processes; output and exit events are streamed back to the browser. The README documents the xterm.js interface and security intent; the HTML implementation was not sampled, so its internal behavior is not shown.

Main entry points: [`src/ptyHandlers.ts`](https://github.com/Kurogoma4D/claude-code-server/blob/main/src/ptyHandlers.ts) (Session event handlers), [`public/index.html`](https://github.com/Kurogoma4D/claude-code-server/blob/main/public/index.html) (Web terminal UI), [`src/server.ts`](https://github.com/Kurogoma4D/claude-code-server/blob/main/src/server.ts) (HTTP and Socket server), [`src/ptyManager.ts`](https://github.com/Kurogoma4D/claude-code-server/blob/main/src/ptyManager.ts) (PTY manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Terminal Client"]
  node_webui["Web terminal UI<br/>[index.html]"]
end

subgraph group_server["Web Server"]
  node_server["HTTP and Socket server<br/>[server.ts]"]
end

subgraph group_sessions["Session Handling"]
  node_handlers["Session event handlers<br/>[ptyHandlers.ts]"]
end

subgraph group_processes["PTY Processes"]
  node_manager["PTY manager<br/>[ptyManager.ts]"]
end

node_user(("Terminal user"))
node_claude["Claude Code CLI"]

node_user -->|"uses"| node_webui
node_webui -->|"connects by WebSocket"| node_server
node_server -->|"serves static files"| node_webui
node_server -->|"dispatches events"| node_handlers
node_handlers -->|"controls PTYs"| node_manager
node_manager -->|"spawns process"| node_claude
node_manager -->|"calls output callbacks"| node_handlers
node_handlers -->|"emits terminal events"| node_webui

click node_webui "https://github.com/Kurogoma4D/claude-code-server/blob/main/public/index.html"
click node_server "https://github.com/Kurogoma4D/claude-code-server/blob/main/src/server.ts"
click node_handlers "https://github.com/Kurogoma4D/claude-code-server/blob/main/src/ptyHandlers.ts"
click node_manager "https://github.com/Kurogoma4D/claude-code-server/blob/main/src/ptyManager.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_webui,node_user toneBlue
class node_server toneAmber
class node_handlers toneMint
class node_manager toneRose
class node_claude toneIndigo
```

## Components

### Terminal Client

- [Web terminal UI](https://github.com/Kurogoma4D/claude-code-server/blob/main/public/index.html): `public/index.html`

### Web Server

- [HTTP and Socket server](https://github.com/Kurogoma4D/claude-code-server/blob/main/src/server.ts): `src/server.ts`

### Session Handling

- [Session event handlers](https://github.com/Kurogoma4D/claude-code-server/blob/main/src/ptyHandlers.ts): `src/ptyHandlers.ts`

### PTY Processes

- [PTY manager](https://github.com/Kurogoma4D/claude-code-server/blob/main/src/ptyManager.ts): `src/ptyManager.ts`

### Other components

- **Terminal user**
- **Claude Code CLI**

## Connections

- Terminal user → Web terminal UI: uses (evidence: `README.md`)
- Web terminal UI → HTTP and Socket server: connects by WebSocket (evidence: `README.md`)
- HTTP and Socket server → Web terminal UI: serves static files (evidence: `src/server.ts`)
- HTTP and Socket server → Session event handlers: dispatches events (evidence: `src/server.ts`)
- Session event handlers → PTY manager: controls PTYs (evidence: `src/ptyHandlers.ts`)
- PTY manager → Claude Code CLI: spawns process (evidence: `src/ptyManager.ts`)
- PTY manager → Session event handlers: calls output callbacks (evidence: `src/ptyManager.ts`)
- Session event handlers → Web terminal UI: emits terminal events (evidence: `src/ptyHandlers.ts`)
