# 777genius/agent-teams-ai architecture

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

- Interactive diagram: https://gitdiagram.com/777genius/agent-teams-ai
- Repository: https://github.com/777genius/agent-teams-ai

## Overview

1. **System shape**
   - This is a monorepo centered on a **desktop Electron app** for orchestrating AI agent teams.
   - The repo also contains a separate **MCP server**, a **landing/docs site**, a shared visualization package, and a few helper/controller packages.

2. **Primary runtime boundary: Electron**
   - The main app is split into the standard Electron layers:
     - `src/main`: privileged process for file system, process launching, HTTP, IPC, persistence, and provider/runtime orchestration.
     - `src/preload`: narrow bridge layer that exposes selected APIs to the UI.
     - `src/renderer`: React UI, state management, and user workflows.
   - This boundary is important because the renderer never talks directly to local files, runtimes, or OS processes.

3. **Feature-based modular architecture**
   - `src/features/*` follows a consistent feature pattern with `contracts`, `core`, `main`, `preload`, and `renderer` folders.
   - The `core` layer holds domain/application logic; `main` binds to local infrastructure; `preload` exposes a safe bridge; `renderer` renders UI and invokes the feature through typed contracts.
   - Notable feature modules include agent attachments, agent graph, Codex account/model/runtime handling, member log streaming, member work sync, recent projects, runtime provider management, team runtime lanes, and tmux installation.

4. **Team orchestration is the heart of the app**
   - Most of the business logic in `src/main/services/team` manages:
     - team creation and provisioning
     - member lifecycle and worktrees
     - task boards, task changes, comments, and inbox messages
     - cross-team messaging and handoffs
     - review workflows and approval flows
     - live process tracking and task log aggregation
   - This layer is the main coordination engine that ties provider runtimes, local project state, and UI together.

5. **Provider/runtime integration is local and adapter-driven**
   - The app auto-detects and manages multiple agent runtimes/providers: **Claude, Codex, and OpenCode**.
   - Runtime integration is handled by services and adapters such as:
     - provider connection / readiness / auth helpers
     - CLI environment and launch configuration builders
     - Codex app-server clients and model catalog queries
     - OpenCode bridge, delivery watchdog, and state-managing adapters
   - The architecture assumes providers are accessed through local CLI/app-server/runtime channels, not through a centralized backend.

6. **Persistent state is file-backed and local-first**
   - The app reads local Claude/runtime/session data under `~/.claude/` and project-owned state under the selected workspace.
   - Persistence uses JSON stores, journals, caches, atomic writes, and file locks rather than a database server.
   - Team/task state, task-change ledgers, inboxes, runtime manifests, and review decisions are stored on disk, with helpers for recovery and tamper-safe updates.

7. **Data discovery and analysis pipeline**
   - `src/main/services/discovery`, `parsing`, and `analysis` turn raw local artifacts into searchable project/session/task data.
   - This includes project scanning, session indexing/search, transcript parsing, tool-result extraction, semantic grouping, and task/session linking.
   - Worker processes in `src/main/workers` are used for heavier or more isolated work such as task-change and team-data processing.

8. **Task logs, review, and diff views form a dedicated subsystem**
   - The repo has a rich pipeline for task-specific logs:
     - exact logs
     - streaming logs
     - historical/fallback transcript sources
     - log attribution and candidate selection
     - activity summaries and preview extraction
   - Review is a first-class flow: the UI can show per-task diffs and supports accept/reject/comment-style actions, with main-process services computing change sets and review decisions.

9. **UI is a large React shell over store slices**
   - `src/renderer` is organized into feature-heavy UI components, Zustand store slices, and many hooks.
   - Major visible areas include:
     - dashboard and recent projects
     - team list/detail views
     - kanban board and task detail
     - session/chat history and execution logs
     - review/diff views
     - editor, settings, extensions, notifications, schedules, and terminal panes
   - The renderer consumes data from IPC/HTTP bridges and focuses on presentation, navigation, and user actions.

10. **Visualization is separated into a reusable graph package**
   - `packages/agent-graph` is a standalone visualization engine for rendering team/task/process graphs.
   - It has its own layout, canvas rendering, interaction hooks, and data/event ports.
   - The app reuses this for team graph-like UI surfaces, keeping graph rendering concerns isolated from the main React screens.

11. **IPC and local HTTP are the main integration surfaces**
   - `src/main/ipc` exposes most app capabilities to the renderer through typed channel handlers.
   - `src/main/http` provides local HTTP endpoints for certain integrations and external access patterns.
   - Security boundaries are explicit: IDs, paths, and payload shapes are validated at the boundary, and write operations are constrained to the selected project root.

