CLI-IPC: WebSocket bridge for provider agents to trigger Maestro UI actions

[pedramamini]

Problem

Provider agents running inside Maestro have no way to trigger UI-side actions in the desktop app. After an agent creates files, modifies the workspace, or generates auto-run documents, the user must manually refresh the file tree, open files, or configure auto-run. This creates friction in agentic workflows where the agent knows what it just changed but can't tell Maestro to reflect it.

Proposed Solution

Add a WebSocket-based IPC bridge between the CLI (maestro-cli) and the Electron app, enabling agents to issue commands like:

maestro-cli refresh-files          # Refresh the file tree panel
maestro-cli open-file <path>       # Open a file in a preview tab
maestro-cli refresh-auto-run       # Refresh the auto-run document list
maestro-cli auto-run <docs...>     # Configure and launch an auto-run
maestro-cli status                 # Check if Maestro is running
maestro-cli send <id> <msg> --tab  # Send + focus the agent's tab

Architecture

Electron starts → auto-starts web server → writes discovery file (cli-server.json)
CLI reads discovery file → connects WebSocket → sends commands
Electron shuts down → deletes discovery file

The existing Fastify + WebSocket server (src/main/web-server/) is reused. A discovery file (~/.config/maestro/cli-server.json) makes the server's random port and security token discoverable by the CLI.

Implementation Plan (4 Phases)

Full implementation documents attached as a gist with 4 phase files (20 tasks total):

CLI-IPC-01.md
CLI-IPC-02.md
CLI-IPC-03.md
CLI-IPC-04.md

Phase	Focus	Tasks
01	Server discovery file + always-on CLI server	4
02	New WebSocket message types + renderer handlers	7
03	CLI WebSocket client + new CLI commands	7
04	Auto-run configuration command + system prompt integration	6

Phase Summary

Phase 01 — Creates src/shared/cli-server-discovery.ts (following cli-activity.ts pattern), auto-starts the web server on app launch, writes/deletes the discovery file on startup/shutdown.

Phase 02 — Adds 3 new WebSocket message types (open_file_tab, refresh_file_tree, refresh_auto_run_docs) across the 5-file callback chain: messageHandlers.ts → CallbackRegistry.ts → WebServer.ts → web-server-factory.ts → preload/process.ts. Wires renderer handlers via useRemoteIntegration.ts using CustomEvent dispatch to App.tsx.

Phase 03 — Creates MaestroClient WebSocket client (src/cli/services/maestro-client.ts) with connect(), sendCommand<T>(), and withMaestroClient() helper. Adds 4 new CLI commands: open-file, refresh-files, refresh-auto-run, status. Adds --tab flag to existing send command.

Phase 04 — Adds configure_auto_run WebSocket message type with launch/save-as-playbook support. Creates auto-run CLI command for configuring and launching auto-runs from the terminal. Updates maestro-system-prompt.md so agents know these commands exist.

What This Enables

Once implemented, the system prompt tells agents about these commands. An agent that just created 5 auto-run documents can:

maestro-cli refresh-auto-run          # UI immediately shows new docs
maestro-cli auto-run doc1.md --launch # Launch the auto-run

An agent that modified workspace files can:

maestro-cli refresh-files             # File tree updates without user action
maestro-cli open-file ./new-file.ts   # Opens it for the user to see

This is a stepping stone toward the full Agent SDK integration (#340) and complements Maestro Cue (#367) event-driven automation.

Related

• Integrate Claude Agent SDK for mid-turn interaction, graceful abort, and structured streaming #340 — Claude Agent SDK integration (hooks like PostToolUse would be the native equivalent)
• feat: Maestro Cue — Event-Driven Agent Automation #367 — Maestro Cue (event-driven automation, file.changed triggers)