# nihalmore07/claude_agent_teams_ui architecture

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

- Interactive diagram: https://gitdiagram.com/nihalmore07/claude_agent_teams_ui
- Repository: https://github.com/nihalmore07/claude_agent_teams_ui

## Overview

1. **What this repo is**
   - This is a desktop orchestration platform for AI agent teams, built primarily as an **Electron app**. The product lets users create teams, launch runtimes, manage tasks on a kanban board, inspect logs/diffs, and coordinate agents across Claude, Codex, OpenCode, and other providers.

2. **Top-level process model**
   - The core app is split into the usual Electron boundaries:
     - **Main process**: owns filesystem access, process spawning, runtime detection, team orchestration, local HTTP, and IPC handlers.
     - **Preload**: exposes narrow bridges to the renderer.
     - **Renderer**: React UI for dashboard, teams, tasks, logs, review, editor, and settings.
   - The renderer never talks directly to local files or spawned runtimes; it goes through preload/IPC or the app’s local HTTP API.

3. **Primary domain: team orchestration**
   - Most of the product logic lives under `src/main/services/team` and the corresponding UI in `src/renderer/components/team`.
   - This subsystem manages:
     - team creation/provisioning
     - member runtime launch and liveness
     - task creation, assignment, comments, attachments, and inbox messaging
     - kanban state and task progress
     - review workflows and approvals
     - cross-team messaging
     - stall detection and recovery
   - It is the center of the app’s data model and is the main source for the team dashboard screens.

4. **Local state and filesystem-backed data**
   - The app is intentionally local-first. It reads from and writes to:
     - project roots on disk
     - app-owned state directories
     - local runtime/session state under `~/.claude/`
     - team inboxes, ledgers, caches, journals, and manifests
   - Persistence is mostly file-based JSON/JSONL plus blob stores and lock files. There are explicit stores for tasks, messages, processes, reviews, launch state, and runtime manifests.

5. **Runtime/provider management**
   - A large set of services and features handles provider detection and configuration:
     - `src/main/services/runtime`
     - `src/features/runtime-provider-management`
     - `src/features/codex-account`
     - `src/features/codex-model-catalog`
     - `src/features/codex-runtime-profile`
     - `src/features/anthropic-runtime-profile`
     - `src/features/tmux-installer`
   - This layer is responsible for discovering installed CLIs/runtimes, checking capabilities, building environment variables, handling auth/session state, and presenting readiness/status in the UI.

6. **Task logs, session parsing, and analysis pipeline**
   - The app has a substantial log-ingestion pipeline in `src/main/services/team/taskLogs`, `src/main/services/parsing`, and `src/main/services/analysis`.
   - It converts raw runtime transcripts and tool output into structured views:
     - exact task logs
     - streamed task logs
     - activity timelines
     - semantic breakdowns of steps, tools, subprocesses, and messages
   - The renderer then consumes these projections to display task detail, execution history, and token/context analysis.

7. **Review and code-change flow**
   - Code review is treated as a first-class workflow, not just a diff viewer.
   - Main-process services compute task changes, ledgers, review decisions, and conflict detection; the renderer presents accept/reject/comment flows and file-level diffs.
   - The review path is tightly bound to task state: changes are linked back to tasks, and the UI can scope review by task or file.

8. **Message and inbox architecture**
   - Agent-to-agent and user-to-agent communication is modeled as inbox/message stores plus protocol adapters.
   - The main process owns the canonical message feeds, inbox writers/readers, cross-team outbox, and message normalization.
   - The renderer surfaces this through team message panels, task comments, unread badges, and transient handoff UI.

9. **Cross-team coordination and task dependency controls**
   - The `crossTeam` and `cascadeGuard` modules implement boundaries around messaging and dependency propagation between teams.
   - Kanban/task logic includes blocked-by relationships, ordering guarantees, and guardrails that prevent unsafe cascades.
   - These rules matter architecturally because they shape how tasks move and how messages are routed.

10. **Feature-sliced architecture inside the app**
   - Under `src/features`, several features are organized as clean slices with `core`, `main`, `preload`, and `renderer` layers.
   - Notable feature slices:
     - `agent-graph` for the visual team graph
     - `recent-projects` for dashboard project discovery
     - `member-work-sync` for runtime turn-settled ingestion and nudging
     - `tmux-installer` for environment setup
     - `runtime-provider-management` for provider config
   - These slices have explicit contracts, IPC bridges, presenters, and infrastructure adapters, making them easier to diagram as isolated subsystems.

