# thesyart/emperor-agent architecture

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

- Interactive diagram: https://gitdiagram.com/thesyart/emperor-agent
- Repository: https://github.com/thesyart/emperor-agent

## Overview

#### 1. Purpose and execution surfaces
Emperor Agent is a local-first, single-user desktop agent workbench for chat, project-bound work, planning, and persistent Goal execution. The production path is Electron hosting the TypeScript Core in-process; the renderer reaches it only through IPC. Python, HTTP, and WebSocket backends are retired.

Primary entry points:
- Electron main process: `desktop/src/main/index.ts`
- Core library composition/export: `packages/core/src/index.ts`
- Sandboxed renderer bootstrap: `desktop/src/renderer/src/main.ts`
- Headless local stdio ACP preview: `packages/core/src/acp/stdio-entry.ts`

#### 2. Desktop process boundary
Electron main owns windows, runtime roots, Core host lifecycle, terminal hosting, and IPC/event bridges. Preload exposes a constrained API to the untrusted/sandboxed renderer; shared contracts define that boundary.

- Core hosting/config: `desktop/src/main/core-host.ts`, `desktop/src/main/config.ts`
- IPC and event forwarding: `desktop/src/main/ipc.ts`, `desktop/src/main/event-bridge.ts`
- Preload bridge: `desktop/src/preload/index.ts`, `desktop/src/shared/ipc-contract.ts`

Control flow is renderer action → preload IPC → main/Core API → runtime event → main event bridge → preload → renderer state update.

#### 3. Core API, runtime, and persistence
CoreApi is the application façade for chat, configuration, workspace, Goal, diagnostics, and other services. Runtime establishes the local state root, resources, session lifecycle, and durable stores. User-private data is filesystem-backed under `stateRoot`; project folders remain separate from session/memory/Goal state.

- API façade and operations: `packages/core/src/api/core-api.ts`, `packages/core/src/api/operations.ts`
- Runtime/session ownership: `packages/core/src/runtime/lifecycle.ts`, `packages/core/src/runtime/session-runtime.ts`
- Durable primitives: `packages/core/src/store/atomic-json.ts`, `packages/core/src/store/jsonl.ts`
- Sessions and project state: `packages/core/src/sessions/store.ts`, `packages/core/src/projects/state-store.ts`

#### 4. Agent turn pipeline and model boundary
A chat/build request becomes an agent run: assemble context, select/call the configured model provider, dispatch allowed tools, persist turn/session state, and emit progress events. Providers are external network boundaries; fallback behavior and cost/execution policy are Core-controlled.

- Agent loop and runner: `packages/core/src/agent/loop.ts`, `packages/core/src/agent/runner.ts`
- Context construction: `packages/core/src/agent/context-builder.ts`, `packages/core/src/context/pipeline.ts`
- Model routing/calling: `packages/core/src/agent/model-caller.ts`, `packages/core/src/model/router.ts`
- Provider adapters: `packages/core/src/providers/openai-compat.ts`, `packages/core/src/providers/anthropic.ts`

#### 5. Control, permissions, plans, and Goals
Control is the principal safety/state-machine layer. It enforces Ask/Smart/Full policies, read-only Plan behavior, approvals, and execution constraints. Goal coordinates durable multi-turn work with scope, evidence, recovery, reviewer checks, and a completion gate; it serializes mutation ownership and fails closed on unsafe recovery.

- Control and Plan lifecycle: `packages/core/src/control/manager.ts`, `packages/core/src/control/plan-execution.ts`
- Permission pipeline: `packages/core/src/permissions/pipeline.ts`, `packages/core/src/permissions/workspace-policy.ts`
- Goal orchestration/gating: `packages/core/src/goals/coordinator.ts`, `packages/core/src/goals/completion-gate.ts`
- Goal persistence/recovery: `packages/core/src/goals/store.ts`, `packages/core/src/goals/recovery.ts`

