# zj970/opencode architecture

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

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

## Overview

OpenCode is an open-source AI coding agent, exposed through web/desktop, terminal, and CLI interfaces. The core workflow is choosing or opening a project session, composing a request, and having an agent work with project context and tools under permission constraints; users then inspect the session and its results. The README documents build and read-only plan agents plus a general subagent. The sampled server routes establish session-execution and service wiring, but the excerpts do not show the agent/tool dispatch path, so uncertain runtime links are omitted.

Main entry points: [`packages/server/src/routes.ts`](https://github.com/zj970/opencode/blob/dev/packages/server/src/routes.ts) (Session Execution), [`packages/app/src/pages/home/home-sessions-controller.tsx`](https://github.com/zj970/opencode/blob/dev/packages/app/src/pages/home/home-sessions-controller.tsx) (Session Browser), [`packages/app/src/context/server-sync.tsx`](https://github.com/zj970/opencode/blob/dev/packages/app/src/context/server-sync.tsx) (Session Sync), [`packages/app/src/app.tsx`](https://github.com/zj970/opencode/blob/dev/packages/app/src/app.tsx) (Web App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_webapp["Web App<br/>[app.tsx]"]
  node_tui["Terminal UI<br/>[app.tsx]"]
  node_cli["CLI<br/>[index.ts]"]
  node_desktopupdater["Desktop Updater"]
end

subgraph group_session["Session Workflow"]
  node_home["Session Browser"]
  node_composer["Request Composer<br/>[index.ts]"]
  node_timeline["Session Timeline"]
end

subgraph group_runtime["Agent Runtime"]
  node_routes["Server API<br/>[routes.ts]"]
  node_sessionexec["Session Execution<br/>[routes.ts]"]
  node_agents["Agent Modes"]
  node_tools["Agent Tools"]
  node_lsp["Language Servers<br/>[server.ts]"]
  node_permissions["Permissions<br/>[permission.tsx]"]
end

subgraph group_state["State And Integrations"]
  node_projectfiles["Project Files<br/>[file.tsx]"]
  node_providers["Model Providers<br/>[providers.tsx]"]
  node_sync["Session Sync<br/>[server-sync.tsx]"]
  node_localstorage[("Local Storage<br/>[storage.ts]")]
  node_cloudstorage[("Object Storage<br/>[storage.ts]")]
end

node_user(("Developer"))

node_user -->|"uses"| node_webapp
node_user -->|"uses"| node_tui
node_user -->|"uses"| node_cli
node_webapp -->|"opens sessions"| node_home
node_home -->|"loads session index"| node_sync
node_home -->|"starts session"| node_composer
node_composer -->|"submits request"| node_routes
node_tui -->|"connects through SDK"| node_routes
node_cli -.->|"serves API"| node_routes
node_routes -->|"provides service"| node_sessionexec
node_sessionexec -.->|"executes agent"| node_agents
node_agents -.->|"invokes tools"| node_tools
node_sessionexec -.->|"checks policy"| node_permissions
node_sessionexec -.->|"requests inference"| node_providers
node_sessionexec -.->|"uses project context"| node_projectfiles
node_sessionexec -.->|"uses language services"| node_lsp
node_routes -.->|"provides session data"| node_sync
node_sync -.->|"updates view"| node_timeline
node_sessionexec -.->|"persists state"| node_localstorage
node_user -->|"initiates update"| node_desktopupdater
node_cloudstorage -.-> node_user

click node_webapp "https://github.com/zj970/opencode/blob/dev/packages/app/src/app.tsx"
click node_tui "https://github.com/zj970/opencode/blob/dev/packages/tui/src/app.tsx"
click node_cli "https://github.com/zj970/opencode/blob/dev/packages/cli/src/index.ts"
click node_routes "https://github.com/zj970/opencode/blob/dev/packages/server/src/routes.ts"
click node_home "https://github.com/zj970/opencode/blob/dev/packages/app/src/pages/home/home-sessions-controller.tsx"
click node_composer "https://github.com/zj970/opencode/blob/dev/packages/app/src/pages/session/composer/index.ts"
click node_timeline "https://github.com/zj970/opencode/blob/dev/packages/app/src/pages/session/timeline/message-timeline.tsx"
click node_sessionexec "https://github.com/zj970/opencode/blob/dev/packages/server/src/routes.ts"
click node_lsp "https://github.com/zj970/opencode/blob/dev/packages/opencode/src/lsp/server.ts"
click node_permissions "https://github.com/zj970/opencode/blob/dev/packages/app/src/context/permission.tsx"
click node_projectfiles "https://github.com/zj970/opencode/blob/dev/packages/app/src/context/file.tsx"
click node_providers "https://github.com/zj970/opencode/blob/dev/packages/app/src/components/settings-v2/providers.tsx"
click node_sync "https://github.com/zj970/opencode/blob/dev/packages/app/src/context/server-sync.tsx"
click node_localstorage "https://github.com/zj970/opencode/blob/dev/packages/opencode/src/storage/storage.ts"
click node_cloudstorage "https://github.com/zj970/opencode/blob/dev/packages/enterprise/src/core/storage.ts"
click node_desktopupdater "https://github.com/zj970/opencode/blob/dev/packages/desktop/src/main/updater-controller.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_webapp,node_tui,node_cli,node_desktopupdater toneBlue
class node_home,node_composer,node_timeline toneAmber
class node_routes,node_sessionexec,node_agents,node_tools,node_lsp,node_permissions toneMint
class node_projectfiles,node_providers,node_sync,node_localstorage,node_cloudstorage toneRose
class node_user toneIndigo
```

## Components

### User Interfaces

- [Web App](https://github.com/zj970/opencode/blob/dev/packages/app/src/app.tsx): `packages/app/src/app.tsx`
- [Terminal UI](https://github.com/zj970/opencode/blob/dev/packages/tui/src/app.tsx): `packages/tui/src/app.tsx`
- [CLI](https://github.com/zj970/opencode/blob/dev/packages/cli/src/index.ts): `packages/cli/src/index.ts`
- [Desktop Updater](https://github.com/zj970/opencode/blob/dev/packages/desktop/src/main/updater-controller.ts): `packages/desktop/src/main/updater-controller.ts`

### Session Workflow

- [Session Browser](https://github.com/zj970/opencode/blob/dev/packages/app/src/pages/home/home-sessions-controller.tsx): `packages/app/src/pages/home/home-sessions-controller.tsx`
- [Request Composer](https://github.com/zj970/opencode/blob/dev/packages/app/src/pages/session/composer/index.ts): `packages/app/src/pages/session/composer/index.ts`
- [Session Timeline](https://github.com/zj970/opencode/blob/dev/packages/app/src/pages/session/timeline/message-timeline.tsx): `packages/app/src/pages/session/timeline/message-timeline.tsx`

### Agent Runtime

- [Server API](https://github.com/zj970/opencode/blob/dev/packages/server/src/routes.ts): `packages/server/src/routes.ts`
- [Session Execution](https://github.com/zj970/opencode/blob/dev/packages/server/src/routes.ts): `packages/server/src/routes.ts`
- **Agent Modes**
- **Agent Tools**
- [Language Servers](https://github.com/zj970/opencode/blob/dev/packages/opencode/src/lsp/server.ts): `packages/opencode/src/lsp/server.ts`
- [Permissions](https://github.com/zj970/opencode/blob/dev/packages/app/src/context/permission.tsx): `packages/app/src/context/permission.tsx`

### State And Integrations

- [Project Files](https://github.com/zj970/opencode/blob/dev/packages/app/src/context/file.tsx): `packages/app/src/context/file.tsx`
- [Model Providers](https://github.com/zj970/opencode/blob/dev/packages/app/src/components/settings-v2/providers.tsx): `packages/app/src/components/settings-v2/providers.tsx`
- [Session Sync](https://github.com/zj970/opencode/blob/dev/packages/app/src/context/server-sync.tsx): `packages/app/src/context/server-sync.tsx`
- [Local Storage](https://github.com/zj970/opencode/blob/dev/packages/opencode/src/storage/storage.ts): `packages/opencode/src/storage/storage.ts`
- [Object Storage](https://github.com/zj970/opencode/blob/dev/packages/enterprise/src/core/storage.ts): `packages/enterprise/src/core/storage.ts`

### Other components

- **Developer**

## Connections

- Developer → Web App: uses
- Developer → Terminal UI: uses
- Developer → CLI: uses
- Web App → Session Browser: opens sessions
- Session Browser → Session Sync: loads session index
- Session Browser → Request Composer: starts session
- Request Composer → Server API: submits request
- Terminal UI → Server API: connects through SDK
- CLI → Server API: serves API
- Server API → Session Execution: provides service
- Session Execution → Agent Modes: executes agent
- Agent Modes → Agent Tools: invokes tools
- Session Execution → Permissions: checks policy
- Session Execution → Model Providers: requests inference
- Session Execution → Project Files: uses project context
- Session Execution → Language Servers: uses language services
- Server API → Session Sync: provides session data
- Session Sync → Session Timeline: updates view
- Session Execution → Local Storage: persists state
- Developer → Desktop Updater: initiates update
- Object Storage → Developer