# nishal77/opencode architecture

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

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

## Overview

1. This is a Bun/TypeScript monorepo for OpenCode: a local AI coding agent with multiple user surfaces, shared domain libraries, a typed HTTP API, and separate cloud services for auth, billing, sharing, and analytics. The main architectural center is the agent runtime plus its session/tool/provider model.

2. `packages/core` is the domain kernel. It owns the canonical definitions for sessions, tools, prompts, permissions, providers/models, filesystem/git/project behavior, config parsing, database schemas/migrations, and effect-based runtime primitives. Most other packages depend on this layer rather than duplicating business logic.

3. `packages/opencode` is the main product/runtime assembly. It combines CLI commands, the interactive TUI, session processing, LLM orchestration, plugin loading, workspace/bootstrap logic, sync, storage, and the local HTTP API server into the end-user executable.

4. `packages/llm` is the provider/protocol adapter layer. It normalizes differences between OpenAI, Anthropic, Gemini, Bedrock, Cloudflare, OpenRouter, xAI, GitHub Copilot, and other providers, including streaming and tool-call behavior, into one internal model that OpenCode can consume consistently.

5. The user-facing surfaces are split by interaction mode: `packages/tui` for terminal UX, `packages/desktop` for the Electron app, `packages/app` for the larger SolidJS app, and `packages/ui` as the shared component/theme library. These clients mostly render state and send actions into the local runtime/API boundary.

6. The core data flow is: user prompt/input → session processor/runner → model provider request → tool execution → persisted events/messages → UI projections. Tool results can mutate files, run shell commands, query LSP/MCP integrations, or emit structured outputs, and those changes are reflected back through session views, timelines, and sync streams.

7. `packages/server` is a typed HTTP boundary over the domain model. Its route groups are organized by feature area—agent, session, filesystem, model, provider, pty, permission, question, reference, project-copy, integration, and health—with middleware for authorization, schema validation, and session/location scoping.

8. Plugins and integrations are intentionally isolated. `packages/plugin` exposes the v2 effect-based plugin API, while OpenCode’s own runtime has plugin loaders, host adapters, and workspace adapters. MCP servers, IDE/LSP support, Git integration, and provider-specific extensions are all treated as pluggable capabilities at the edges.

9. Persistence is split between local embedded state and service-side databases. Core/opencode carry Drizzle-backed schemas and migrations for sessions, workspaces, credentials, events, and permissions; the console/stats services have their own databases and ingestion paths for usage and analytics. Long-lived state is therefore shared by schema, but separated by deployment target.

10. The cloud/control-plane side lives mainly in `packages/console`, `packages/enterprise`, and `packages/stats`. Console handles auth, billing, model proxying/rate limiting, and usage batching; enterprise hosts share views and APIs; stats ingests telemetry and serves analytics. The `infra/` modules wire these services into SST-managed deployments.

11. `packages/web` is the documentation and marketing site, built with Astro/Starlight and multilingual content. `packages/sdk/js` is the generated OpenAPI-based client/server SDK that external consumers and internal tools use to talk to the same APIs as the built-in apps.

12. Cross-cutting tooling is substantial: Storybook supports the UI library, Playwright and recorded integration tests cover the app surfaces, Electron Builder packages desktop, and GitHub Actions plus release scripts drive publishing. These tools reinforce the same package graph rather than introducing separate architectural tiers.

