# wecode-ai/runvsagent architecture

> Architecture diagram of the GitHub repository wecode-ai/runvsagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wecode-ai/runvsagent
- Repository: https://github.com/wecode-ai/runvsagent

## Overview

##### Project Type & Purpose
- RunVSAgent is a cross-IDE integration tool (full-stack, plugin-based) that lets you run VS Code–style coding agents (e.g., Roo Code, Cline) inside JetBrains IDEs.
- It consists of two main parts:
- A Kotlin-based JetBrains plugin that lives inside the IDE.
- A Node.js/TypeScript “extension host” process that emulates VS Code’s API and manages the agents.

##### File-Structure Analysis
Top-level directories:
- extension_host/ → Node.js runtime, TS source, RPC & VS Code API layer
- jetbrains_plugin/ → Kotlin plugin code, organized into core, editor, actions, IPC proxies, webview, etc.
- scripts/ → build/setup/test shell scripts
- deps/, docs/, configs (BUILD.md, README.md)

Patterns & clues:
- RPC layer in extension_host/src/rpcManager.ts + IPC proxy interfaces in jetbrains_plugin (com/sina/weibo/agent/ipc/proxy)
- WebView support both in plugin (webview manager) and extension host (webViewManager.ts)
- Gradle build for plugin and npm/pnpm/tsup for extension host

##### README Insights
- Technology stack callouts: Node.js 18+/TypeScript 5.0+, Kotlin 1.8+/IntelliJ Platform, Unix domain sockets/Named pipes for IPC.

- JetBrains IDE Process
– Kotlin Plugin (modules: core, actions, editor bridge, webview integration)
– UI Integration & Tool Window
- Extension Host Process
– Node.js Runtime
– VSCode API Compatibility Layer
– RPC Manager (message broker)
– Agent Manager (lifecycle & loading of agents)
- VSCode Agents
– Cline, RooCode, others (each as plugin bundles loaded by the host)
- External/OS services
– IPC Channel (Unix Domain Socket or Named Pipe)
– File System, Network, Shell for agents’ side effects

1. IDE Plugin ↔ Extension Host via RPC channel:
– “register command” / “invoke API” / “handle events”
2. Plugin → IDE Editor & UI API (IntelliJ Platform)
3. Extension Host → VSCode API stubs → Agents
4. Agents → VSCode API → Host → Plugin → IDE

c. Architectural Patterns & Principles:
- Modular separation: Plugin vs Host vs Agents
- Interprocess communication via RPC & message proxies
- Adapter/compatibility pattern: VSCode API layer adapts VS Code extensions to JetBrains environment
- Plugin lifecycle management (bootstrap scripts, extensionHost/bootstrap-*.ts)

