# hunters-sec/opencode architecture

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

- Interactive diagram: https://gitdiagram.com/hunters-sec/opencode
- Repository: https://github.com/hunters-sec/opencode

## Overview

OpenWorm is an AI coding agent with terminal, web, and desktop clients backed by an OpenCode server. The main workflow is selecting a provider/model, creating or continuing a coding session, and using the agent’s tools to work with a project. The README also documents read-only planning, multi-provider support, and WormGPT models. Edges below are limited to relationships shown in the excerpts or README; several listed subsystems were not sampled, so their internal wiring is omitted.

Main entry points: [`packages/opencode/src/server/server.ts`](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/server/server.ts) (HTTP server), [`packages/opencode/src/cli/cmd/tui/app.tsx`](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx) (Terminal UI), [`packages/console/app/src/routes/zen/util/handler.ts`](https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/handler.ts) (Hosted model gateway), [`packages/opencode/src/project/instance.ts`](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/project/instance.ts) (Project context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_tui["Terminal UI<br/>[app.tsx]"]
  node_web["Web app<br/>[app.tsx]"]
  node_sdk["Web SDK adapter<br/>[server.ts]"]
  node_desktop["Desktop client<br/>[entry.tsx]"]
  node_review["Session review UI<br/>[session-review.tsx]"]
  node_reviewtab["Review tab<br/>[review-tab.tsx]"]
end

subgraph group_runtime["Agent runtime"]
  node_server["HTTP server<br/>[server.ts]"]
  node_sessions["Session routes<br/>[session.ts]"]
  node_agent["Agent engine<br/>[agent.ts]"]
  node_prompt["Prompt history<br/>[history.tsx]"]
  node_flags["Runtime flags<br/>[flag.ts]"]
end

subgraph group_project["Project services"]
  node_project["Project context<br/>[instance.ts]"]
  node_project_model["Project model<br/>[project.ts]"]
  node_storage[("Local storage<br/>[storage.ts]")]
  node_filesystem["Filesystem tools<br/>[filesystem.ts]"]
  node_glob["File matching<br/>[glob.ts]"]
  node_log["Runtime logging<br/>[log.ts]"]
end

subgraph group_providers["Model access"]
  node_provider["Provider registry<br/>[provider.ts]"]
  node_zen["Hosted model gateway<br/>[handler.ts]"]
  node_anthropic["Anthropic adapter<br/>[anthropic.ts]"]
  node_openai["OpenAI adapter<br/>[openai.ts]"]
  node_compatible["Compatible adapter"]
end

node_user(("Developer"))

node_user -->|"uses"| node_tui
node_user -->|"uses"| node_web
node_user -->|"uses"| node_desktop
node_tui -.->|"calls API"| node_server
node_web -.->|"configures client"| node_sdk
node_sdk -.->|"calls API"| node_server
node_desktop -.->|"uses backend"| node_server
node_server -->|"routes requests"| node_sessions
node_server -->|"uses providers"| node_provider
node_server -->|"uses agents"| node_agent
node_tui -->|"renders"| node_prompt
node_tui -.->|"selects models"| node_provider
node_server -->|"uses context"| node_project
node_project -->|"uses state"| node_project_model
node_project -.->|"persists data"| node_storage
node_storage -->|"reads and writes"| node_filesystem
node_filesystem -->|"uses matching"| node_glob
node_server -->|"logs activity"| node_log
node_reviewtab -.->|"renders"| node_review
node_user -.->|"requests hosted models"| node_zen
node_zen -->|"dispatches"| node_anthropic
node_zen -->|"dispatches"| node_openai
node_zen -->|"dispatches"| node_compatible

click node_tui "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx"
click node_web "https://github.com/hunters-sec/opencode/blob/main/packages/app/src/app.tsx"
click node_sdk "https://github.com/hunters-sec/opencode/blob/main/packages/app/src/utils/server.ts"
click node_desktop "https://github.com/hunters-sec/opencode/blob/main/packages/desktop/src/entry.tsx"
click node_server "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/server/server.ts"
click node_sessions "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/server/routes/session.ts"
click node_agent "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/agent/agent.ts"
click node_prompt "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/cli/cmd/tui/component/prompt/history.tsx"
click node_flags "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/flag/flag.ts"
click node_provider "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/provider/provider.ts"
click node_zen "https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/handler.ts"
click node_anthropic "https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/provider/anthropic.ts"
click node_openai "https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/provider/openai.ts"
click node_compatible "https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/provider/openai-compatible.ts"
click node_project "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/project/instance.ts"
click node_project_model "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/project/project.ts"
click node_storage "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/storage/storage.ts"
click node_filesystem "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/util/filesystem.ts"
click node_glob "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/util/glob.ts"
click node_log "https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/util/log.ts"
click node_review "https://github.com/hunters-sec/opencode/blob/main/packages/ui/src/components/session-review.tsx"
click node_reviewtab "https://github.com/hunters-sec/opencode/blob/main/packages/app/src/pages/session/review-tab.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_tui,node_web,node_sdk,node_desktop,node_review,node_reviewtab toneBlue
class node_server,node_sessions,node_agent,node_prompt,node_flags toneAmber
class node_project,node_project_model,node_storage,node_filesystem,node_glob,node_log toneMint
class node_provider,node_zen,node_anthropic,node_openai,node_compatible toneRose
class node_user toneIndigo
```

## Components

### User clients

- [Terminal UI](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx): `packages/opencode/src/cli/cmd/tui/app.tsx`
- [Web app](https://github.com/hunters-sec/opencode/blob/main/packages/app/src/app.tsx): `packages/app/src/app.tsx`
- [Web SDK adapter](https://github.com/hunters-sec/opencode/blob/main/packages/app/src/utils/server.ts): `packages/app/src/utils/server.ts`
- [Desktop client](https://github.com/hunters-sec/opencode/blob/main/packages/desktop/src/entry.tsx): `packages/desktop/src/entry.tsx`
- [Session review UI](https://github.com/hunters-sec/opencode/blob/main/packages/ui/src/components/session-review.tsx): `packages/ui/src/components/session-review.tsx`
- [Review tab](https://github.com/hunters-sec/opencode/blob/main/packages/app/src/pages/session/review-tab.tsx): `packages/app/src/pages/session/review-tab.tsx`

### Agent runtime

- [HTTP server](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/server/server.ts): `packages/opencode/src/server/server.ts`
- [Session routes](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/server/routes/session.ts): `packages/opencode/src/server/routes/session.ts`
- [Agent engine](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/agent/agent.ts): `packages/opencode/src/agent/agent.ts`
- [Prompt history](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/cli/cmd/tui/component/prompt/history.tsx): `packages/opencode/src/cli/cmd/tui/component/prompt/history.tsx`
- [Runtime flags](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/flag/flag.ts): `packages/opencode/src/flag/flag.ts`

### Project services

- [Project context](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/project/instance.ts): `packages/opencode/src/project/instance.ts`
- [Project model](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/project/project.ts): `packages/opencode/src/project/project.ts`
- [Local storage](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/storage/storage.ts): `packages/opencode/src/storage/storage.ts`
- [Filesystem tools](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/util/filesystem.ts): `packages/opencode/src/util/filesystem.ts`
- [File matching](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/util/glob.ts): `packages/opencode/src/util/glob.ts`
- [Runtime logging](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/util/log.ts): `packages/opencode/src/util/log.ts`

### Model access

- [Provider registry](https://github.com/hunters-sec/opencode/blob/main/packages/opencode/src/provider/provider.ts): `packages/opencode/src/provider/provider.ts`
- [Hosted model gateway](https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/handler.ts): `packages/console/app/src/routes/zen/util/handler.ts`
- [Anthropic adapter](https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/provider/anthropic.ts): `packages/console/app/src/routes/zen/util/provider/anthropic.ts`
- [OpenAI adapter](https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/provider/openai.ts): `packages/console/app/src/routes/zen/util/provider/openai.ts`
- [Compatible adapter](https://github.com/hunters-sec/opencode/blob/main/packages/console/app/src/routes/zen/util/provider/openai-compatible.ts): `packages/console/app/src/routes/zen/util/provider/openai-compatible.ts`

### Other components

- **Developer**

## Connections

- Developer → Terminal UI: uses (evidence: `README.md`)
- Developer → Web app: uses (evidence: `README.md`)
- Developer → Desktop client: uses (evidence: `README.md`)
- Terminal UI → HTTP server: calls API
- Web app → Web SDK adapter: configures client
- Web SDK adapter → HTTP server: calls API
- Desktop client → HTTP server: uses backend (evidence: `README.md`)
- HTTP server → Session routes: routes requests (evidence: `packages/opencode/src/server/server.ts`)
- HTTP server → Provider registry: uses providers (evidence: `packages/opencode/src/server/server.ts`)
- HTTP server → Agent engine: uses agents (evidence: `packages/opencode/src/server/server.ts`)
- Terminal UI → Prompt history: renders (evidence: `packages/opencode/src/cli/cmd/tui/app.tsx`)
- Terminal UI → Provider registry: selects models (evidence: `README.md`)
- HTTP server → Project context: uses context (evidence: `packages/opencode/src/server/server.ts`)
- Project context → Project model: uses state (evidence: `packages/opencode/src/project/instance.ts`)
- Project context → Local storage: persists data
- Local storage → Filesystem tools: reads and writes (evidence: `packages/opencode/src/storage/storage.ts`)
- Filesystem tools → File matching: uses matching (evidence: `packages/opencode/src/util/filesystem.ts`)
- HTTP server → Runtime logging: logs activity (evidence: `packages/opencode/src/server/server.ts`)
- Review tab → Session review UI: renders
- Developer → Hosted model gateway: requests hosted models (evidence: `README.md`)
- Hosted model gateway → Anthropic adapter: dispatches (evidence: `packages/console/app/src/routes/zen/util/handler.ts`)
- Hosted model gateway → OpenAI adapter: dispatches (evidence: `packages/console/app/src/routes/zen/util/handler.ts`)
- Hosted model gateway → Compatible adapter: dispatches (evidence: `packages/console/app/src/routes/zen/util/handler.ts`)