Main entry points: [`packages/opencode`](https://github.com/nishal77/opencode/tree/dev/packages/opencode) (opencode), [`packages/server`](https://github.com/nishal77/opencode/tree/dev/packages/server) (server), [`packages/core`](https://github.com/nishal77/opencode/tree/dev/packages/core) (core), [`packages/ui`](https://github.com/nishal77/opencode/tree/dev/packages/ui) (ui)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Shared Core"]
  node_packages_core["core<br/>domain kernel"]
  node_packages_llm["llm<br/>provider adapters"]
  node_packages_plugin["plugin"]
  node_packages_effect_drizzle_sqlite["effect-sqlite<br/>sqlite runtime"]
end

subgraph group_group_local["Local Runtime"]
  node_packages_opencode["opencode<br/>local runtime"]
  node_packages_server["server<br/>typed HTTP API"]
  node_packages_cli["cli<br/>command shell"]
end

subgraph group_group_surfaces["User Surfaces"]
  node_packages_tui["tui<br/>terminal UI"]
  node_packages_desktop["desktop<br/>electron shell"]
  node_packages_app["app"]
  node_packages_ui["ui<br/>component system"]
  node_packages_web["web<br/>docs site"]
end

subgraph group_group_cloud["Cloud Services"]
  node_packages_console_app["console app<br/>control plane web"]
  node_packages_console_core["console core<br/>business data"]
  node_packages_console_function["console fn<br/>serverless jobs"]
  node_packages_stats_core["stats core<br/>analytics domain"]
  node_packages_stats_server["stats server<br/>ingest api"]
  node_infra["infra<br/>deployment wiring"]
end

subgraph group_group_tooling["Tooling & SDKs"]
  node_packages_sdk_js["sdk js<br/>generated client"]
  node_script["script<br/>repo automation"]
end

node_packages_llm -->|"provider model"| node_packages_core
node_packages_plugin -->|"plugin contracts"| node_packages_core
node_packages_effect_drizzle_sqlite -->|"persistence runtime"| node_packages_core
node_packages_opencode -->|"domain kernel"| node_packages_core
node_packages_opencode -->|"model execution"| node_packages_llm
node_packages_opencode -->|"plugin host"| node_packages_plugin
node_packages_opencode -->|"local api"| node_packages_server
node_packages_opencode -->|"terminal surface"| node_packages_tui
node_packages_opencode -->|"entrypoints"| node_packages_cli
node_packages_opencode -->|"shared ui"| node_packages_ui
node_packages_server -->|"typed boundary"| node_packages_core
node_packages_server -->|"provider routes"| node_packages_llm
node_packages_tui -->|"rendering"| node_packages_ui
node_packages_app -->|"components"| node_packages_ui
node_packages_app -->|"api client"| node_packages_server
node_packages_desktop -->|"embedded runtime"| node_packages_opencode
node_packages_desktop -->|"renderer"| node_packages_app
node_packages_web -->|"brand system"| node_packages_ui
node_packages_console_app -->|"control plane"| node_packages_console_core
node_packages_console_function -->|"background jobs"| node_packages_console_core
node_packages_stats_core -.->|"analytics domain"| node_packages_console_core
node_packages_stats_server -->|"ingestion"| node_packages_stats_core
node_infra -->|"deploy"| node_packages_console_app
node_infra -->|"deploy"| node_packages_stats_server
node_packages_sdk_js -->|"openapi client"| node_packages_server
node_script -->|"publish"| node_packages_opencode
node_script -->|"release"| node_packages_sdk_js

click node_packages_core "https://github.com/nishal77/opencode/tree/dev/packages/core"
click node_packages_llm "https://github.com/nishal77/opencode/tree/dev/packages/llm"
click node_packages_plugin "https://github.com/nishal77/opencode/tree/dev/packages/plugin"
click node_packages_effect_drizzle_sqlite "https://github.com/nishal77/opencode/tree/dev/packages/effect-drizzle-sqlite"
click node_packages_opencode "https://github.com/nishal77/opencode/tree/dev/packages/opencode"
click node_packages_server "https://github.com/nishal77/opencode/tree/dev/packages/server"
click node_packages_cli "https://github.com/nishal77/opencode/tree/dev/packages/cli"
click node_packages_tui "https://github.com/nishal77/opencode/tree/dev/packages/tui"
click node_packages_desktop "https://github.com/nishal77/opencode/tree/dev/packages/desktop"
click node_packages_app "https://github.com/nishal77/opencode/tree/dev/packages/app"
click node_packages_ui "https://github.com/nishal77/opencode/tree/dev/packages/ui"
click node_packages_web "https://github.com/nishal77/opencode/tree/dev/packages/web"
click node_packages_console_app "https://github.com/nishal77/opencode/tree/dev/packages/console/app"
click node_packages_console_core "https://github.com/nishal77/opencode/tree/dev/packages/console/core"
click node_packages_console_function "https://github.com/nishal77/opencode/tree/dev/packages/console/function"
click node_packages_stats_core "https://github.com/nishal77/opencode/tree/dev/packages/stats/core"
click node_packages_stats_server "https://github.com/nishal77/opencode/tree/dev/packages/stats/server"
click node_infra "https://github.com/nishal77/opencode/tree/dev/infra"
click node_packages_sdk_js "https://github.com/nishal77/opencode/tree/dev/packages/sdk/js"
click node_script "https://github.com/nishal77/opencode/tree/dev/script"

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_packages_core,node_packages_llm,node_packages_plugin,node_packages_effect_drizzle_sqlite toneBlue
class node_packages_opencode,node_packages_server,node_packages_cli toneAmber
class node_packages_tui,node_packages_desktop,node_packages_app,node_packages_ui,node_packages_web toneMint
class node_packages_console_app,node_packages_console_core,node_packages_console_function,node_packages_stats_core,node_packages_stats_server,node_infra toneRose
class node_packages_sdk_js,node_script toneIndigo
```

## Components

### Shared Core

Canonical domain, session, tool, plugin, and model abstractions used across runtimes and services.

- [core](https://github.com/nishal77/opencode/tree/dev/packages/core): domain kernel · Canonical session/tool/provider/config/persistence model and effect runtime primitives. · `packages/core`
- [llm](https://github.com/nishal77/opencode/tree/dev/packages/llm): provider adapters · Normalizes provider protocols, streaming, and tool-call behavior into one internal model. · `packages/llm`
- [plugin](https://github.com/nishal77/opencode/tree/dev/packages/plugin): v2 plugin API · Effect-based plugin surface for agents, commands, providers, skills, and host integration. · `packages/plugin`
- [effect-sqlite](https://github.com/nishal77/opencode/tree/dev/packages/effect-drizzle-sqlite): sqlite runtime · Effect-compatible SQLite driver and migrator utilities used by storage layers. · `packages/effect-drizzle-sqlite`

### Local Runtime

The end-user executable assembly: CLI, agent runtime, local server, plugin host, persistence, and workspace control.

- [opencode](https://github.com/nishal77/opencode/tree/dev/packages/opencode): local runtime · Main executable assembly combining CLI, TUI, session processing, plugin loading, sync, and local HTTP API. · `packages/opencode`
- [server](https://github.com/nishal77/opencode/tree/dev/packages/server): typed HTTP API · Standalone typed HTTP boundary exposing agent, session, filesystem, provider, and related routes. · `packages/server`
- [cli](https://github.com/nishal77/opencode/tree/dev/packages/cli): command shell · Thin command framework for service control, daemon boot, and runtime entrypoints. · `packages/cli`

### User Surfaces

Terminal, desktop, web app, docs site, and shared UI packages that present the runtime state.

- [tui](https://github.com/nishal77/opencode/tree/dev/packages/tui): terminal UI · Interactive terminal surface for sessions, prompts, permissions, plugins, and workspace workflows. · `packages/tui`
- [desktop](https://github.com/nishal77/opencode/tree/dev/packages/desktop): electron shell · Desktop renderer/main process integration around the shared runtime and web UI. · `packages/desktop`
- [app](https://github.com/nishal77/opencode/tree/dev/packages/app): solid app · Web app surface for sessions, settings, timelines, and workspace management. · `packages/app`
- [ui](https://github.com/nishal77/opencode/tree/dev/packages/ui): component system · Shared design system, themes, icons, and cross-surface UI primitives. · `packages/ui`
- [web](https://github.com/nishal77/opencode/tree/dev/packages/web): docs site · Astro/Starlight documentation and marketing site with multilingual content. · `packages/web`

### Cloud Services

Auth, billing, sharing, analytics, and deployment wiring for the control plane and hosted services.

- [console app](https://github.com/nishal77/opencode/tree/dev/packages/console/app): control plane web · Hosted console for auth, billing, provider management, usage, and enterprise workflows. · `packages/console/app`
- [console core](https://github.com/nishal77/opencode/tree/dev/packages/console/core): business data · Shared control-plane domain models, schemas, and billing/provider/account logic. · `packages/console/core`
- [console fn](https://github.com/nishal77/opencode/tree/dev/packages/console/function): serverless jobs · Background functions for auth and log/stat processing. · `packages/console/function`
- [stats core](https://github.com/nishal77/opencode/tree/dev/packages/stats/core): analytics domain · Stats/telemetry domain, normalization, runtime, and ingestion helpers. · `packages/stats/core`
- [stats server](https://github.com/nishal77/opencode/tree/dev/packages/stats/server): ingest api · Analytics ingestion and sync server. · `packages/stats/server`
- [infra](https://github.com/nishal77/opencode/tree/dev/infra): deployment wiring · SST app definitions for local, console, enterprise, lake, monitoring, secrets, and stats deployments. · `infra`

### Tooling & SDKs

Publishing, generated clients, and developer tooling around the monorepo.

- [sdk js](https://github.com/nishal77/opencode/tree/dev/packages/sdk/js): generated client · OpenAPI-based JavaScript SDK and server/client wrappers for external and internal consumers. · `packages/sdk/js`
- [script](https://github.com/nishal77/opencode/tree/dev/script): repo automation · Release, publish, changelog, stats, and maintenance scripts for the monorepo. · `script`

## Connections

- llm → core: provider model · LLM adapters consume the canonical model and tool/session contracts from core.
- plugin → core: plugin contracts · The plugin API is built on core abstractions for agents, commands, providers, and skills.
- effect-sqlite → core: persistence runtime · SQLite drivers and migrations support the core database and effect layers.
- opencode → core: domain kernel · The main runtime assembles session, tool, config, and persistence logic from core.
- opencode → llm: model execution · OpenCode uses provider adapters to execute model requests and streaming responses.
- opencode → plugin: plugin host · The local runtime loads and runs plugins through the shared plugin API.
- opencode → server: local api · The executable embeds a typed HTTP boundary for clients and integration surfaces.
- opencode → tui: terminal surface · The runtime powers the interactive terminal experience.
- opencode → cli: entrypoints · CLI commands bootstrap and control the opencode runtime and daemon.
- opencode → ui: shared ui · The runtime and TUI reuse shared UI primitives and theming.
- server → core: typed boundary · HTTP handlers are thin wrappers around the shared domain model.
- server → llm: provider routes · Server routes expose provider/model actions backed by normalized LLM adapters.
- tui → ui: rendering · The terminal UI consumes shared components, icons, and theme primitives.
- app → ui: components · The web app is built on the shared design system and theme layer.
- app → server: api client · The app talks to the local typed HTTP API boundary for sessions and workspace state.
- desktop → opencode: embedded runtime · Electron wraps the local product runtime and session/server lifecycle.
- desktop → app: renderer · Desktop reuses the web app-like renderer and shared UI stack.
- web → ui: brand system · The docs/marketing site shares visual primitives and assets with the product UI.
- console app → console core: control plane · The hosted console uses the shared account, billing, provider, and workspace domain.
- console fn → console core: background jobs · Serverless functions operate on the same control-plane domain and schemas.
- stats core → console core: analytics domain · Stats and console share some business concepts around users, workspaces, and usage.
- stats server → stats core: ingestion · The analytics server persists and serves data through the stats domain layer.
- infra → console app: deploy · Infrastructure defines the deployment topology for the console application.
- infra → stats server: deploy · Infrastructure wires the stats ingestion service into managed deployments.
- sdk js → server: openapi client · Generated SDKs target the same HTTP API exposed by the server package.
- script → opencode: publish · Repository scripts drive builds, releases, and maintenance for the main runtime.
- script → sdk js: release · Automation builds and publishes generated SDK artifacts.