d. Key Technologies & Frameworks:
- Kotlin + IntelliJ Platform SDK (JetBrains Plugin)
- Node.js + TypeScript + tsup (Extension Host bundler)
- IPC via Unix Domain Socket / Named Pipe
- Gradle (build plugin), npm/pnpm (build host), shell scripts (scripts/*)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Swimlane: JetBrains IDE Process
    subgraph "JetBrains IDE Process"
        %% Plugin Core Modules
        subgraph "Plugin Core"
            EHostManager["ExtensionHostManager"]:::kotlin
            EProcessManager["ExtensionProcessManager"]:::kotlin
            SocketServer["ExtensionSocketServer"]:::kotlin
            UDSServer["ExtensionUnixDomainSocketServer"]:::kotlin
            PluginRPCManager["RPCManager"]:::kotlin
        end

        %% UI & Tool Window
        UIToolWindow["RunVSAgentToolWindowFactory"]:::kotlin

        %% Editor Bridge
        subgraph "Editor Bridge"
            DocManager["EditorAndDocManager"]:::kotlin
            EditorListener["EditorListener"]:::kotlin
            EditorCommands["EditorCommands"]:::kotlin
        end

        %% Actions
        Actions["VSCodeCommandActions"]:::kotlin

        %% IPC Proxies
        subgraph "IPC Proxies"
            ProtocolReader["ProtocolReader"]:::kotlin
            ProtocolWriter["ProtocolWriter"]:::kotlin
            RPCProtocol["RPCProtocol"]:::kotlin
            ExtHostCommandsProxy["ExtHostCommandsProxy"]:::kotlin
        end

        %% WebView Integration
        WebViewMgrPlugin["WebViewManager"]:::kotlin
        PluginXML["plugin.xml"]:::kotlin
    end

    %% IPC Layer
    IPCChannel[("IPC Channel\n(Unix Domain Socket/Named Pipe)")]:::ipc

    %% Swimlane: Extension Host Process
    subgraph "Extension Host Process"
        %% Entry & Bootstrap
        subgraph "Entry & Bootstrap"
            MainTS["main.ts"]:::node
            BootstrapServer["bootstrap-server.ts"]:::node
            BootstrapCLI["bootstrap-cli.ts"]:::node
        end

        %% VS Code API Emulation
        subgraph "VS Code API Emulation"
            ExtensionEntry["extension.ts"]:::node
            WebViewMgrHost["webViewManager.ts"]:::node
        end

        %% RPC & Agent Management
        subgraph "Host Management"
            HostRPCManager["rpcManager.ts"]:::node
            ExtensionMgr["extensionManager.ts"]:::node
        end

        %% Build & Config
        subgraph "Build & Config"
            TSUP["tsup.config.ts"]:::node
            PackageJSON["package.json"]:::node
            TSConfig["tsconfig.json"]:::node
        end
    end

    %% Swimlane: VS Code Agents
    subgraph "VS Code Agents"
        RooCode["roo-code"]:::agent
        VSCodeDep["vscode"]:::agent
    end

    %% External Services
    FileSystem[(File System)]:::ipc
    Network[(Network/Shell)]:::ipc

    %% Connections
    Actions -->|"invoke RPC"| ProtocolWriter
    ProtocolWriter -->|"write"| IPCChannel
    PluginRPCManager -->|"send/receive messages"| IPCChannel
    IPCChannel -->|"RPC messages"| HostRPCManager
    HostRPCManager -->|"manage agents"| ExtensionMgr
    ExtensionMgr -->|"load extensions"| ExtensionEntry
    ExtensionEntry -->|"API calls"| WebViewMgrHost
    ExtensionEntry -->|"invoke agent code"| RooCode
    ExtensionEntry -->|"invoke agent code"| VSCodeDep
    RooCode -->|"calls API"| ExtensionEntry
    VSCodeDep -->|"calls API"| ExtensionEntry
    ExtensionEntry -->|"send events"| HostRPCManager
    HostRPCManager -->|"forward events"| IPCChannel
    IPCChannel -->|"deliver events"| PluginRPCManager
    PluginRPCManager -->|"update UI"| UIToolWindow
    DocManager -->|"editor events"| PluginRPCManager
    EditorListener -->|"document changes"| PluginRPCManager
    EditorCommands -->|"editor commands"| PluginRPCManager
    UIToolWindow -->|"user commands"| Actions
    PluginRPCManager -->|"proxy calls"| ExtHostCommandsProxy
    ExtHostCommandsProxy -->|"write"| ProtocolWriter
    ExtensionMgr -->|"access FS/Network"| FileSystem
    ExtensionMgr -->|"spawn processes"| Network

    %% Click Events
    click EHostManager "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/core/ExtensionHostManager.kt"
    click EProcessManager "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/core/ExtensionProcessManager.kt"
    click SocketServer "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/core/ExtensionSocketServer.kt"
    click UDSServer "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/core/ExtensionUnixDomainSocketServer.kt"
    click PluginRPCManager "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/core/RPCManager.kt"
    click UIToolWindow "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/ui/RunVSAgentToolWindowFactory.kt"
    click DocManager "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/editor/EditorAndDocManager.kt"
    click EditorListener "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/editor/EditorListener.kt"
    click EditorCommands "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/editor/EditorCommands.kt"
    click Actions "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/actions/VSCodeCommandActions.kt"
    click ProtocolReader "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/ipc/ProtocolReader.kt"
    click ProtocolWriter "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/ipc/ProtocolWriter.kt"
    click RPCProtocol "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/ipc/proxy/RPCProtocol.kt"
    click ExtHostCommandsProxy "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/ipc/proxy/interfaces/ExtHostCommandsProxy.kt"
    click WebViewMgrPlugin "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/kotlin/com/sina/weibo/agent/webview/WebViewManager.kt"
    click PluginXML "https://github.com/wecode-ai/runvsagent/blob/main/jetbrains_plugin/src/main/resources/META-INF/plugin.xml"
    click MainTS "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/src/main.ts"
    click BootstrapServer "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/bootstrap-server.ts"
    click BootstrapCLI "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/bootstrap-cli.ts"
    click ExtensionEntry "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/src/extension.ts"
    click WebViewMgrHost "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/src/webViewManager.ts"
    click HostRPCManager "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/src/rpcManager.ts"
    click ExtensionMgr "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/src/extensionManager.ts"
    click TSUP "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/tsup.config.ts"
    click PackageJSON "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/package.json"
    click TSConfig "https://github.com/wecode-ai/runvsagent/blob/main/extension_host/tsconfig.json"
    click RooCode "https://github.com/wecode-ai/runvsagent/tree/main/deps/roo-code"
    click VSCodeDep "https://github.com/wecode-ai/runvsagent/tree/main/deps/vscode"
    click FileSystem "https://github.com/wecode-ai/runvsagent/tree/main/File System"
    click Network "https://github.com/wecode-ai/runvsagent/tree/main/Network/Shell"

    %% Styles
    classDef kotlin fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef node fill:#ABEBC6,stroke:#186A3B,color:#145A32;
    classDef agent fill:#F9E79F,stroke:#7D6608,color:#7D6608;
    classDef ipc fill:#D5D8DC,stroke:#566573,color:#2C3E50;
```
