777genius/agent-teams-ai

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.