#### 6. Capabilities and renderer projection
Core-owned tools operate on files, terminals, Git, MCP, skills, attachments, memory, and scheduler jobs, subject to control and permission checks. The Vue renderer projects Core events into chat, plans, goals, workspace panes, and configuration panels rather than directly owning backend state.

- Tool dispatch/execution: `packages/core/src/tools/dispatch.ts`, `packages/core/src/tools/execution.ts`
- Workspace and terminal/Git boundary: `packages/core/src/workspace/terminal.ts`, `packages/core/src/workspace/git.ts`
- MCP lifecycle: `packages/core/src/mcp/supervisor.ts`, `packages/core/src/mcp/adapter.ts`
- Renderer state/event reduction: `desktop/src/renderer/src/runtime/reducer.ts`, `desktop/src/renderer/src/runtime/runtimeEffects.ts`
- Primary UI shell: `desktop/src/renderer/src/App.vue`, `desktop/src/renderer/src/views/ChatView.vue`

Main entry points: [`packages/core/src/api/core-api.ts`](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/api/core-api.ts) (Core API), [`packages/core/src/agent/runner.ts`](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/agent/runner.ts) (Agent runner), [`desktop/src/preload/index.ts`](https://github.com/thesyart/emperor-agent/blob/main/desktop/src/preload/index.ts) (Preload API), [`desktop/src/main/ipc.ts`](https://github.com/thesyart/emperor-agent/blob/main/desktop/src/main/ipc.ts) (IPC & event bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Electron desktop"]
  node_electron_main["Electron main<br/>desktop host<br/>[index.ts]"]
  node_core_host["Core host<br/>host lifecycle<br/>[core-host.ts]"]
  node_ipc_bridge["IPC &amp; event bridge<br/>IPC bridge<br/>[ipc.ts]"]
  node_preload["Preload API<br/>sandbox bridge<br/>[index.ts]"]
  node_renderer["Vue renderer<br/>UI shell<br/>[App.vue]"]
  node_renderer_runtime["Renderer runtime<br/>event reducer<br/>[reducer.ts]"]
end

subgraph group_core["Core runtime"]
  node_core_api["Core API<br/>application facade<br/>[core-api.ts]"]
  node_runtime["Runtime &amp; sessions<br/>runtime lifecycle<br/>[lifecycle.ts]"]
  node_durable_state[("Local durable state<br/>filesystem stores<br/>[atomic-json.ts]")]
  node_acp_stdio["ACP stdio preview<br/>headless entry point<br/>[stdio-entry.ts]"]
end

subgraph group_agent["Agent execution"]
  node_agent_runner["Agent runner<br/>turn runner<br/>[runner.ts]"]
  node_context_pipeline["Context pipeline<br/>context builder<br/>[pipeline.ts]"]
  node_model_router["Model router<br/>model boundary<br/>[router.ts]"]
  node_control{{"Control &amp; plan<br/>safety state machine<br/>[manager.ts]"}}
  node_permissions{{"Permissions<br/>workspace policy<br/>[pipeline.ts]"}}
  node_goal["Goal coordinator<br/>durable orchestration<br/>[coordinator.ts]"]
end

subgraph group_external["External boundaries"]
  node_tools["Tool execution<br/>capability dispatcher<br/>[dispatch.ts]"]
  node_workspace["Workspace &amp; terminal<br/>local project boundary<br/>[terminal.ts]"]
  node_mcp["MCP supervisor<br/>integration lifecycle<br/>[supervisor.ts]"]
  node_model_providers(("Model providers<br/>external network<br/>[openai-compat.ts]"))
end

node_renderer -->|"user actions"| node_preload
node_preload -->|"constrained IPC"| node_ipc_bridge
node_ipc_bridge -->|"Core commands"| node_core_api
node_core_host -->|"hosts"| node_core_api
node_electron_main -->|"lifecycle"| node_core_host
node_ipc_bridge -->|"runtime events"| node_preload
node_preload -->|"events"| node_renderer_runtime
node_renderer_runtime -->|"state updates"| node_renderer
node_core_api -->|"uses"| node_runtime
node_runtime -->|"owns stateRoot stores"| node_durable_state
node_core_api -->|"starts turns"| node_agent_runner
node_agent_runner -->|"assembles context"| node_context_pipeline
node_agent_runner -->|"calls model"| node_model_router
node_model_router -->|"provider requests"| node_model_providers
node_agent_runner -->|"execution policy"| node_control
node_control -->|"authorizes actions"| node_permissions
node_permissions -->|"permits tools"| node_tools
node_tools -->|"files, terminal, Git"| node_workspace
node_tools -->|"MCP capabilities"| node_mcp
node_core_api -->|"manages Goals"| node_goal
node_goal -->|"governed execution"| node_control
node_goal -->|"scope, evidence, recovery"| node_durable_state
node_acp_stdio -->|"headless local access"| node_core_api

click node_electron_main "https://github.com/thesyart/emperor-agent/blob/main/desktop/src/main/index.ts"
click node_core_host "https://github.com/thesyart/emperor-agent/blob/main/desktop/src/main/core-host.ts"
click node_ipc_bridge "https://github.com/thesyart/emperor-agent/blob/main/desktop/src/main/ipc.ts"
click node_preload "https://github.com/thesyart/emperor-agent/blob/main/desktop/src/preload/index.ts"
click node_renderer "https://github.com/thesyart/emperor-agent/blob/main/desktop/src/renderer/src/App.vue"
click node_renderer_runtime "https://github.com/thesyart/emperor-agent/blob/main/desktop/src/renderer/src/runtime/reducer.ts"
click node_core_api "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/api/core-api.ts"
click node_runtime "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/runtime/lifecycle.ts"
click node_durable_state "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/store/atomic-json.ts"
click node_agent_runner "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/agent/runner.ts"
click node_context_pipeline "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/context/pipeline.ts"
click node_model_router "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/model/router.ts"
click node_control "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/control/manager.ts"
click node_permissions "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/permissions/pipeline.ts"
click node_goal "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/goals/coordinator.ts"
click node_tools "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/tools/dispatch.ts"
click node_workspace "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/workspace/terminal.ts"
click node_mcp "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/mcp/supervisor.ts"
click node_model_providers "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/providers/openai-compat.ts"
click node_acp_stdio "https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/acp/stdio-entry.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_electron_main,node_core_host,node_ipc_bridge,node_preload,node_renderer,node_renderer_runtime toneBlue
class node_core_api,node_runtime,node_durable_state,node_acp_stdio toneAmber
class node_agent_runner,node_context_pipeline,node_model_router,node_control,node_permissions,node_goal toneMint
class node_tools,node_workspace,node_mcp,node_model_providers toneRose
```

## Components

### Electron desktop

Main, preload, and sandboxed renderer processes.

- [Electron main](https://github.com/thesyart/emperor-agent/blob/main/desktop/src/main/index.ts): desktop host · Owns windows, Core lifecycle, terminals, and IPC. · `desktop/src/main/index.ts`
- [Core host](https://github.com/thesyart/emperor-agent/blob/main/desktop/src/main/core-host.ts): host lifecycle · `desktop/src/main/core-host.ts`
- [IPC & event bridge](https://github.com/thesyart/emperor-agent/blob/main/desktop/src/main/ipc.ts): IPC bridge · Forwards commands to Core and runtime events back. · `desktop/src/main/ipc.ts`
- [Preload API](https://github.com/thesyart/emperor-agent/blob/main/desktop/src/preload/index.ts): sandbox bridge · Constrained API exposed to the renderer. · `desktop/src/preload/index.ts`
- [Vue renderer](https://github.com/thesyart/emperor-agent/blob/main/desktop/src/renderer/src/App.vue): UI shell · Projects Core state into chat, plans, goals, and workspace views. · `desktop/src/renderer/src/App.vue`
- [Renderer runtime](https://github.com/thesyart/emperor-agent/blob/main/desktop/src/renderer/src/runtime/reducer.ts): event reducer · `desktop/src/renderer/src/runtime/reducer.ts`

### Core runtime

In-process application services and local state.

- [Core API](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/api/core-api.ts): application facade · Facade for chat, configuration, workspace, Goal, and diagnostics. · `packages/core/src/api/core-api.ts`
- [Runtime & sessions](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/runtime/lifecycle.ts): runtime lifecycle · Establishes state root, resources, and session ownership. · `packages/core/src/runtime/lifecycle.ts`
- [Local durable state](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/store/atomic-json.ts): filesystem stores · Private sessions, project state, memory, and Goal state under stateRoot. · `packages/core/src/store/atomic-json.ts`
- [ACP stdio preview](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/acp/stdio-entry.ts): headless entry point · Local headless Core access over stdio. · `packages/core/src/acp/stdio-entry.ts`

### Agent execution

Turn pipeline, policy, and durable Goal work.

- [Agent runner](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/agent/runner.ts): turn runner · Runs chat/build turns and emits progress. · `packages/core/src/agent/runner.ts`
- [Context pipeline](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/context/pipeline.ts): context builder · `packages/core/src/context/pipeline.ts`
- [Model router](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/model/router.ts): model boundary · Applies Core-controlled provider, fallback, cost, and execution policy. · `packages/core/src/model/router.ts`
- [Control & plan](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/control/manager.ts): safety state machine · Enforces Ask, Smart, Full, approvals, constraints, and read-only Plan mode. · `packages/core/src/control/manager.ts`
- [Permissions](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/permissions/pipeline.ts): workspace policy · `packages/core/src/permissions/pipeline.ts`
- [Goal coordinator](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/goals/coordinator.ts): durable orchestration · Serializes multi-turn mutation work, recovery, review, and completion gating. · `packages/core/src/goals/coordinator.ts`

### External boundaries

Provider and local workspace integrations.

- [Tool execution](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/tools/dispatch.ts): capability dispatcher · Dispatches allowed Core-owned capabilities. · `packages/core/src/tools/dispatch.ts`
- [Workspace & terminal](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/workspace/terminal.ts): local project boundary · Project files, terminal hosting, and Git remain outside private state. · `packages/core/src/workspace/terminal.ts`
- [MCP supervisor](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/mcp/supervisor.ts): integration lifecycle · `packages/core/src/mcp/supervisor.ts`
- [Model providers](https://github.com/thesyart/emperor-agent/blob/main/packages/core/src/providers/openai-compat.ts): external network · Configured OpenAI-compatible and Anthropic provider adapters. · `packages/core/src/providers/openai-compat.ts`

## Connections

- Vue renderer → Preload API: user actions
- Preload API → IPC & event bridge: constrained IPC
- IPC & event bridge → Core API: Core commands
- Core host → Core API: hosts
- Electron main → Core host: lifecycle
- IPC & event bridge → Preload API: runtime events
- Preload API → Renderer runtime: events
- Renderer runtime → Vue renderer: state updates
- Core API → Runtime & sessions: uses
- Runtime & sessions → Local durable state: owns stateRoot stores
- Core API → Agent runner: starts turns
- Agent runner → Context pipeline: assembles context
- Agent runner → Model router: calls model
- Model router → Model providers: provider requests
- Agent runner → Control & plan: execution policy
- Control & plan → Permissions: authorizes actions
- Permissions → Tool execution: permits tools
- Tool execution → Workspace & terminal: files, terminal, Git
- Tool execution → MCP supervisor: MCP capabilities
- Core API → Goal coordinator: manages Goals
- Goal coordinator → Control & plan: governed execution
- Goal coordinator → Local durable state: scope, evidence, recovery
- ACP stdio preview → Core API: headless local access