## The Problem Developers juggling several AI‑driven code‑generation tools often lose context when switching between terminals, CI pipelines, and ad‑hoc scripts. Keeping each agent’s workspace, history, and configuration synchronized while still being able to run batch jobs or remote‑control them is a repetitive, error‑prone task.

## What This Does Maestro provides a single Electron‑based desktop front‑end plus a headless CLI that orchestrates any number of AI agents (Claude, Codex, OpenCode, etc.).

  • The CLI entry point lives in src/cli/index.ts and dispatches commands defined under src/main/agents/, src/main/app‑lifecycle/, and src/main/debug‑package/.
  • The UI is built with React (src/renderer/…) and boots from src/web/App.tsx (referenced by the Vite config vite.config.web.mts).
  • Core runtime logic is in src/main/index.ts, which wires the IPC layer (src/main/ipc/handlers/), the process manager (src/main/process‑manager/), and the storage subsystem (src/main/storage/).

## How It Is Wired

  1. Startup – The Electron main process loads src/main/index.ts. It creates the IPC channel, instantiates ProcessManager (src/main/process‑manager/ProcessManager.ts) and registers all handlers via registerAllHandlers (src/main/ipc/handlers/index.ts).
  2. Command execution – A CLI call (e.g., maestro-cli run‑playbook) hits src/cli/index.ts, which forwards to the appropriate service in src/main/services/. The most‑called service functions are set (79 callers) and execFileNoThrow (17 callers).
  3. Agent work – createIpcMethod (13 callers) builds the RPC bridge that ultimately invokes agent runtimes in separate PTY processes (ProcessManager.spawn). Those processes perform file I/O (24 distinct calls) and occasional network requests (3 calls).
  4. State updates – The shared logger (src/main/utils/logger.ts) is a hub (107 inbound imports) that writes to the log file and is used by almost every subsystem. The type hub src/renderer/types/index.ts is the largest import target (434 modules) and participates in a circular dependency with LayerStackContext and hooks/index.
  5. Export to UI – Renderer components consume the LayerStackContext (100 imports) and hook library (src/renderer/hooks/index.ts). The UI entry src/web/App.tsx ultimately renders src/renderer/App which imports 50 other modules, giving it an instability score of 0.98.

External effects – The code reads/writes the local file system (24 functions), makes three outbound HTTP calls (e.g., for remote tunneling), and interacts with a local SQLite‑style DB (9 functions). No model inference code is embedded; a single function calls an external inference service.

## How To Use It

# 1. Clone the repo
git clone https://github.com/moses-y/Maestro
cd Maestro

# 2. Install dependencies (npm is the package manager)
npm ci

# 3. Build the UI and preload scripts
npm run build   # defined in package.json, uses scripts/build‑cli.mjs & scripts/build‑preload.mjs

# 4. Start the desktop app
npm start       # launches Electron, which runs src/main/index.ts

# 5. Or use the CLI directly
npx maestro-cli list‑agents
npx maestro-cli run‑playbook path/to/playbook.md --jsonl

Configuration files such as docs/configuration.md and environment variables referenced in src/main/web‑server/types.ts (e.g., API keys for Claude/OpenAI) must be present before running agents.

## Real‑World Use A team can define a markdown playbook that lists build, test, and deployment steps. Running npx maestro-cli run‑playbook my‑release.yml spawns separate PTY processes for each agent, stores each step’s output in the local SQLite store, and streams progress to the UI. A mobile device can monitor the run via the built‑in web server (src/main/web‑server/) and abort or retry steps without leaving the IDE.

## Code Health & Issues

  • High – Pin third‑party GitHub Actions to a commit SHA (.github/workflows/*).
  • High – CI never runs the test suite (.github/workflows/*).
  • High – continue‑on‑error masks failures in release.yml.
  • High – Release workflow pushes directly to the default branch.
  • Medium – No Dependabot/Renovate configured.
  • Medium – No dependency‑vulnerability scan in CI.
  • Medium – Generated build output is committed (build/).
  • Medium – Checkout step keeps credentials; should set persist‑credentials: false.
  • Low – Workflow jobs lack explicit timeout‑minutes.

The static analysis also flagged eight import cycles, several oversized hub modules, and deep nesting (up to 9 levels) that increase cognitive load.

## The Bottom Line Maestro delivers a functional, extensible orchestration layer for multiple AI agents with both GUI and CLI interfaces. The codebase is large and heavily inter‑dependent; the central logger and type index act as high‑impact hubs, and import cycles may hinder future refactoring. Immediate attention should focus on tightening CI (pinning actions, running tests) and reducing the size of hub modules to improve maintainability. Suitable for teams that need an integrated desktop tool for AI‑driven automation and are comfortable maintaining a TypeScript/Electron stack.