# cyhhao/vibe-remote architecture

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

- Interactive diagram: https://gitdiagram.com/cyhhao/vibe-remote
- Repository: https://github.com/cyhhao/vibe-remote

## Overview

Avibe is a local-first agent platform: users configure agents and model sources, then steer agent sessions from the Workbench or connected messaging platforms. Agent backends execute work; durable sessions, projects, settings, and activity support ongoing use. The README also describes scheduled and watched background work, a Model Hub gateway, and agent-built Show Pages. The graph combines those documented capabilities with relationships visible in the supplied excerpts and SOURCE INDEX; several product branches are documented but their internal wiring was not sampled.

Main entry points: [`core/controller.py`](https://github.com/cyhhao/vibe-remote/blob/master/core/controller.py) (Controller), [`modules/agents/service.py`](https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/service.py) (Agent service), [`ui/src/App.tsx`](https://github.com/cyhhao/vibe-remote/blob/master/ui/src/App.tsx) (Browser Workbench), [`vibe/model_hub_runtime/client.py`](https://github.com/cyhhao/vibe-remote/blob/master/vibe/model_hub_runtime/client.py) (Gateway runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_browser["Browser Workbench<br/>[App.tsx]"]
  node_messaging["Messaging platforms"]
end

subgraph group_control["Control plane"]
  node_controller["Controller<br/>[controller.py]"]
  node_settings["Configuration<br/>[v2_config.py]"]
  node_agent_catalog["Agent catalog<br/>[vibe_agents.py]"]
  node_sessions["Session services"]
  node_workbench_sessions["Workbench sessions"]
  node_internal_api["Internal control API<br/>[internal_client.py]"]
end

subgraph group_agents["Agent runtime"]
  node_agent_service["Agent service<br/>[service.py]"]
  node_claude["Claude backend<br/>[claude_agent.py]"]
  node_codex["Codex backend<br/>[agent.py]"]
  node_opencode["OpenCode runtime<br/>[server.py]"]
end

subgraph group_capabilities["Product capabilities"]
  node_model_hub["Model Hub<br/>[service.py]"]
  node_hub_runtime["Gateway runtime<br/>[client.py]"]
  node_harness["Agent Harness<br/>[scheduled_tasks.py]"]
  node_show_pages["Show Pages<br/>[show_pages.py]"]
  node_workbench["Workbench apps<br/>[Workbench.tsx]"]
end

subgraph group_state["Local state"]
  node_database[("Local database<br/>[db.py]")]
  node_paths["Local data paths<br/>[paths.py]"]
end

node_user(("User"))

node_user -->|"steers via"| node_browser
node_user -->|"steers via"| node_messaging
node_browser -.->|"dispatches turns"| node_controller
node_messaging -->|"dispatches messages"| node_controller
node_controller -->|"coordinates agents"| node_agent_service
node_controller -->|"loads config"| node_settings
node_controller -->|"uses catalog"| node_agent_catalog
node_controller -->|"prepares gateway"| node_model_hub
node_browser -->|"opens apps"| node_workbench
node_browser -.->|"manages sessions"| node_workbench_sessions
node_workbench_sessions -->|"queries sessions"| node_database
node_sessions -->|"persists sessions"| node_database
node_controller -->|"serves control"| node_internal_api
node_agent_service -->|"settles turns"| node_sessions
node_agent_service -->|"runs backend"| node_claude
node_agent_service -.->|"runs backend"| node_codex
node_agent_service -.->|"runs backend"| node_opencode
node_user -->|"configures sources"| node_model_hub
node_model_hub -.->|"routes requests"| node_hub_runtime
node_hub_runtime -->|"serves models"| node_claude
node_hub_runtime -->|"serves models"| node_codex
node_hub_runtime -->|"serves models"| node_opencode
node_user -->|"schedules work"| node_harness
node_harness -->|"delivers notices"| node_messaging
node_agent_service -->|"builds pages"| node_show_pages
node_sessions -->|"binds agents"| node_agent_catalog
node_settings -->|"uses data paths"| node_paths
node_database -.->|"stores local state"| node_paths

click node_browser "https://github.com/cyhhao/vibe-remote/blob/master/ui/src/App.tsx"
click node_messaging "https://github.com/cyhhao/vibe-remote/tree/master/modules/im"
click node_controller "https://github.com/cyhhao/vibe-remote/blob/master/core/controller.py"
click node_settings "https://github.com/cyhhao/vibe-remote/blob/master/config/v2_config.py"
click node_agent_catalog "https://github.com/cyhhao/vibe-remote/blob/master/core/vibe_agents.py"
click node_sessions "https://github.com/cyhhao/vibe-remote/blob/master/storage/sessions_service.py"
click node_workbench_sessions "https://github.com/cyhhao/vibe-remote/blob/master/storage/workbench_sessions_service.py"
click node_internal_api "https://github.com/cyhhao/vibe-remote/blob/master/vibe/internal_client.py"
click node_agent_service "https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/service.py"
click node_claude "https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/claude_agent.py"
click node_codex "https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/codex/agent.py"
click node_opencode "https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/opencode/server.py"
click node_model_hub "https://github.com/cyhhao/vibe-remote/blob/master/core/handlers/model_hub/service.py"
click node_hub_runtime "https://github.com/cyhhao/vibe-remote/blob/master/vibe/model_hub_runtime/client.py"
click node_harness "https://github.com/cyhhao/vibe-remote/blob/master/core/scheduled_tasks.py"
click node_show_pages "https://github.com/cyhhao/vibe-remote/blob/master/core/show_pages.py"
click node_workbench "https://github.com/cyhhao/vibe-remote/blob/master/ui/src/components/Workbench.tsx"
click node_database "https://github.com/cyhhao/vibe-remote/blob/master/storage/db.py"
click node_paths "https://github.com/cyhhao/vibe-remote/blob/master/config/paths.py"

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_browser,node_messaging,node_user toneBlue
class node_controller,node_settings,node_agent_catalog,node_sessions,node_workbench_sessions,node_internal_api toneAmber
class node_agent_service,node_claude,node_codex,node_opencode toneMint
class node_model_hub,node_hub_runtime,node_harness,node_show_pages,node_workbench toneRose
class node_database,node_paths toneIndigo
```

## Components

### User entry points

- [Browser Workbench](https://github.com/cyhhao/vibe-remote/blob/master/ui/src/App.tsx): `ui/src/App.tsx`
- [Messaging platforms](https://github.com/cyhhao/vibe-remote/tree/master/modules/im): `modules/im`

### Control plane

- [Controller](https://github.com/cyhhao/vibe-remote/blob/master/core/controller.py): `core/controller.py`
- [Configuration](https://github.com/cyhhao/vibe-remote/blob/master/config/v2_config.py): `config/v2_config.py`
- [Agent catalog](https://github.com/cyhhao/vibe-remote/blob/master/core/vibe_agents.py): `core/vibe_agents.py`
- [Session services](https://github.com/cyhhao/vibe-remote/blob/master/storage/sessions_service.py): `storage/sessions_service.py`
- [Workbench sessions](https://github.com/cyhhao/vibe-remote/blob/master/storage/workbench_sessions_service.py): `storage/workbench_sessions_service.py`
- [Internal control API](https://github.com/cyhhao/vibe-remote/blob/master/vibe/internal_client.py): `vibe/internal_client.py`

### Agent runtime

- [Agent service](https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/service.py): `modules/agents/service.py`
- [Claude backend](https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/claude_agent.py): `modules/agents/claude_agent.py`
- [Codex backend](https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/codex/agent.py): `modules/agents/codex/agent.py`
- [OpenCode runtime](https://github.com/cyhhao/vibe-remote/blob/master/modules/agents/opencode/server.py): `modules/agents/opencode/server.py`

### Product capabilities

- [Model Hub](https://github.com/cyhhao/vibe-remote/blob/master/core/handlers/model_hub/service.py): `core/handlers/model_hub/service.py`
- [Gateway runtime](https://github.com/cyhhao/vibe-remote/blob/master/vibe/model_hub_runtime/client.py): `vibe/model_hub_runtime/client.py`
- [Agent Harness](https://github.com/cyhhao/vibe-remote/blob/master/core/scheduled_tasks.py): `core/scheduled_tasks.py`
- [Show Pages](https://github.com/cyhhao/vibe-remote/blob/master/core/show_pages.py): `core/show_pages.py`
- [Workbench apps](https://github.com/cyhhao/vibe-remote/blob/master/ui/src/components/Workbench.tsx): `ui/src/components/Workbench.tsx`

### Local state

- [Local database](https://github.com/cyhhao/vibe-remote/blob/master/storage/db.py): `storage/db.py`
- [Local data paths](https://github.com/cyhhao/vibe-remote/blob/master/config/paths.py): `config/paths.py`

### Other components

- **User**

## Connections

- User → Browser Workbench: steers via (evidence: `README.md`)
- User → Messaging platforms: steers via (evidence: `README.md`)
- Browser Workbench → Controller: dispatches turns
- Messaging platforms → Controller: dispatches messages (evidence: `core/controller.py`)
- Controller → Agent service: coordinates agents (evidence: `core/controller.py`)
- Controller → Configuration: loads config (evidence: `core/controller.py`)
- Controller → Agent catalog: uses catalog (evidence: `core/controller.py`)
- Controller → Model Hub: prepares gateway (evidence: `core/controller.py`)
- Browser Workbench → Workbench apps: opens apps (evidence: `ui/src/App.tsx`)
- Browser Workbench → Workbench sessions: manages sessions
- Workbench sessions → Local database: queries sessions (evidence: `storage/workbench_sessions_service.py`)
- Session services → Local database: persists sessions (evidence: `storage/sessions_service.py`)
- Controller → Internal control API: serves control (evidence: `vibe/internal_client.py`)
- Agent service → Session services: settles turns (evidence: `modules/agents/service.py`)
- Agent service → Claude backend: runs backend (evidence: `modules/agents/service.py`)
- Agent service → Codex backend: runs backend
- Agent service → OpenCode runtime: runs backend
- User → Model Hub: configures sources (evidence: `README.md`)
- Model Hub → Gateway runtime: routes requests
- Gateway runtime → Claude backend: serves models (evidence: `README.md`)
- Gateway runtime → Codex backend: serves models (evidence: `README.md`)
- Gateway runtime → OpenCode runtime: serves models (evidence: `README.md`)
- User → Agent Harness: schedules work (evidence: `README.md`)
- Agent Harness → Messaging platforms: delivers notices (evidence: `README.md`)
- Agent service → Show Pages: builds pages (evidence: `README.md`)
- Session services → Agent catalog: binds agents (evidence: `storage/sessions_service.py`)
- Configuration → Local data paths: uses data paths (evidence: `config/v2_config.py`)
- Local database → Local data paths: stores local state (evidence: `storage/db.py`)