11. **Visualization subsystem**
   - The `packages/agent-graph` package is a reusable graph-rendering engine.
   - It contains layout, simulation, canvas drawing, overlays, interaction hooks, and data/event ports.
   - The app-specific adapter in `src/features/agent-graph` maps team/runtime/task data into renderable graph nodes and activity lanes for the team visualization tab.

12. **HTTP and IPC surface**
   - The main process exposes both:
     - **IPC handlers** for renderer requests
     - a **local HTTP server** for some API-style access paths
   - These surfaces are validated at the boundary, especially for IDs, payload shapes, and filesystem paths.
   - This is the primary trust boundary between UI and privileged local operations.

13. **Workers and background execution**
   - Heavy or long-running work is offloaded to worker processes such as `team-data-worker`, `team-fs-worker`, and `task-change-worker`.
   - The design separates UI responsiveness from scanning, parsing, and filesystem-heavy operations.
   - There is also a general service/infrastructure layer for file watchers, event-loop monitoring, SSH, PTY/terminal integration, and updater logic.

14. **Standalone ecosystem pieces**
   - `mcp-server` is a separate TypeScript package that exposes tools over MCP, backed by the controller layer and tool catalogs.
   - `agent-teams-controller` appears to be a lower-level controller package used by the MCP server and/or runtime integrations.
   - The `landing` app is a separate Nuxt-based marketing/documentation site, not part of the runtime product loop.

15. **Build, release, and verification**
   - The repo is a monorepo managed with pnpm, Bun lockfiles, and Electron/Vite tooling.
   - CI, release, and landing workflows are in GitHub Actions.
   - Tests are extensive and cover main-process services, renderer components, feature slices, IPC, HTTP, and end-to-end runtime paths, which reflects the repo’s strongly boundary-driven architecture.

16. **How to draw the architecture**
   - A good diagram should center on:
     - Electron renderer UI
     - preload/IPC boundary
     - main-process orchestration services
     - filesystem-backed stores and runtime/session data
     - external CLIs/providers
     - worker processes for parsing/scanning
     - optional local HTTP/MCP surfaces
   - The most important data flow is: **runtime/session files and provider state in the local machine → main-process scanners/adapters → projections/stores → renderer UI**, with user actions flowing back through IPC to mutate team state, tasks, reviews, and runtime control.

