# arover/agenttars architecture

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

- Interactive diagram: https://gitdiagram.com/arover/agenttars
- Repository: https://github.com/arover/agenttars

## Overview

##### Project Type & Purpose
- This is a monorepo for a **desktop GUI-agent platform** built on Electron + React + TypeScript. It delivers two Electron apps under `apps/`:
- **agent-tars** – a “technical preview” multimodal AI agent, capable of web-page visual interpretation + command-line/file-system controls
- **ui-tars** – the flagship UI-TARS agent desktop, controlling your computer via natural language and a Vision-Language Model
- The remainder of the repo hosts supporting **libraries** (agent-infra, common, shared, operators, sdk, cli, electron-ipc, visualizer) and **examples**, all tied together with pnpm/Turbo for build/test orchestration.

##### File Structure Analysis
- Top-level folders:
- `apps/` – two Electron apps (each with `main`, `preload`, `renderer` layers, build configs, resources)
- `packages/` – modular libraries (agent infrastructure, CLI, SDK, operators, shared types/utils, visualizer, etc.)
- `docs/`, `examples/` – documentation and usage samples
- `scripts/`, `.github/`, `turbo.json`, `pnpm-workspace.yaml` – CI/CD, release automation, monorepo tooling
- Patterns & Configs:
- **Electron architecture**: `main` (Node.js background), `preload` (IPC bridge), `renderer` (React UI)
- **Plugin/Provider pattern** for LLMs under `agent-tars/src/main/llmProvider`
- **Micro-libraries** for browser automation, search, logging, MCP (message/control protocol) servers & clients
- **Workspace testing** with Vitest, Playwright, e2e workflows, and CI pipelines under `.github`.

a. Main Components
- **Electron Apps**
- Agent-TARS Main Process
- Agent-TARS Renderer (React + Vite)
- UI-TARS Main Process
- UI-TARS Renderer (React + Vite)
- **Preload/IPCs**: bridges exposing safe APIs to renderer
- **Core Libraries** (`packages/agent-infra`, `packages/common`, `packages/shared`)
- **SDK & CLI** (`packages/ui-tars/sdk`, `packages/ui-tars/cli`)
- **Operators & Electron-IPC** (`packages/ui-tars/operators/*`, `packages/ui-tars/electron-ipc`)
- **External Services**
- LLM Providers (OpenAI, Anthropic, Mistral, Gemini, AzureOpenAI…)
- ModelScope platform (optional cloud deployment)
- Local OS (file system, browser automation, system permissions)

b. Relationships & Interactions
- **Renderer → Preload → Main** (data-flow for UI events, commands, results)
- **Main → agent-infra/mcp-client → MCP servers** (file system commands, shell commands, browser operations)
- **Main → LLM provider modules** (via ProviderFactory) → External LLM APIs
- **Renderer** calls UI services (chat session storage, file-permission service, agent flows)
- **SDK/CLI** consume shared packages to script or extend agent capabilities
- **Operators** plug into agent-infra to add new device/browser/file operations

c. Architectural Patterns & Principles
- **Monorepo modularity**: clear separation of concerns by package
- **Plugin/provider** for LLM engines – easy extension and configuration
- **IPC boundary** to sandbox renderer and expose only whitelisted APIs
- **Event-driven flows** in React for agent conversations and canvas replay
- **Microservices style** within local context: MCP servers for file/shell operations

d. Key Technologies & Frameworks
- **Electron** (main/preload/renderer splits)
- **React + Vite** (UI)
- **TypeScript** (all layers)
- **pnpm & Turbo** (monorepo, workspace management, caching)
- **Vitest / Playwright** (unit & e2e tests)
- **Node.js** (back-end services)
- **Various LLM SDKs** via HTTP/gRPC

## Diagram (Mermaid)

