# hoangcoderr/chatgpt-local-coder architecture

> Architecture diagram of the GitHub repository hoangcoderr/chatgpt-local-coder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hoangcoderr/chatgpt-local-coder
- Repository: https://github.com/hoangcoderr/chatgpt-local-coder

## Overview

ChatGPT Local Coder is a self-hosted MCP server that exposes local coding tools to ChatGPT or another MCP client. The main workflow is client request → authenticated HTTP/MCP session → tool dispatch → local filesystem, shell, Git, or configured upstream MCP operation → structured result. Distinct capabilities also include project context and memory, checkpoints/rewind, and a localhost admin surface for configuration. Edges follow README statements and source-index references or excerpts; unsampled implementation details are not inferred.

Main entry points: [`src/server-factory.ts`](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/server-factory.ts) (Tool server factory), [`src/lib/mcp-upstream-manager.ts`](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-upstream-manager.ts) (Upstream manager), [`src/index.ts`](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/index.ts) (HTTP entrypoint), [`src/lib/mcp-session-manager.ts`](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-session-manager.ts) (MCP sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP access"]
  node_entrypoint["HTTP entrypoint<br/>[index.ts]"]
  node_sessions["MCP sessions"]
  node_server["Tool server factory<br/>[server-factory.ts]"]
end

subgraph group_tools["Local coding tools"]
  node_filesystem["Filesystem tools<br/>[filesystem.ts]"]
  node_shell["Shell tools<br/>[shell.ts]"]
  node_git["Git tools<br/>[git.ts]"]
  node_rewind["Checkpoint rewind<br/>[rewind.ts]"]
  node_node_repl["Node REPL<br/>[node-repl.ts]"]
end

subgraph group_context["Project context"]
  node_context_tools["Context tools<br/>[context.ts]"]
  node_instructions["Instruction context"]
  node_memory["Project memory<br/>[project-memory.ts]"]
  node_skills["Project skills<br/>[skills-loader.ts]"]
end

subgraph group_integrations["MCP integrations"]
  node_upstream_manager["Upstream manager"]
  node_upstream_config["Upstream configuration"]
  node_oauth["Upstream OAuth"]
  node_proxy["Tool proxy<br/>[mcp-tool-proxy.ts]"]
  node_bridge["MCP bridge tools<br/>[mcp-bridge.ts]"]
end

subgraph group_admin["Administration"]
  node_admin_server["Admin server<br/>[server.ts]"]
  node_admin_routes["Admin routes<br/>[routes.ts]"]
  node_audit["Activity and audit<br/>[audit.ts]"]
  node_activity_log[("Activity log<br/>[activity-log.ts]")]
end

node_client(("ChatGPT / MCP client"))
node_local_machine[("Local machine")]
node_upstream_services{{"MCP services"}}

node_client -->|"sends MCP requests"| node_entrypoint
node_entrypoint -->|"handles sessions"| node_sessions
node_entrypoint -->|"starts admin"| node_admin_server
node_entrypoint -->|"builds context"| node_instructions
node_sessions -->|"creates server"| node_server
node_sessions -->|"refreshes tools"| node_upstream_manager
node_sessions -->|"refreshes proxies"| node_proxy
node_server -->|"registers tools"| node_filesystem
node_server -->|"registers tools"| node_shell
node_server -->|"registers tools"| node_git
node_server -->|"registers tools"| node_context_tools
node_server -->|"registers tools"| node_rewind
node_server -->|"registers tool"| node_node_repl
node_server -->|"registers tools"| node_bridge
node_server -->|"registers server"| node_upstream_manager
node_server -->|"builds instructions"| node_instructions
node_filesystem -->|"reads and edits files"| node_local_machine
node_shell -->|"runs commands"| node_local_machine
node_git -->|"manages Git"| node_local_machine
node_filesystem -->|"records actions"| node_audit
node_filesystem -->|"creates checkpoints"| node_rewind
node_rewind -->|"records actions"| node_audit
node_context_tools -->|"loads skills"| node_skills
node_instructions -->|"loads project memory"| node_memory
node_instructions -->|"loads skills"| node_skills
node_context_tools -->|"reads statuses"| node_upstream_manager
node_upstream_manager -->|"loads configuration"| node_upstream_config
node_upstream_manager -->|"creates provider"| node_oauth
node_upstream_manager -->|"refreshes proxies"| node_proxy
node_bridge -->|"uses manager"| node_upstream_manager
node_upstream_manager -.->|"connects to servers"| node_upstream_services
node_admin_server -->|"mounts routes"| node_admin_routes
node_admin_server -->|"uses manager"| node_upstream_manager
node_admin_routes -->|"configures upstreams"| node_upstream_manager
node_admin_routes -->|"reads activity"| node_audit
node_audit -->|"appends events"| node_activity_log

click node_entrypoint "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/index.ts"
click node_sessions "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-session-manager.ts"
click node_server "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/server-factory.ts"
click node_filesystem "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/filesystem.ts"
click node_shell "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/shell.ts"
click node_git "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/git.ts"
click node_rewind "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/rewind.ts"
click node_node_repl "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/node-repl.ts"
click node_context_tools "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/context.ts"
click node_instructions "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/instruction-context.ts"
click node_memory "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/project-memory.ts"
click node_skills "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/skills-loader.ts"
click node_upstream_manager "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-upstream-manager.ts"
click node_upstream_config "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-upstream-config.ts"
click node_oauth "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-oauth-provider.ts"
click node_proxy "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-tool-proxy.ts"
click node_bridge "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/mcp-bridge.ts"
click node_admin_server "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/admin/server.ts"
click node_admin_routes "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/admin/routes.ts"
click node_audit "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/audit.ts"
click node_activity_log "https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/activity-log.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_entrypoint,node_sessions,node_server,node_client toneBlue
class node_filesystem,node_shell,node_git,node_rewind,node_node_repl,node_local_machine toneAmber
class node_context_tools,node_instructions,node_memory,node_skills toneMint
class node_upstream_manager,node_upstream_config,node_oauth,node_proxy,node_bridge toneRose
class node_admin_server,node_admin_routes,node_audit,node_activity_log,node_upstream_services toneIndigo
```

## Components

### MCP access

- [HTTP entrypoint](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/index.ts): `src/index.ts`
- [MCP sessions](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-session-manager.ts): `src/lib/mcp-session-manager.ts`
- [Tool server factory](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/server-factory.ts): `src/server-factory.ts`

### Local coding tools

- [Filesystem tools](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/filesystem.ts): `src/tools/filesystem.ts`
- [Shell tools](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/shell.ts): `src/tools/shell.ts`
- [Git tools](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/git.ts): `src/tools/git.ts`
- [Checkpoint rewind](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/rewind.ts): `src/tools/rewind.ts`
- [Node REPL](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/node-repl.ts): `src/tools/node-repl.ts`

### Project context

- [Context tools](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/context.ts): `src/tools/context.ts`
- [Instruction context](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/instruction-context.ts): `src/lib/instruction-context.ts`
- [Project memory](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/project-memory.ts): `src/lib/project-memory.ts`
- [Project skills](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/skills-loader.ts): `src/lib/skills-loader.ts`

### MCP integrations

- [Upstream manager](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-upstream-manager.ts): `src/lib/mcp-upstream-manager.ts`
- [Upstream configuration](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-upstream-config.ts): `src/lib/mcp-upstream-config.ts`
- [Upstream OAuth](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-oauth-provider.ts): `src/lib/mcp-oauth-provider.ts`
- [Tool proxy](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/mcp-tool-proxy.ts): `src/lib/mcp-tool-proxy.ts`
- [MCP bridge tools](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/tools/mcp-bridge.ts): `src/tools/mcp-bridge.ts`

### Administration

- [Admin server](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/admin/server.ts): `src/admin/server.ts`
- [Admin routes](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/admin/routes.ts): `src/admin/routes.ts`
- [Activity and audit](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/audit.ts): `src/lib/audit.ts`
- [Activity log](https://github.com/hoangcoderr/chatgpt-local-coder/blob/main/src/lib/activity-log.ts): `src/lib/activity-log.ts`

### Other components

- **ChatGPT / MCP client**
- **Local machine**
- **MCP services**

## Connections

- ChatGPT / MCP client → HTTP entrypoint: sends MCP requests (evidence: `README.md`)
- HTTP entrypoint → MCP sessions: handles sessions (evidence: `src/index.ts`)
- HTTP entrypoint → Admin server: starts admin (evidence: `src/index.ts`)
- HTTP entrypoint → Instruction context: builds context (evidence: `src/index.ts`)
- MCP sessions → Tool server factory: creates server (evidence: `src/lib/mcp-session-manager.ts`)
- MCP sessions → Upstream manager: refreshes tools (evidence: `src/lib/mcp-session-manager.ts`)
- MCP sessions → Tool proxy: refreshes proxies (evidence: `src/lib/mcp-session-manager.ts`)
- Tool server factory → Filesystem tools: registers tools (evidence: `src/server-factory.ts`)
- Tool server factory → Shell tools: registers tools (evidence: `src/server-factory.ts`)
- Tool server factory → Git tools: registers tools (evidence: `src/server-factory.ts`)
- Tool server factory → Context tools: registers tools (evidence: `src/server-factory.ts`)
- Tool server factory → Checkpoint rewind: registers tools (evidence: `src/server-factory.ts`)
- Tool server factory → Node REPL: registers tool (evidence: `src/server-factory.ts`)
- Tool server factory → MCP bridge tools: registers tools (evidence: `src/server-factory.ts`)
- Tool server factory → Upstream manager: registers server (evidence: `src/server-factory.ts`)
- Tool server factory → Instruction context: builds instructions (evidence: `src/server-factory.ts`)
- Filesystem tools → Local machine: reads and edits files (evidence: `README.md`)
- Shell tools → Local machine: runs commands (evidence: `README.md`)
- Git tools → Local machine: manages Git (evidence: `README.md`)
- Filesystem tools → Activity and audit: records actions (evidence: `src/tools/filesystem.ts`)
- Filesystem tools → Checkpoint rewind: creates checkpoints (evidence: `src/tools/filesystem.ts`)
- Checkpoint rewind → Activity and audit: records actions (evidence: `src/tools/rewind.ts`)
- Context tools → Project skills: loads skills (evidence: `src/tools/context.ts`)
- Instruction context → Project memory: loads project memory (evidence: `src/lib/instruction-context.ts`)
- Instruction context → Project skills: loads skills (evidence: `src/lib/instruction-context.ts`)
- Context tools → Upstream manager: reads statuses (evidence: `src/tools/context.ts`)
- Upstream manager → Upstream configuration: loads configuration (evidence: `src/lib/mcp-upstream-manager.ts`)
- Upstream manager → Upstream OAuth: creates provider (evidence: `src/lib/mcp-upstream-manager.ts`)
- Upstream manager → Tool proxy: refreshes proxies (evidence: `src/lib/mcp-upstream-manager.ts`)
- MCP bridge tools → Upstream manager: uses manager (evidence: `src/tools/mcp-bridge.ts`)
- Upstream manager → MCP services: connects to servers
- Admin server → Admin routes: mounts routes (evidence: `src/admin/server.ts`)
- Admin server → Upstream manager: uses manager (evidence: `src/admin/server.ts`)
- Admin routes → Upstream manager: configures upstreams (evidence: `src/admin/routes.ts`)
- Admin routes → Activity and audit: reads activity (evidence: `src/admin/routes.ts`)
- Activity and audit → Activity log: appends events (evidence: `src/lib/audit.ts`)