Main entry points: [`src/renderer/App.tsx`](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/renderer/App.tsx) (Renderer app), [`src/main/services/team/index.ts`](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/services/team/index.ts) (Team services), [`src/main/ipc/handlers.ts`](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/ipc/handlers.ts) (IPC + HTTP), [`src/main/index.ts`](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/index.ts) (Electron shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Electron app"]
  node_electron_shell["Electron shell<br/>app-shell<br/>[index.ts]"]
  node_main_ipc_http["IPC + HTTP<br/>boundary<br/>[handlers.ts]"]
  node_team_services["Team services<br/>orchestration<br/>[index.ts]"]
  node_task_logs_pipeline["Logs pipeline<br/>ingestion"]
  node_runtime_services["Runtime layer<br/>provider/runtime"]
  node_background_workers["Workers<br/>background jobs"]
  node_preload_bridge["Preload bridge<br/>ipc bridge<br/>[index.ts]"]
  node_renderer_app["Renderer app<br/>react-ui<br/>[App.tsx]"]
  node_shared_contracts["Shared contracts<br/>types/utils<br/>[index.ts]"]
end

subgraph group_features["Feature slices"]
  node_team_ui["Team UI<br/>team workspace UI<br/>[TeamDetailView.tsx]"]
  node_graph_feature["Team graph<br/>visualization feature<br/>[TeamGraphTab.tsx]"]
  node_recent_projects["Recent projects<br/>dashboard feature<br/>[index.ts]"]
  node_provider_mgmt["Provider mgmt<br/>runtime feature<br/>[index.ts]"]
  node_codex_account["Codex account<br/>auth feature<br/>[index.ts]"]
  node_member_work_sync["Work sync<br/>sync feature<br/>[index.ts]"]
  node_tmux_installer["Tmux installer<br/>environment feature<br/>[index.ts]"]
end

subgraph group_packages["Shared packages"]
  node_agent_graph_pkg["Graph engine<br/>canvas library<br/>[index.ts]"]
end

subgraph group_standalone["Standalone apps"]
  node_mcp_server["MCP server<br/>tool server<br/>[index.ts]"]
  node_controller_pkg["Controller core<br/>tooling backend<br/>[index.js]"]
  node_landing_site["Landing site<br/>marketing site<br/>[app.vue]"]
end

node_electron_shell -->|"registers"| node_main_ipc_http
node_electron_shell -->|"loads"| node_preload_bridge
node_electron_shell -->|"hosts"| node_renderer_app
node_main_ipc_http -->|"commands"| node_team_services
node_main_ipc_http -->|"provider ops"| node_runtime_services
node_main_ipc_http -->|"project API"| node_recent_projects
node_main_ipc_http -->|"settings API"| node_provider_mgmt
node_preload_bridge -->|"bridges"| node_renderer_app
node_renderer_app -->|"composes"| node_team_ui
node_renderer_app -->|"renders"| node_graph_feature
node_renderer_app -->|"shows"| node_recent_projects
node_renderer_app -->|"shows"| node_provider_mgmt
node_renderer_app -->|"shows"| node_tmux_installer
node_team_ui -->|"reads/writes"| node_team_services
node_team_services -->|"feeds"| node_task_logs_pipeline
node_task_logs_pipeline -->|"offloads"| node_background_workers
node_team_services -->|"scans"| node_background_workers
node_team_services -->|"shares"| node_shared_contracts
node_runtime_services -->|"checks"| node_codex_account
node_provider_mgmt -->|"integrates"| node_codex_account
node_member_work_sync -->|"nudges"| node_team_services
node_member_work_sync -->|"observes"| node_runtime_services
node_graph_feature -->|"uses"| node_agent_graph_pkg
node_mcp_server -->|"delegates"| node_controller_pkg
node_team_services -.->|"exports"| node_controller_pkg
node_landing_site -.->|"separate from"| node_renderer_app

click node_electron_shell "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/index.ts"
click node_main_ipc_http "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/ipc/handlers.ts"
click node_team_services "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/services/team/index.ts"
click node_task_logs_pipeline "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/services/team/taskLogs/stream/BoardTaskLogStreamService.ts"
click node_runtime_services "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/services/runtime/ProviderConnectionService.ts"
click node_background_workers "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/workers/team-data-worker.ts"
click node_preload_bridge "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/preload/index.ts"
click node_renderer_app "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/renderer/App.tsx"
click node_team_ui "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/renderer/components/team/TeamDetailView.tsx"
click node_graph_feature "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/agent-graph/renderer/ui/TeamGraphTab.tsx"
click node_recent_projects "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/recent-projects/main/index.ts"
click node_provider_mgmt "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/runtime-provider-management/main/index.ts"
click node_codex_account "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/codex-account/main/index.ts"
click node_member_work_sync "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/member-work-sync/main/index.ts"
click node_tmux_installer "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/tmux-installer/main/index.ts"
click node_shared_contracts "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/shared/types/index.ts"
click node_agent_graph_pkg "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/packages/agent-graph/src/index.ts"
click node_mcp_server "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/mcp-server/src/index.ts"
click node_controller_pkg "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/agent-teams-controller/src/index.js"
click node_landing_site "https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/landing/app.vue"

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_shell,node_main_ipc_http,node_team_services,node_task_logs_pipeline,node_runtime_services,node_background_workers,node_preload_bridge,node_renderer_app,node_shared_contracts toneBlue
class node_team_ui,node_graph_feature,node_recent_projects,node_provider_mgmt,node_codex_account,node_member_work_sync,node_tmux_installer toneAmber
class node_agent_graph_pkg toneMint
class node_mcp_server,node_controller_pkg,node_landing_site toneRose
```

## Components

### Electron app

Main desktop product and UI shell

- [Electron shell](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/index.ts): app-shell · Bootstraps the desktop app and wires main, preload, and renderer boundaries · `src/main/index.ts`
- [IPC + HTTP](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/ipc/handlers.ts): boundary · Privileged trust boundary for renderer requests and local API access · `src/main/ipc/handlers.ts`
- [Team services](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/services/team/index.ts): orchestration · Core team, task, message, review, and provisioning logic · `src/main/services/team/index.ts`
- [Logs pipeline](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/services/team/taskLogs/stream/BoardTaskLogStreamService.ts): ingestion · Parses transcripts and builds exact, streamed, and activity views · `src/main/services/team/taskLogs/stream/BoardTaskLogStreamService.ts`
- [Runtime layer](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/services/runtime/ProviderConnectionService.ts): provider/runtime · Detects providers, builds runtime env, and manages CLI readiness · `src/main/services/runtime/ProviderConnectionService.ts`
- [Workers](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/main/workers/team-data-worker.ts): background jobs · Offloads filesystem-heavy parsing, scanning, and change computation · `src/main/workers/team-data-worker.ts`
- [Preload bridge](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/preload/index.ts): ipc bridge · Narrow renderer access to IPC and feature bridges · `src/preload/index.ts`
- [Renderer app](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/renderer/App.tsx): react-ui · React dashboard for teams, tasks, logs, review, editor, and settings · `src/renderer/App.tsx`
- [Shared contracts](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/shared/types/index.ts): types/utils · Cross-layer types, constants, and pure utilities shared by main and renderer · `src/shared/types/index.ts`

### Feature slices

Feature-organized subsystems with contracts, main, preload, and renderer layers

- [Team UI](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/renderer/components/team/TeamDetailView.tsx): team workspace UI · Team detail, kanban, messages, review, members, tasks, and logs screens · `src/renderer/components/team/TeamDetailView.tsx`
- [Team graph](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/agent-graph/renderer/ui/TeamGraphTab.tsx): visualization feature · Adapts team/runtime/task state into an interactive graph view · `src/features/agent-graph/renderer/ui/TeamGraphTab.tsx`
- [Recent projects](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/recent-projects/main/index.ts): dashboard feature · Discovers and presents recent project targets for the dashboard · `src/features/recent-projects/main/index.ts`
- [Provider mgmt](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/runtime-provider-management/main/index.ts): runtime feature · Manages Codex, Anthropic, and runtime-provider readiness and settings · `src/features/runtime-provider-management/main/index.ts`
- [Codex account](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/codex-account/main/index.ts): auth feature · Reads Codex account artifacts and presents launch readiness · `src/features/codex-account/main/index.ts`
- [Work sync](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/member-work-sync/main/index.ts): sync feature · Ingests runtime turn-settled events and dispatches nudges and diagnostics · `src/features/member-work-sync/main/index.ts`
- [Tmux installer](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/src/features/tmux-installer/main/index.ts): environment feature · Detects and installs tmux across platforms and WSL paths · `src/features/tmux-installer/main/index.ts`

### Shared packages

Reusable libraries used by the app and tooling

- [Graph engine](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/packages/agent-graph/src/index.ts): canvas library · Reusable graph rendering engine with layout, canvas, hooks, and interaction ports · `packages/agent-graph/src/index.ts`

### Standalone apps

Separate runtime products in the monorepo

- [MCP server](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/mcp-server/src/index.ts): tool server · Exposes controller-backed tools over MCP transport · `mcp-server/src/index.ts`
- [Controller core](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/agent-teams-controller/src/index.js): tooling backend · Lower-level controller for tasks, messages, review, runtime, and cross-team rules · `agent-teams-controller/src/index.js`
- [Landing site](https://github.com/nihalmore07/claude_agent_teams_ui/blob/main/landing/app.vue): marketing site · Separate Nuxt-based marketing and documentation app · `landing/app.vue`

## Connections

- Electron shell → IPC + HTTP: registers · Main process exposes privileged request surfaces
- Electron shell → Preload bridge: loads · Electron loads preload bridges into renderer windows
- Electron shell → Renderer app: hosts · Desktop window renders the React application
- IPC + HTTP → Team services: commands · IPC and HTTP mutate or query team state
- IPC + HTTP → Runtime layer: provider ops · Boundary routes provider and runtime requests
- IPC + HTTP → Recent projects: project API · Boundary serves project discovery requests
- IPC + HTTP → Provider mgmt: settings API · Boundary serves runtime-provider management requests
- Preload bridge → Renderer app: bridges · Renderer accesses privileged APIs through preload
- Renderer app → Team UI: composes · Main UI is made of team-centric workspace screens
- Renderer app → Team graph: renders · Renderer includes the interactive team graph tab
- Renderer app → Recent projects: shows · Dashboard surfaces recent projects and open targets
- Renderer app → Provider mgmt: shows · Settings surface provider readiness and configuration
- Renderer app → Tmux installer: shows · UI presents installation and readiness flows for tmux
- Team UI → Team services: reads/writes · Team screens drive orchestration, tasks, messages, and review
- Team services → Logs pipeline: feeds · Team orchestration produces transcripts and task execution data
- Logs pipeline → Workers: offloads · Heavy parsing and scanning run in worker processes
- Team services → Workers: scans · Filesystem and change computation are delegated to workers
- Team services → Shared contracts: shares · Domain state uses shared types and constants
- Runtime layer → Codex account: checks · Runtime readiness depends on account and auth state
- Provider mgmt → Codex account: integrates · Provider management merges with Codex account state
- Work sync → Team services: nudges · Turn-settled ingestion feeds team inboxes and task state
- Work sync → Runtime layer: observes · Sync reacts to runtime events and provider-specific payloads
- Team graph → Graph engine: uses · App-specific graph view is built on reusable graph engine
- MCP server → Controller core: delegates · MCP tools are backed by the controller layer
- Team services → Controller core: exports · Controller concepts mirror the core team/task/message model
- Landing site → Renderer app: separate from · Marketing site is a standalone app, not part of runtime loop