```mermaid
graph TB
    %% Agent-TARS App
    subgraph "Agent-TARS Electron App"
        direction TB
        ATM["Agent-TARS Main Process"]:::main
        ATP["Agent-TARS Preload (IPC Bridge)"]:::ipc
        ATR["Agent-TARS Renderer (React + Vite UI)"]:::ui
        ATR -->|"ui events"| ATP
        ATP -->|"ipcRoutes/*"| ATM
    end

    %% UI-TARS App
    subgraph "UI-TARS Electron App"
        direction TB
        UTM["UI-TARS Main Process"]:::main
        UTP["UI-TARS Preload (IPC Bridge)"]:::ipc
        UTR["UI-TARS Renderer (React + Vite UI)"]:::ui
        UTR -->|"ui events"| UTP
        UTP -->|"ipcRoutes/*"| UTM
    end

    %% Core Libraries
    subgraph "Core Libraries / Packages"
        direction TB
        AINF["Package: agent-infra"]:::lib
        COMMON["Package: common"]:::lib
        SHARED1["Package: agent-infra/shared"]:::lib
        SHARED2["Package: ui-tars/shared"]:::lib
    end

    %% MCP Protocol
    subgraph "MCP Protocol"
        direction TB
        MCP_C["MCP Client"]:::lib
        MCP_S["MCP Servers"]:::lib
    end

    %% Browser & Search
    subgraph "Browser & Search Libraries"
        direction TB
        BUSE["Package: agent-infra/browser-use"]:::lib
        BROW["Package: agent-infra/browser"]:::lib
        SEARCH["Package: agent-infra/search"]:::lib
    end

    %% UI-TARS Extensions
    subgraph "UI-TARS Extensions"
        direction TB
        CLI["Package: ui-tars/cli"]:::lib
        SDK["Package: ui-tars/sdk"]:::lib
        EIPC["Package: ui-tars/electron-ipc"]:::lib
        OP1["Package: ui-tars/operators/browser-operator"]:::lib
        OP2["Package: ui-tars/operators/browserbase"]:::lib
        OP3["Package: ui-tars/operators/nut-js"]:::lib
        VIS["Package: ui-tars/visualizer"]:::lib
        UTIO["Package: ui-tars/utio"]:::lib
    end

    %% External Services
    subgraph "External Integrations"
        direction TB
        LLM["LLM Providers (OpenAI, Anthropic, Mistral, Gemini, AzureOpenAI…)"]:::external
        CLOUD["ModelScope / Cloud Endpoints"]:::external
        OS["Local OS Services (fs, shell, browser automation)"]:::external
    end

    %% Connections Agent-TARS Main
    ATM -->|uses| AINF
    ATM -->|calls| MCP_C
    MCP_C -->|controls| MCP_S
    ATM -->|uses| BUSE
    ATM -->|uses| BROW
    ATM -->|uses| SEARCH
    ATM -->|loads plugins| SHARED1
    ATM -->|calls| LLM
    ATM -->|optional deploy| CLOUD
    ATM -->|os ops| OS

    %% Connections UI-TARS Main
    UTM -->|uses| AINF
    UTM -->|uses| COMMON
    UTM -->|calls| MCP_C
    UTM -->|loads plugins| SHARED2
    UTM -->|calls| LLM
    UTM -->|optional deploy| CLOUD
    UTM -->|os ops| OS
    UTM -->|integrates| EIPC

    %% SDK/CLI usage
    CLI -->|depends on| SHARED2
    CLI -->|uses| AINF
    SDK -->|depends on| SHARED2
    SDK -->|uses| AINF

    %% IPC Flow
    ATR -->|IPC request| ATP
    ATP -->|IPC handler| ATM
    UTR -->|IPC request| UTP
    UTP -->|IPC handler| UTM

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000
    classDef main fill:#90EE90,stroke:#000
    classDef ipc fill:#98FB98,stroke:#000
    classDef lib fill:#D3D3D3,stroke:#000
    classDef external fill:#FFA500,stroke:#000

    %% Click Events
    click ATM "https://github.com/arover/agenttars/tree/main/apps/agent-tars/src/main"
    click ATP "https://github.com/arover/agenttars/tree/main/apps/agent-tars/src/preload"
    click ATR "https://github.com/arover/agenttars/tree/main/apps/agent-tars/src/renderer"
    click UTM "https://github.com/arover/agenttars/tree/main/apps/ui-tars/src/main"
    click UTP "https://github.com/arover/agenttars/tree/main/apps/ui-tars/src/preload"
    click UTR "https://github.com/arover/agenttars/tree/main/apps/ui-tars/src/renderer"
    click AINF "https://github.com/arover/agenttars/tree/main/packages/agent-infra"
    click COMMON "https://github.com/arover/agenttars/tree/main/packages/common"
    click SHARED1 "https://github.com/arover/agenttars/tree/main/packages/agent-infra/shared"
    click SHARED2 "https://github.com/arover/agenttars/tree/main/packages/ui-tars/shared"
    click MCP_C "https://github.com/arover/agenttars/tree/main/packages/agent-infra/mcp-client"
    click MCP_S "https://github.com/arover/agenttars/tree/main/packages/agent-infra/mcp-servers"
    click BUSE "https://github.com/arover/agenttars/tree/main/packages/agent-infra/browser-use"
    click BROW "https://github.com/arover/agenttars/tree/main/packages/agent-infra/browser"
    click SEARCH "https://github.com/arover/agenttars/tree/main/packages/agent-infra/search"
    click CLI "https://github.com/arover/agenttars/tree/main/packages/ui-tars/cli"
    click SDK "https://github.com/arover/agenttars/tree/main/packages/ui-tars/sdk"
    click EIPC "https://github.com/arover/agenttars/tree/main/packages/ui-tars/electron-ipc"
    click OP1 "https://github.com/arover/agenttars/tree/main/packages/ui-tars/operators/browser-operator"
    click OP2 "https://github.com/arover/agenttars/tree/main/packages/ui-tars/operators/browserbase"
    click OP3 "https://github.com/arover/agenttars/tree/main/packages/ui-tars/operators/nut-js"
    click VIS "https://github.com/arover/agenttars/tree/main/packages/ui-tars/visualizer"
    click UTIO "https://github.com/arover/agenttars/tree/main/packages/ui-tars/utio"
```
