How nihalmore07/claude_agent_teams_ui works
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: App.tsx Renderer app · team/index.ts Team services · handlers.ts IPC + HTTP · main/index.ts Electron shell
Components 20
Electron app
Main desktop product and UI shell
- Electron shell · Bootstraps the desktop app and wires main, preload, and renderer boundaries
src/main/index.ts - IPC + HTTP · Privileged trust boundary for renderer requests and local API access
src/main/ipc/handlers.ts - Team services · Core team, task, message, review, and provisioning logic
src/main/services/team/index.ts - Logs pipeline · Parses transcripts and builds exact, streamed, and activity views
src/main/services/team/taskLogs/stream/BoardTaskLogStreamService.ts - Runtime layer · Detects providers, builds runtime env, and manages CLI readiness
src/main/services/runtime/ProviderConnectionService.ts - Workers · Offloads filesystem-heavy parsing, scanning, and change computation
src/main/workers/team-data-worker.ts - Preload bridge · Narrow renderer access to IPC and feature bridges
src/preload/index.ts - Renderer app · React dashboard for teams, tasks, logs, review, editor, and settings
src/renderer/App.tsx - Shared contracts · 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 · Team detail, kanban, messages, review, members, tasks, and logs screens
src/renderer/components/team/TeamDetailView.tsx - Team graph · Adapts team/runtime/task state into an interactive graph view
src/features/agent-graph/renderer/ui/TeamGraphTab.tsx - Recent projects · Discovers and presents recent project targets for the dashboard
src/features/recent-projects/main/index.ts - Provider mgmt · Manages Codex, Anthropic, and runtime-provider readiness and settings
src/features/runtime-provider-management/main/index.ts - Codex account · Reads Codex account artifacts and presents launch readiness
src/features/codex-account/main/index.ts - Work sync · Ingests runtime turn-settled events and dispatches nudges and diagnostics
src/features/member-work-sync/main/index.ts - Tmux installer · 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 · 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 · Exposes controller-backed tools over MCP transport
mcp-server/src/index.ts - Controller core · Lower-level controller for tasks, messages, review, runtime, and cross-team rules
agent-teams-controller/src/index.js - Landing site · Separate Nuxt-based marketing and documentation app
landing/app.vue
Connections 26
- 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