# xiaomimimo/mimo-code architecture

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

- Interactive diagram: https://gitdiagram.com/xiaomimimo/mimo-code
- Repository: https://github.com/xiaomimimo/mimo-code

## Overview

1. This is a TypeScript/Bun monorepo organized around one core product runtime and several adjacent surfaces. The main execution engine lives in `packages/opencode`, while `packages/app`, `packages/desktop`, `packages/web`, `packages/console`, `packages/enterprise`, `packages/ui`, `packages/sdk`, and `packages/plugin` provide alternate clients, cloud services, documentation, and integrations.

2. The heart of the system is `packages/opencode`: a terminal-native AI coding assistant. Its top-level flow is: CLI bootstrap → config/env loading → runtime initialization → server/session orchestration → provider calls and tool execution → persistence and resume. The runtime is designed around long-lived sessions, not short request/response cycles.

3. Session management is the core domain layer. `packages/opencode/src/session`, `actor`, `task`, `workflow`, `history`, `memory`, `inbox`, and `share` implement the long-horizon agent loop: prompt assembly, LLM request/response handling, checkpoints, compaction, retries, task trees, imports, and sharing. The README’s “persistent memory” and “automatic checkpoints” are backed by this layer.

4. The agent/tool boundary is explicit. `packages/opencode/src/tool` defines the available capabilities such as shell, file read/write/edit, git, ripgrep/search, LSP, MCP, web fetch/search, memory access, tasks, and workflows. Session code decides when to invoke tools; tool modules encapsulate the concrete side effects and permission checks.

5. Model/provider integration is another major boundary. `packages/opencode/src/provider` normalizes multiple LLM backends and their auth/model schemas, while `packages/opencode/src/plugin` adds provider-specific adapters and custom behaviors. This is what allows MiMo Auto, Xiaomi MiMo Platform OAuth, Claude imports, and OpenAI-compatible custom providers to coexist under one abstraction.

6. Persistent state is stored locally and is a first-class subsystem. `packages/opencode/src/storage` and the SQL schema files under `session`, `memory`, `task`, `workflow`, `sync`, and related modules indicate a SQLite-backed store with migrations. Memory and history use FTS-style search and are treated as durable context inputs for future sessions, not just logs.

7. The local UI is split across multiple shells. `packages/opencode/src/cli/cmd/tui` provides the terminal UI, `packages/desktop` wraps the same product in an Electron-style desktop shell, and `packages/app` contains a separate Solid/Vite web app that mirrors much of the session UI. These surfaces all sit above the same core session/service layer rather than reimplementing agent logic.

8. `packages/ui` is the shared presentation library. It contains reusable components, theming, i18n, and small interaction primitives used by the app/desktop/web surfaces. The architecture boundary here is “visual and interaction components only”; business logic stays in `opencode` or the product-specific apps.

9. `packages/console` is the cloud control plane for MiMoCode. It is an Astro/Vite app plus backend route handlers, auth, billing, model/provider management, workspace administration, and public marketing/docs endpoints. Unlike the local agent runtime, this side focuses on account lifecycle, subscriptions, rate limiting, provider routing, and enterprise features.

10. The console’s backend is split into `packages/console/core`, `function`, `mail`, and `resource`. `core` contains domain logic and database schema/migrations via Drizzle; `function` holds serverless helpers such as auth/log processing; `mail` renders transactional email templates; `resource` declares cloud resources. External dependencies here materially shape the architecture: OAuth, Stripe webhooks, provider APIs, and rate limit enforcement.

11. Sharing and enterprise distribution have their own surface area. `packages/enterprise` serves shared session/content views, while `packages/opencode/src/share` and the web app’s `pages/s/[id]` route support rendering exported conversations. This is a separate read-only publishing path from the interactive session runtime.

12. Integrations are packaged independently. `packages/plugin` is the generic plugin package, `sdks/vscode` is a VS Code extension, and `packages/extensions/zed` is a Zed integration. These consume the core runtime contracts but remain outside the local CLI/session implementation.

13. The documentation and public website are separate from the product runtime. `packages/web` is the Astro-based docs/marketing site with multilingual content, while `packages/console/app` also serves product-facing pages and docs routes for the cloud service. These sites are content-heavy and mostly consume shared share-rendering components rather than core agent logic.

14. Cross-cutting build and deployment concerns are centralized in the repo root. `sst.config.ts`, `infra/`, and the various `script/` and `packages/*/script` directories orchestrate cloud deployment, releases, code generation, and packaging. The repo uses Bun, Turborepo, Vite, Storybook, Playwright, and extensive tests to keep the local runtime, cloud control plane, and UI surfaces aligned.