12. **MCP/server integration is a separate tool-facing boundary**
   - `mcp-server` exposes the controller functionality as MCP tools over stdio, with tool groups for teams, tasks, runtime, review, messages, work sync, kanban, process, and cross-team operations.
   - This makes the app’s orchestration layer available to external agents/tools without coupling them to the Electron UI.

13. **Landing/docs are intentionally decoupled**
   - `landing/` is a separate Nuxt-based marketing/documentation site with i18n, SEO routes, downloads, and release content.
   - It is not part of the runtime orchestration path; it supports distribution and product discovery.

14. **Build and release shape the deployment model**
   - The repo uses a workspace setup with Electron/Vite for the app, Vitest for tests, and CI/release workflows for packaging.
   - Distribution targets desktop installers and AppImage/deb/rpm/pacman artifacts, reinforcing that the primary runtime is a locally installed desktop application.

Main entry points: [`src/main`](https://github.com/777genius/agent-teams-ai/tree/main/src/main) (Main process), [`src/main/services/team`](https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/team) (Team engine), [`src/renderer`](https://github.com/777genius/agent-teams-ai/tree/main/src/renderer) (Renderer shell), [`src/main/services/runtime`](https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/runtime) (Runtime adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_src_shared["Shared core<br/>shared types/utils"]
end

subgraph group_electron["Electron App"]
  node_src_main["Main process<br/>Electron main"]
  node_src_preload["Preload bridge<br/>Electron preload"]
  node_src_renderer["Renderer shell<br/>React UI"]
  node_ipc_http["IPC and HTTP<br/>integration boundary"]
end

subgraph group_features["Feature Modules"]
  node_feature_mods["Feature modules<br/>layered features"]
end

subgraph group_services["Main Services"]
  node_team_services["Team engine<br/>orchestration services"]
  node_runtime_services["Runtime adapters<br/>provider integration"]
  node_discover_analysis["Discovery pipeline<br/>scan/parse/analyze"]
  node_tasklogs_pipeline["Task log pipeline<br/>logs/review pipeline"]
  node_persistence_services["Local persistence<br/>file-backed state"]
end

subgraph group_ui["Renderer UI"]
end

subgraph group_platform["External Surfaces"]
  node_agent_graph_pkg["Graph package<br/>visualization engine"]
  node_mcp_server["MCP server<br/>tool server"]
  node_agent_controller["Controller pkg<br/>control library"]
  node_landing_site["Landing/docs<br/>Nuxt site"]
end

subgraph group_feature_mods["Subsystem Features"]
  node_recent_projects["Recent projects<br/>feature"]
  node_runtime_mgmt["Runtime manager<br/>feature"]
  node_member_log_stream["Log streaming<br/>feature"]
  node_member_work_sync["Work sync<br/>feature"]
  node_tmux_installer["Tmux installer<br/>feature"]
  node_agent_attachments["Attachments<br/>feature"]
end

node_src_renderer -->|"safe API access"| node_src_preload
node_src_preload -->|"IPC bridge"| node_src_main
node_src_renderer -->|"UI requests"| node_ipc_http
node_ipc_http -->|"dispatches"| node_src_main
node_src_main -->|"orchestrates"| node_team_services
node_src_main -->|"adapts providers"| node_runtime_services
node_src_main -->|"indexes data"| node_discover_analysis
node_src_main -->|"builds logs"| node_tasklogs_pipeline
node_src_main -->|"persists state"| node_persistence_services
node_team_services -->|"uses runtimes"| node_runtime_services
node_team_services -->|"feeds review"| node_tasklogs_pipeline
node_team_services -->|"stores ledgers"| node_persistence_services
node_discover_analysis -->|"indexes cache"| node_persistence_services
node_runtime_services -->|"uses contracts"| node_src_shared
node_feature_mods -->|"binds main"| node_src_main
node_feature_mods -->|"exposes bridge"| node_src_preload
node_feature_mods -->|"renders UI"| node_src_renderer
node_recent_projects -->|"dashboard surface"| node_src_renderer
node_runtime_mgmt -->|"controls providers"| node_runtime_services
node_member_log_stream -->|"streams output"| node_tasklogs_pipeline
node_member_work_sync -->|"syncs work"| node_team_services
node_tmux_installer -->|"checks tools"| node_runtime_services
node_agent_attachments -->|"supports work"| node_team_services
node_agent_graph_pkg -->|"shared viz"| node_src_renderer
node_mcp_server -->|"wraps"| node_agent_controller
node_mcp_server -->|"tool access"| node_team_services

click node_src_main "https://github.com/777genius/agent-teams-ai/tree/main/src/main"
click node_src_preload "https://github.com/777genius/agent-teams-ai/tree/main/src/preload"
click node_src_renderer "https://github.com/777genius/agent-teams-ai/tree/main/src/renderer"
click node_src_shared "https://github.com/777genius/agent-teams-ai/tree/main/src/shared"
click node_feature_mods "https://github.com/777genius/agent-teams-ai/tree/main/src/features"
click node_team_services "https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/team"
click node_runtime_services "https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/runtime"
click node_discover_analysis "https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/discovery"
click node_tasklogs_pipeline "https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/team/taskLogs"
click node_persistence_services "https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/infrastructure"
click node_ipc_http "https://github.com/777genius/agent-teams-ai/tree/main/src/main/ipc"
click node_agent_graph_pkg "https://github.com/777genius/agent-teams-ai/tree/main/packages/agent-graph"
click node_mcp_server "https://github.com/777genius/agent-teams-ai/tree/main/mcp-server"
click node_agent_controller "https://github.com/777genius/agent-teams-ai/tree/main/agent-teams-controller"
click node_landing_site "https://github.com/777genius/agent-teams-ai/tree/main/landing"
click node_recent_projects "https://github.com/777genius/agent-teams-ai/tree/main/src/features/recent-projects"
click node_runtime_mgmt "https://github.com/777genius/agent-teams-ai/tree/main/src/features/runtime-provider-management"
click node_member_log_stream "https://github.com/777genius/agent-teams-ai/tree/main/src/features/member-log-stream"
click node_member_work_sync "https://github.com/777genius/agent-teams-ai/tree/main/src/features/member-work-sync"
click node_tmux_installer "https://github.com/777genius/agent-teams-ai/tree/main/src/features/tmux-installer"
click node_agent_attachments "https://github.com/777genius/agent-teams-ai/tree/main/src/features/agent-attachments"

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_src_shared,node_recent_projects,node_runtime_mgmt,node_member_log_stream,node_member_work_sync,node_tmux_installer,node_agent_attachments toneBlue
class node_src_main,node_src_preload,node_src_renderer,node_ipc_http toneAmber
class node_feature_mods toneMint
class node_team_services,node_runtime_services,node_discover_analysis,node_tasklogs_pipeline,node_persistence_services toneRose
class node_agent_graph_pkg,node_mcp_server,node_agent_controller,node_landing_site toneTeal
```

## Components

### Monorepo

Desktop app, controller surface, shared packages, and docs site.

- [Shared core](https://github.com/777genius/agent-teams-ai/tree/main/src/shared): shared types/utils · Common contracts, constants, and utilities used across runtimes. · `src/shared`

### Electron App

Local-first desktop runtime and UI boundary.

- [Main process](https://github.com/777genius/agent-teams-ai/tree/main/src/main): Electron main · Privileged process handling IPC, HTTP, local filesystem, persistence, and orchestration. · `src/main`
- [Preload bridge](https://github.com/777genius/agent-teams-ai/tree/main/src/preload): Electron preload · Narrow bridge exposing selected APIs from main to the renderer. · `src/preload`
- [Renderer shell](https://github.com/777genius/agent-teams-ai/tree/main/src/renderer): React UI · React application for dashboards, teams, tasks, review, and settings. · `src/renderer`
- [IPC and HTTP](https://github.com/777genius/agent-teams-ai/tree/main/src/main/ipc): integration boundary · Typed renderer-facing IPC handlers and local HTTP endpoints. · `src/main/ipc`

### Feature Modules

Typed, layered features shared across main, preload, and renderer.

- [Feature modules](https://github.com/777genius/agent-teams-ai/tree/main/src/features): layered features · Feature packages with contracts, core, main, preload, and renderer boundaries. · `src/features`

### Main Services

Core orchestration, discovery, parsing, runtime, and persistence services.

- [Team engine](https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/team): orchestration services · Main coordination engine for team creation, members, tasks, inbox, reviews, and live process tracking. · `src/main/services/team`
- [Runtime adapters](https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/runtime): provider integration · Local adapter layer for Claude, Codex, and OpenCode readiness, launch, and environment setup. · `src/main/services/runtime`
- [Discovery pipeline](https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/discovery): scan/parse/analyze · Scans local artifacts and turns them into searchable project, session, and task data. · `src/main/services/discovery`
- [Task log pipeline](https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/team/taskLogs): logs/review pipeline · Exact, streaming, and historical task log sourcing plus attribution and diff/review support. · `src/main/services/team/taskLogs`
- [Local persistence](https://github.com/777genius/agent-teams-ai/tree/main/src/main/services/infrastructure): file-backed state · JSON stores, journals, caches, locks, and atomic writes on disk. · `src/main/services/infrastructure`

### External Surfaces

MCP tools, reusable graph package, and landing/docs site.

- [Graph package](https://github.com/777genius/agent-teams-ai/tree/main/packages/agent-graph): visualization engine · Reusable canvas/layout/interaction engine for team and task graph surfaces. · `packages/agent-graph`
- [MCP server](https://github.com/777genius/agent-teams-ai/tree/main/mcp-server): tool server · StdIO MCP tool boundary exposing team, task, runtime, review, and work-sync operations. · `mcp-server`
- [Controller pkg](https://github.com/777genius/agent-teams-ai/tree/main/agent-teams-controller): control library · Shared controller logic and internal stores used by the MCP server. · `agent-teams-controller`
- [Landing/docs](https://github.com/777genius/agent-teams-ai/tree/main/landing): Nuxt site · Decoupled marketing and documentation site with product docs and release content. · `landing`

### Subsystem Features

Architecturally central feature packages with their own contracts and runtime bridges.

- [Recent projects](https://github.com/777genius/agent-teams-ai/tree/main/src/features/recent-projects): feature · Dashboard subsystem for discovering, merging, and opening recent projects. · `src/features/recent-projects`
- [Runtime manager](https://github.com/777genius/agent-teams-ai/tree/main/src/features/runtime-provider-management): feature · UI and IPC for provider/runtime management and model selection. · `src/features/runtime-provider-management`
- [Log streaming](https://github.com/777genius/agent-teams-ai/tree/main/src/features/member-log-stream): feature · Member log previews and streams across Claude, Codex, and OpenCode. · `src/features/member-log-stream`
- [Work sync](https://github.com/777genius/agent-teams-ai/tree/main/src/features/member-work-sync): feature · Turn-settled ingestion, nudging, and reconciliation for member work state. · `src/features/member-work-sync`
- [Tmux installer](https://github.com/777genius/agent-teams-ai/tree/main/src/features/tmux-installer): feature · Cross-platform tmux detection and installation flow with runtime adapters. · `src/features/tmux-installer`
- [Attachments](https://github.com/777genius/agent-teams-ai/tree/main/src/features/agent-attachments): feature · Agent-facing attachment handling and optimization across providers. · `src/features/agent-attachments`

## Connections

- Renderer shell → Preload bridge: safe API access · Renderer invokes only exposed bridges, not OS or filesystem APIs.
- Preload bridge → Main process: IPC bridge · Preload forwards typed calls into privileged handlers.
- Renderer shell → IPC and HTTP: UI requests · Renderer uses IPC and local HTTP through typed clients.
- IPC and HTTP → Main process: dispatches · IPC and HTTP route requests into main-process services.
- Main process → Team engine: orchestrates · Main process delegates team lifecycle, messaging, review, and task operations.
- Main process → Runtime adapters: adapts providers · Main process manages provider readiness, auth, and launch configuration.
- Main process → Discovery pipeline: indexes data · Main process scans and analyzes local artifacts into searchable state.
- Main process → Task log pipeline: builds logs · Main process assembles exact and streaming task log views.
- Main process → Local persistence: persists state · Main process writes file-backed stores, journals, and caches.
- Team engine → Runtime adapters: uses runtimes · Team orchestration launches and supervises agent runtimes.
- Team engine → Task log pipeline: feeds review · Team orchestration relies on task log extraction for summaries and diffs.
- Team engine → Local persistence: stores ledgers · Team, inbox, review, and launch state are kept on disk.
- Discovery pipeline → Local persistence: indexes cache · Discovery uses local caches and indices for session and project search.
- Runtime adapters → Shared core: uses contracts · Provider integration shares common types, utilities, and constants.
- Feature modules → Main process: binds main · Feature packages attach main-process infrastructure and IPC handlers.
- Feature modules → Preload bridge: exposes bridge · Feature packages publish narrow preload bridges.
- Feature modules → Renderer shell: renders UI · Feature packages provide renderer hooks and views.
- Recent projects → Renderer shell: dashboard surface · Recent-projects data powers the dashboard and project launcher.
- Runtime manager → Runtime adapters: controls providers · Runtime management reflects and configures provider state.
- Log streaming → Task log pipeline: streams output · Log-stream feature consumes transcript and trace sources.
- Work sync → Team engine: syncs work · Work-sync feature feeds team state and inbox/reconciliation flows.
- Tmux installer → Runtime adapters: checks tools · Tmux installation integrates with runtime and platform readiness.
- Attachments → Team engine: supports work · Attachment handling feeds team and task workflows.
- Graph package → Renderer shell: shared viz · Reusable graph rendering is embedded in the React shell.
- MCP server → Controller pkg: wraps · MCP tools are backed by the controller library.
- MCP server → Team engine: tool access · MCP exposes team orchestration outside the Electron UI.