# int04/chatcmd architecture

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

- Interactive diagram: https://gitdiagram.com/int04/chatcmd
- Repository: https://github.com/int04/chatcmd

## Overview

ChatCMD is a self-hosted MCP bridge that lets AI clients use permission-scoped tools on a local machine. A client connects through the MCP server; tool dispatch applies authorization and invokes terminal, filesystem, Git, process, skill, or task capabilities. The server persists local state and exposes a management API and live events to the React console. An optional browser extension bridges ChatGPT conversations and can provide a sub-agent fallback. The README documents these capabilities; sampled source confirms the route, persistence, and event boundaries, but not every internal dispatch call.

Main entry points: [`src/api/routes.rs`](https://github.com/int04/chatcmd/blob/main/src/api/routes.rs) (Local API), [`src/runtime_host.rs`](https://github.com/int04/chatcmd/blob/main/src/runtime_host.rs) (Runtime host), [`src/runtime_host/dispatch.rs`](https://github.com/int04/chatcmd/blob/main/src/runtime_host/dispatch.rs) (Tool dispatch), [`web/src/App.tsx`](https://github.com/int04/chatcmd/blob/main/web/src/App.tsx) (Management console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_mcp_http["MCP HTTP<br/>[http_transport.rs]"]
  node_mcp_server["MCP server<br/>[mcp_server.rs]"]
  node_api["Local API<br/>[routes.rs]"]
  node_ws["Live events<br/>[mod.rs]"]
end

subgraph group_control["Control plane"]
  node_host["Runtime host<br/>[runtime_host.rs]"]
  node_dispatch["Tool dispatch<br/>[dispatch.rs]"]
  node_approval["Authorization<br/>[approval.rs]"]
  node_subagents["Sub-agent lifecycle<br/>[subagents.rs]"]
end

subgraph group_execution["Local execution"]
  node_machine_tools["Machine tools<br/>[services.rs]"]
  node_shell["PTY terminals<br/>[shell.rs]"]
  node_skills["Skill discovery<br/>[skill_service.rs]"]
  node_chatgpt_bridge["ChatGPT bridge<br/>[chatgpt.rs]"]
  node_extension["Browser extension<br/>[background.js]"]
end

subgraph group_state["Persistence"]
  node_repository[("SQLite repository<br/>[repository.rs]")]
  node_compact["Compact sessions<br/>[mod.rs]"]
end

subgraph group_interfaces["User interfaces"]
  node_webapp["Management console<br/>[App.tsx]"]
  node_tasks_ui["Task supervision<br/>[TasksPage.tsx]"]
  node_agents_ui["Access profiles<br/>[AgentsPage.tsx]"]
end

node_mcp_client(("MCP client"))
node_operator(("Local operator"))
node_chatgpt(("ChatGPT browser"))

node_mcp_client -->|"sends MCP requests"| node_mcp_http
node_mcp_http -->|"forwards requests"| node_mcp_server
node_mcp_server -->|"invokes runtime"| node_host
node_host -->|"dispatches tools"| node_dispatch
node_dispatch -->|"checks permission"| node_approval
node_dispatch -->|"invokes tools"| node_machine_tools
node_dispatch -->|"controls terminals"| node_shell
node_dispatch -->|"discovers skills"| node_skills
node_host -->|"coordinates agents"| node_subagents
node_host -->|"persists state"| node_repository
node_api -->|"reads and writes"| node_repository
node_api -->|"handles bridge routes"| node_chatgpt_bridge
node_chatgpt_bridge -.->|"exchanges requests"| node_extension
node_extension -.->|"drives conversations"| node_chatgpt
node_api -->|"manages compact jobs"| node_compact
node_compact -->|"stores checkpoints"| node_repository
node_host -->|"publishes activity"| node_ws
node_ws -->|"streams events"| node_webapp
node_operator -->|"uses console"| node_webapp
node_webapp -->|"calls local API"| node_api
node_webapp -->|"renders tasks"| node_tasks_ui
node_webapp -->|"renders profiles"| node_agents_ui
node_agents_ui -->|"manages profiles"| node_api
node_tasks_ui -->|"loads task detail"| node_api
node_chatgpt -.->|"initiates browser work"| node_extension

click node_mcp_http "https://github.com/int04/chatcmd/blob/main/crates/chatcmd-mcp/src/http_transport.rs"
click node_mcp_server "https://github.com/int04/chatcmd/blob/main/crates/chatcmd-mcp/src/mcp_server.rs"
click node_api "https://github.com/int04/chatcmd/blob/main/src/api/routes.rs"
click node_ws "https://github.com/int04/chatcmd/blob/main/src/websocket/mod.rs"
click node_host "https://github.com/int04/chatcmd/blob/main/src/runtime_host.rs"
click node_dispatch "https://github.com/int04/chatcmd/blob/main/src/runtime_host/dispatch.rs"
click node_approval "https://github.com/int04/chatcmd/blob/main/src/runtime_host/approval.rs"
click node_subagents "https://github.com/int04/chatcmd/blob/main/src/runtime_host/subagents.rs"
click node_machine_tools "https://github.com/int04/chatcmd/blob/main/crates/chatcmd-runtime/src/services.rs"
click node_shell "https://github.com/int04/chatcmd/blob/main/crates/chatcmd-runtime/src/shell.rs"
click node_skills "https://github.com/int04/chatcmd/blob/main/crates/chatcmd-runtime/src/skill_service.rs"
click node_chatgpt_bridge "https://github.com/int04/chatcmd/blob/main/src/api/chatgpt.rs"
click node_extension "https://github.com/int04/chatcmd/blob/main/chatgpt-extension/background.js"
click node_repository "https://github.com/int04/chatcmd/blob/main/crates/chatcmd-storage/src/repository.rs"
click node_compact "https://github.com/int04/chatcmd/blob/main/crates/chatcmd-storage/src/compact/mod.rs"
click node_webapp "https://github.com/int04/chatcmd/blob/main/web/src/App.tsx"
click node_tasks_ui "https://github.com/int04/chatcmd/blob/main/web/src/pages/TasksPage.tsx"
click node_agents_ui "https://github.com/int04/chatcmd/blob/main/web/src/pages/AgentsPage.tsx"

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_mcp_http,node_mcp_server,node_api,node_ws,node_mcp_client,node_chatgpt toneBlue
class node_host,node_dispatch,node_approval,node_subagents toneAmber
class node_machine_tools,node_shell,node_skills,node_chatgpt_bridge,node_extension toneMint
class node_repository,node_compact toneRose
class node_webapp,node_tasks_ui,node_agents_ui,node_operator toneIndigo
```

## Components

### Entry points

- [MCP HTTP](https://github.com/int04/chatcmd/blob/main/crates/chatcmd-mcp/src/http_transport.rs): `crates/chatcmd-mcp/src/http_transport.rs`
- [MCP server](https://github.com/int04/chatcmd/blob/main/crates/chatcmd-mcp/src/mcp_server.rs): `crates/chatcmd-mcp/src/mcp_server.rs`
- [Local API](https://github.com/int04/chatcmd/blob/main/src/api/routes.rs): `src/api/routes.rs`
- [Live events](https://github.com/int04/chatcmd/blob/main/src/websocket/mod.rs): `src/websocket/mod.rs`

### Control plane

- [Runtime host](https://github.com/int04/chatcmd/blob/main/src/runtime_host.rs): `src/runtime_host.rs`
- [Tool dispatch](https://github.com/int04/chatcmd/blob/main/src/runtime_host/dispatch.rs): `src/runtime_host/dispatch.rs`
- [Authorization](https://github.com/int04/chatcmd/blob/main/src/runtime_host/approval.rs): `src/runtime_host/approval.rs`
- [Sub-agent lifecycle](https://github.com/int04/chatcmd/blob/main/src/runtime_host/subagents.rs): `src/runtime_host/subagents.rs`

### Local execution

- [Machine tools](https://github.com/int04/chatcmd/blob/main/crates/chatcmd-runtime/src/services.rs): `crates/chatcmd-runtime/src/services.rs`
- [PTY terminals](https://github.com/int04/chatcmd/blob/main/crates/chatcmd-runtime/src/shell.rs): `crates/chatcmd-runtime/src/shell.rs`
- [Skill discovery](https://github.com/int04/chatcmd/blob/main/crates/chatcmd-runtime/src/skill_service.rs): `crates/chatcmd-runtime/src/skill_service.rs`
- [ChatGPT bridge](https://github.com/int04/chatcmd/blob/main/src/api/chatgpt.rs): `src/api/chatgpt.rs`
- [Browser extension](https://github.com/int04/chatcmd/blob/main/chatgpt-extension/background.js): `chatgpt-extension/background.js`

### Persistence

- [SQLite repository](https://github.com/int04/chatcmd/blob/main/crates/chatcmd-storage/src/repository.rs): `crates/chatcmd-storage/src/repository.rs`
- [Compact sessions](https://github.com/int04/chatcmd/blob/main/crates/chatcmd-storage/src/compact/mod.rs): `crates/chatcmd-storage/src/compact/mod.rs`

### User interfaces

- [Management console](https://github.com/int04/chatcmd/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Task supervision](https://github.com/int04/chatcmd/blob/main/web/src/pages/TasksPage.tsx): `web/src/pages/TasksPage.tsx`
- [Access profiles](https://github.com/int04/chatcmd/blob/main/web/src/pages/AgentsPage.tsx): `web/src/pages/AgentsPage.tsx`

### Other components

- **MCP client**
- **Local operator**
- **ChatGPT browser**

## Connections

- MCP client → MCP HTTP: sends MCP requests
- MCP HTTP → MCP server: forwards requests
- MCP server → Runtime host: invokes runtime
- Runtime host → Tool dispatch: dispatches tools
- Tool dispatch → Authorization: checks permission
- Tool dispatch → Machine tools: invokes tools
- Tool dispatch → PTY terminals: controls terminals
- Tool dispatch → Skill discovery: discovers skills
- Runtime host → Sub-agent lifecycle: coordinates agents
- Runtime host → SQLite repository: persists state
- Local API → SQLite repository: reads and writes
- Local API → ChatGPT bridge: handles bridge routes
- ChatGPT bridge → Browser extension: exchanges requests
- Browser extension → ChatGPT browser: drives conversations
- Local API → Compact sessions: manages compact jobs
- Compact sessions → SQLite repository: stores checkpoints
- Runtime host → Live events: publishes activity
- Live events → Management console: streams events
- Local operator → Management console: uses console
- Management console → Local API: calls local API
- Management console → Task supervision: renders tasks
- Management console → Access profiles: renders profiles
- Access profiles → Local API: manages profiles
- Task supervision → Local API: loads task detail
- ChatGPT browser → Browser extension: initiates browser work