Main entry points: [`packages/opencode/src/session/index.ts`](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/session/index.ts) (Session engine), [`packages/opencode/src/server/server.ts`](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/server/server.ts) (Local server), [`packages/opencode/src/cli/bootstrap.ts`](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/cli/bootstrap.ts) (CLI bootstrap), [`packages/opencode/src/effect/runtime.ts`](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/effect/runtime.ts) (App runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Repo root"]
  node_root_build["Build & infra<br/>monorepo orchestration"]
end

subgraph group_opencode["Core runtime"]
  node_opencode_cli["CLI bootstrap<br/>runtime entry<br/>[bootstrap.ts]"]
  node_opencode_config["Config layer<br/>settings/env<br/>[index.ts]"]
  node_opencode_runtime["App runtime<br/>effect runtime<br/>[runtime.ts]"]
  node_opencode_server["Local server<br/>ipc/http server<br/>[server.ts]"]
  node_opencode_session[("Session engine<br/>agent loop<br/>[index.ts]")]
  node_opencode_tools["Tool system<br/>tool boundary<br/>[index.ts]"]
  node_opencode_provider["Provider layer<br/>llm adapter<br/>[index.ts]"]
  node_opencode_plugin["Plugin system<br/>provider/plugins<br/>[index.ts]"]
  node_opencode_storage[("SQLite store<br/>local persistence<br/>[index.ts]")]
  node_opencode_state["History & memory<br/>durable context<br/>[index.ts]"]
  node_opencode_task["Task workflow<br/>task orchestration<br/>[index.ts]"]
  node_opencode_workspace["Workspace mgmt<br/>project/worktree<br/>[index.ts]"]
end

subgraph group_surfaces["User surfaces"]
  node_tui_app["Terminal UI<br/>tui client<br/>[app.tsx]"]
  node_desktop_app["Desktop shell<br/>electron client<br/>[index.ts]"]
  node_web_app["Web app<br/>solid web client<br/>[app.tsx]"]
  node_enterprise_share["Share views<br/>read-only publishing<br/>[[shareID].tsx]"]
end

subgraph group_console["Cloud console"]
  node_console_app["Console app<br/>cloud control plane<br/>[app.tsx]"]
  node_console_core[("Console core<br/>cloud domain<br/>[account.ts]")]
end

subgraph group_ecosystem["Ecosystem"]
  node_sdk_plugin_ecosystem["SDKs & plugins<br/>integrations<br/>[index.ts]"]
  node_shared_ui["Shared UI<br/>component library<br/>[button.tsx]"]
  node_docs_site["Docs site<br/>astro docs<br/>[[...slug].md.ts]"]
end

node_root_build -->|"builds"| node_opencode_cli
node_root_build -->|"packages"| node_desktop_app
node_root_build -->|"deploys"| node_console_app
node_opencode_cli -->|"loads"| node_opencode_config
node_opencode_cli -->|"starts"| node_opencode_runtime
node_opencode_runtime -->|"hosts"| node_opencode_server
node_opencode_runtime -->|"binds"| node_opencode_workspace
node_opencode_server -->|"orchestrates"| node_opencode_session
node_opencode_session -->|"calls"| node_opencode_provider
node_opencode_session -->|"invokes"| node_opencode_tools
node_opencode_session -->|"persists"| node_opencode_storage
node_opencode_session -->|"reads/writes"| node_opencode_state
node_opencode_session -->|"coordinates"| node_opencode_task
node_opencode_provider -->|"extends"| node_opencode_plugin
node_opencode_tools -->|"operates on"| node_opencode_workspace
node_opencode_tools -->|"guards"| node_opencode_storage
node_tui_app -->|"talks to"| node_opencode_server
node_desktop_app -->|"talks to"| node_opencode_server
node_web_app -->|"talks to"| node_opencode_server
node_console_app -->|"uses"| node_console_core
node_console_app -->|"renders with"| node_shared_ui
node_enterprise_share -->|"renders"| node_opencode_state
node_docs_site -->|"reuses"| node_enterprise_share
node_sdk_plugin_ecosystem -->|"integrates with"| node_opencode_server
node_sdk_plugin_ecosystem -->|"shares"| node_shared_ui

click node_opencode_cli "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/cli/bootstrap.ts"
click node_opencode_config "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/config/index.ts"
click node_opencode_runtime "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/effect/runtime.ts"
click node_opencode_server "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/server/server.ts"
click node_opencode_session "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/session/index.ts"
click node_opencode_tools "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/tool/index.ts"
click node_opencode_provider "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/provider/index.ts"
click node_opencode_plugin "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/plugin/index.ts"
click node_opencode_storage "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/storage/index.ts"
click node_opencode_state "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/history/index.ts"
click node_opencode_task "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/task/index.ts"
click node_opencode_workspace "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/project/index.ts"
click node_tui_app "https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx"
click node_desktop_app "https://github.com/xiaomimimo/mimo-code/blob/main/packages/desktop/src/main/index.ts"
click node_web_app "https://github.com/xiaomimimo/mimo-code/blob/main/packages/app/src/app.tsx"
click node_console_app "https://github.com/xiaomimimo/mimo-code/blob/main/packages/console/app/src/app.tsx"
click node_console_core "https://github.com/xiaomimimo/mimo-code/blob/main/packages/console/core/src/account.ts"
click node_enterprise_share "https://github.com/xiaomimimo/mimo-code/blob/main/packages/enterprise/src/routes/share/[shareID].tsx"
click node_sdk_plugin_ecosystem "https://github.com/xiaomimimo/mimo-code/blob/main/packages/sdk/js/src/index.ts"
click node_shared_ui "https://github.com/xiaomimimo/mimo-code/blob/main/packages/ui/src/components/button.tsx"
click node_docs_site "https://github.com/xiaomimimo/mimo-code/blob/main/packages/web/src/pages/[...slug].md.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_root_build toneBlue
class node_opencode_cli,node_opencode_config,node_opencode_runtime,node_opencode_server,node_opencode_session,node_opencode_tools,node_opencode_provider,node_opencode_plugin,node_opencode_storage,node_opencode_state,node_opencode_task,node_opencode_workspace toneAmber
class node_tui_app,node_desktop_app,node_web_app,node_enterprise_share toneMint
class node_console_app,node_console_core toneRose
class node_sdk_plugin_ecosystem,node_shared_ui,node_docs_site toneIndigo
```

## Components

### Repo root

Workspace-wide build, infra, and orchestration

- **Build & infra**: monorepo orchestration · Repo-wide scripts, deployment, and packaging entrypoints

### Core runtime

Local AI coding assistant runtime and its subsystems

- [CLI bootstrap](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/cli/bootstrap.ts): runtime entry · Command parsing, startup, upgrades, and TUI launch · `packages/opencode/src/cli/bootstrap.ts`
- [Config layer](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/config/index.ts): settings/env · Loads and normalizes app, provider, model, plugin, and permission config · `packages/opencode/src/config/index.ts`
- [App runtime](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/effect/runtime.ts): effect runtime · Bootstraps services, logging, observability, and process coordination · `packages/opencode/src/effect/runtime.ts`
- [Local server](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/server/server.ts): ipc/http server · Bun/Node server, routes, middleware, and control-plane endpoints · `packages/opencode/src/server/server.ts`
- [Session engine](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/session/index.ts): agent loop · Long-lived session state, prompt assembly, checkpoints, compaction, retries, and summaries · `packages/opencode/src/session/index.ts`
- [Tool system](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/tool/index.ts): tool boundary · Shell, file, search, LSP, MCP, memory, task, and workflow tool definitions and execution · `packages/opencode/src/tool/index.ts`
- [Provider layer](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/provider/index.ts): llm adapter · Normalizes LLM backends, auth, model schemas, and response transforms · `packages/opencode/src/provider/index.ts`
- [Plugin system](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/plugin/index.ts): provider/plugins · Provider-specific adapters, checkpoint hooks, and plugin loading · `packages/opencode/src/plugin/index.ts`
- [SQLite store](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/storage/index.ts): local persistence · Local durable storage, schema, migrations, and SQLite access · `packages/opencode/src/storage/index.ts`
- [History & memory](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/history/index.ts): durable context · Persistent history, memory FTS, inbox, share, and sync-related context stores · `packages/opencode/src/history/index.ts`
- [Task workflow](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/task/index.ts): task orchestration · Task trees, gates, events, and workflow orchestration for agent work · `packages/opencode/src/task/index.ts`
- [Workspace mgmt](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/project/index.ts): project/worktree · Project, workspace, VCS, trust, and worktree lifecycle · `packages/opencode/src/project/index.ts`

### User surfaces

Local and web client shells built on top of the runtime

- [Terminal UI](https://github.com/xiaomimimo/mimo-code/blob/main/packages/opencode/src/cli/cmd/tui/app.tsx): tui client · Terminal-native interactive shell, dialogs, and session views · `packages/opencode/src/cli/cmd/tui/app.tsx`
- [Desktop shell](https://github.com/xiaomimimo/mimo-code/blob/main/packages/desktop/src/main/index.ts): electron client · Desktop main/preload/renderer app with IPC, windows, updates, and local state · `packages/desktop/src/main/index.ts`
- [Web app](https://github.com/xiaomimimo/mimo-code/blob/main/packages/app/src/app.tsx): solid web client · Browser-based session UI and shared session rendering routes · `packages/app/src/app.tsx`
- [Share views](https://github.com/xiaomimimo/mimo-code/blob/main/packages/enterprise/src/routes/share/[shareID].tsx): read-only publishing · Shared session rendering and export/read-only share surfaces · `packages/enterprise/src/routes/share/[shareID].tsx`

### Cloud console

MiMoCode cloud control plane and admin surfaces

- [Console app](https://github.com/xiaomimimo/mimo-code/blob/main/packages/console/app/src/app.tsx): cloud control plane · Astro/Vite product site, auth, billing, providers, workspace admin, and API routes · `packages/console/app/src/app.tsx`
- [Console core](https://github.com/xiaomimimo/mimo-code/blob/main/packages/console/core/src/account.ts): cloud domain · Shared cloud domain logic, database schema, billing, providers, accounts, and workspaces · `packages/console/core/src/account.ts`

### Ecosystem

SDKs, plugins, extensions, and shared libraries

- [SDKs & plugins](https://github.com/xiaomimimo/mimo-code/blob/main/packages/sdk/js/src/index.ts): integrations · JS SDK, VS Code extension, generic plugin package, and other external integrations · `packages/sdk/js/src/index.ts`
- [Shared UI](https://github.com/xiaomimimo/mimo-code/blob/main/packages/ui/src/components/button.tsx): component library · Reusable presentation components, theming, i18n, and interaction primitives · `packages/ui/src/components/button.tsx`
- [Docs site](https://github.com/xiaomimimo/mimo-code/blob/main/packages/web/src/pages/[...slug].md.ts): astro docs · Documentation and marketing content plus share-rendering components · `packages/web/src/pages/[...slug].md.ts`

## Connections

- Build & infra → CLI bootstrap: builds · Root scripts package and release the core runtime
- Build & infra → Desktop shell: packages · Desktop build and signing are orchestrated from the repo root
- Build & infra → Console app: deploys · Infra definitions wire the cloud console into cloud resources
- CLI bootstrap → Config layer: loads · CLI startup resolves config, env, and defaults
- CLI bootstrap → App runtime: starts · Bootstrap hands control to the effect runtime
- App runtime → Local server: hosts · Runtime serves local IPC/HTTP endpoints and route handlers
- App runtime → Workspace mgmt: binds · Runtime attaches project/workspace context to execution
- Local server → Session engine: orchestrates · Server routes create, inspect, and drive sessions
- Session engine → Provider layer: calls · Session loop invokes model providers for generation
- Session engine → Tool system: invokes · Agent turns request tool actions through the tool boundary
- Session engine → SQLite store: persists · Sessions write checkpoints, messages, and durable state locally
- Session engine → History & memory: reads/writes · History, memory, inbox, and share data feed the long-horizon loop
- Session engine → Task workflow: coordinates · Task trees and workflow state structure agent work
- Provider layer → Plugin system: extends · Plugins adapt specific providers and custom behaviors
- Tool system → Workspace mgmt: operates on · Tools act within the current project/worktree context
- Tool system → SQLite store: guards · Tool execution consults local permissions and stored state
- Terminal UI → Local server: talks to · Terminal UI consumes the local server/session API
- Desktop shell → Local server: talks to · Desktop shell reuses the same runtime services
- Web app → Local server: talks to · Web client mirrors session interactions through the shared service layer
- Console app → Console core: uses · Console routes rely on shared domain logic and schema
- Console app → Shared UI: renders with · Cloud UI reuses the shared presentation library
- Share views → History & memory: renders · Read-only share views consume exported session content
- Docs site → Share views: reuses · Docs and marketing pages reuse share-rendering components
- SDKs & plugins → Local server: integrates with · SDKs and extensions target the core runtime contracts
- SDKs & plugins → Shared UI: shares · Some integrations reuse shared visual primitives and theming