Dorchestrator

A visual desktop application for orchestrating multiple AI agents — powered by Claude Code, OpenAI Codex, or the built-in coding agent — with real-time collaboration, Kanban task execution, and inter-agent communication.

Features

Three Workspace Modes

• Kanban Mode - Task board for assigning work to shared agents or full swarms with background execution and review loops
• Swarm Mode - Visual graph-based multi-agent orchestration with inter-agent communication
• Mux Mode - Template-based terminal multiplexer for managing multiple agent sessions
• Toggle between modes with a single click in the header

Kanban Mode

• Five task stages: Backlog, Todo, In Progress, In Review, and Done
• Create tasks that target either a shared agent or an existing swarm
• When targeting a swarm, choose the entry agent that receives the first prompt
• Dragging a card into In Progress starts the run in the background
• Task detail modal shows run history in accordions with execution timelines or live transcripts
• Review loop supports replying to a run from In Review or marking it done
• Shared agent library with template-based creation and the same configuration panel used in Swarm mode
• Built-in Schedules view for one-time or recurring workspace commands with pause, edit, delete, and manual run controls
• Scheduled commands create spawned task cards automatically and surface their command output in In Review

Visual Agent Graph (Swarm Mode)

• Drag-and-drop interface powered by React Flow
• Real-time node connections for defining agent relationships
• Color-coded agents with customizable roles and templates
• Interactive canvas with zoom, pan, and selection controls

Mux Mode

• Template-based agent session management
• Sidebar navigation for quick template switching
• Create, edit, and delete custom templates
• Persistent template storage across sessions

Integrated Terminals

• Live PTY sessions for each agent — choose between claude CLI, codex CLI, or built-in agent per agent
• xterm.js terminals with full ANSI color support
• Auto-restart on session end
• Flexible layouts (auto, 1-col, 2-col, 3-col grid)
• Toggle views to focus on graph or terminals

Multi-CLI Support

• Claude Code (claude CLI) — Anthropic's agentic terminal with full MCP support
• Codex (codex CLI) — OpenAI's agentic coding assistant running in full-auto mode
• Built-in Agent (/coding-agent) — Integrated coding agent without external CLI dependency
• Each agent independently chooses its CLI and model
• Mix Claude, Codex, and built-in agents in the same workspace

Voice Assistant

• Offline voice recognition using Whisper.cpp
• Real-time waveform visualization while recording
• Automatic transcription to focused terminal
• Keyboard shortcut (Cmd+Shift+V / Ctrl+Shift+V)
• Cyberpunk-styled UI with neon effects

Inter-Agent Communication

• MCP-based messaging between connected agents (both Claude Code and Codex)
• TCP bridge server for reliable message routing
• Two-way communication with response capture
• Real-time streaming of agent responses
• Edge-aware tool discovery (agents only see connected peers)

Agent Configuration

• Pre-built templates: CEO, Programmer, Tester, Researcher, Custom
• Terminal type selection: Claude Code, Codex, or Built-in Agent per agent
• Model selection:
• Claude: Opus 4.6, Sonnet 4.6, Haiku 4.5
• Codex: gpt-5.1, gpt-5.2, gpt-5.3, gpt-5.4, gpt-5.5 (default)
• Built-in: Uses integrated coding agent
• System prompts for role-specific instructions
• Persistent settings across sessions
• Shared Kanban agents also appear as options when creating graph agents in Swarm mode

Workspace Management

• Folder-based workspaces for agent file access
• Launch-time workspace picker (blocks until set)
• Change workspace on-the-fly from header
• Shared working directory for all agents

Quick Start

Prerequisites

• macOS (Darwin)
• Node.js 16+
• For Claude Code agents: claude CLI installed and in PATH (get it here)
• For Codex agents: codex CLI installed and in PATH (get it here)
• For Built-in agents: Make sure to copy /coding-agent/config/agents.example.json to your-home-dir/.dorchestrator/coding-agent/config/agents.json and configure your own API provider if you need.
• Anthropic API key (for Claude Code agents)
• OpenAI API key (for Codex agents)
• ffmpeg (required for voice assistant): brew install ffmpeg

Installation

# Clone the repository
git clone <your-repo-url>
cd agent-orchestrator

# Install dependencies
npm install

# The postinstall script will automatically rebuild node-pty for Electron

Configuration

Create a .env file in the project root:

# Claude Code agents
ANTHROPIC_API_KEY=your_anthropic_api_key_here
ANTHROPIC_BASE_URL=https://api.anthropic.com  # optional
CLAUDE_PATH=/path/to/claude                   # optional, defaults to 'claude' in PATH

# Codex agents
OPENAI_API_KEY=your_openai_api_key_here       # required for Codex agents
CODEX_PATH=/path/to/codex                     # optional, defaults to 'codex' in PATH

Or configure the Anthropic key via the UI after launch (Settings button in header).

Development

# Start in development mode (hot reload)
npm run dev

This runs: - Vite dev server on http://localhost:3000 - Electron app with DevTools open

Production Build

# Build and package the app
npm run build

The packaged app will be in the dist/ directory.

Architecture

Tech Stack

• Electron - Desktop app framework
• React - UI components and state management
• React Flow - Graph visualization and interaction
• xterm.js - Terminal emulation with PTY support
• node-pty - Pseudo-terminal spawning (native addon)
• Anthropic SDK - Fallback orchestrator (not used for PTY mode)

Key Components

Main Process (src/main/index.js)

• PTY lifecycle management (spawn, resize, kill)
• Supports both claude and codex CLI per agent
• TCP bridge server for inter-agent messaging
• MCP config generation per agent
• Workspace and auth settings persistence
• Kanban task runtime orchestration, background execution, persistence, and timeline event capture
• IPC handlers for renderer communication

Kanban State (src/main/kanbanManager.js)

• Persists Kanban board state per workspace under .dorchestrator
• Stores selected sidebar view, sidebar collapse state, and task cards
• Keeps task updates in sync between background execution and the renderer

MCP Bridge (src/main/mcp-bridge.js)

• Stdio MCP server (newline-delimited JSON)
• Exposes send_message tool to connected agents (both Claude Code and Codex)
• Handles initialize, tools/list, tools/call
• Forwards messages via TCP to bridge server

Renderer Process (src/renderer/)

• App.jsx - Main layout, workspace picker, view toggles
• GraphView - React Flow canvas with agent nodes
• TerminalGrid - Multi-terminal layout manager
• TerminalPanel - Individual xterm.js terminal + PTY integration
• AgentConfigPanel - Agent settings sidebar (terminal type, model, etc.)
• KanbanWorkspace - Board lanes, shared agents, task composer, task review modal
• KanbanExecutionTimeline - Structured task execution timeline view for Kanban runs

Inter-Agent Communication Flow

CEO Terminal (PTY)
  ↓ uses MCP tool: send_message
MCP Bridge (stdio)
  ↓ TCP socket
Bridge Server (main process)
  ↓ writes to target PTY stdin (Claude Code) or spawns exec (Codex)
Target Agent Terminal (PTY)
  ↓ captures output
Bridge Server
  ↓ returns response
CEO Terminal (receives reply)

Usage

Using Kanban Mode

1. Switch to Kanban from the header
2. In Agents, create shared agents from templates or edit them with the standard agent config panel
3. In Board, create a task with a title, first prompt, and target
4. Choose either:
5. a shared Agent
6. a Swarm, plus the swarm entry agent that should receive the first prompt
7. Drag the card into In Progress to start execution
8. Open the card to inspect the run accordion, execution timeline, transcript, and final reply
9. In In Review, either send reviewer feedback to continue the task or mark it Done

Kanban Board Stages

• Backlog stores ideas that are not ready to execute yet
• Todo is the default landing stage for newly created tasks
• In Progress starts a background run when a card enters the lane
• In Review is where completed runs wait for approval or reviewer feedback
• Done contains accepted completed tasks

Shared Agents

• Kanban shared agents are workspace-level reusable agent definitions
• They can be created from the same role templates as Swarm agents
• They are edited with the same configuration sidebar used elsewhere in the app
• They also appear in Swarm graph creation controls so the two workflows share agent definitions

Scheduled Tasks

• Open Schedules in the Kanban sidebar to create workspace automation alongside the board and shared agents
• Each schedule stores a name, CLI command, enabled state, and either a one-time run timestamp or a recurring interval in minutes, hours, or days
• Run Now triggers a schedule immediately without waiting for the next automatic window
• Automatic executions create Kanban cards, stream command output into the task modal, and land in In Review with success or failure status
• One-time schedules disable themselves after they fire; recurring schedules keep calculating the next run time and preserve execution logs

Creating Agents

1. Click "Add Agent" in the graph view
2. Select a template (CEO, Programmer, etc.) or create custom
3. Configure name, role, terminal type (Claude Code, Codex, or Built-in Agent), model, and system prompt
4. Click "Save"

Choosing Terminal Type

In the Configure Agent panel, select the Terminal field:

Terminal	CLI	Models	MCP Support
Claude Code	claude	Opus 4.6, Sonnet 4.6, Haiku 4.5	Yes
Codex (OpenAI)	codex	gpt-5.1, gpt-5.2, gpt-5.3, gpt-5.4, gpt-5.5 (default)	Yes
Built-in Agent	integrated /coding-agent	provider-backed internal models	No external CLI required

You can mix agent types in the same workspace — for example, use a Claude Code CEO to orchestrate other Claude agents while running a Codex agent for parallel tasks.

Connecting Agents

1. Drag from one agent's handle to another
2. Connected agents can message each other via MCP tools
3. Edges are bidirectional (both agents see each other)

Messaging Between Agents

In any agent's terminal:

> Send a message to the Programmer asking them to create a snake game

The agent will use the send_message MCP tool automatically if connected.

Workspace Setup

• On first launch, you'll be prompted to select a workspace folder
• All agents run with this folder as their working directory
• Change workspace anytime via the folder button in the header

View Controls

• Graph Graph - Toggle graph view on/off
• Terminal Terminal - Toggle terminal view on/off
• Split handle - Drag to resize graph/terminal ratio (when both visible)

Using Voice Assistant

The voice assistant allows you to dictate commands directly to your focused terminal using offline speech recognition.

First-Time Setup

1. Install ffmpeg (if not already installed): bash brew install ffmpeg

2. Launch the app and look for the voice orb in the bottom-right corner

3. Install Whisper.cpp (one-time setup, ~5 minutes):

4. Click the voice orb
5. Click "Install Whisper.cpp"
6. Wait for compilation to complete

7. Requires: git, make, and C++ compiler (install with xcode-select --install)

8. Download a model (choose one):

9. Tiny (~75MB) - Fast, decent accuracy
10. Base (~150MB) - Recommended, good balance
11. Small (~500MB) - Better accuracy, slower

Recording Voice Commands

1. Click the voice orb or press Cmd+Shift+V (Mac) / Ctrl+Shift+V (Windows)
2. Speak your command clearly
3. Click again or press the shortcut to stop recording
4. Wait 2-5 seconds for processing
5. The transcribed text will be automatically sent to your focused terminal

Features

• Fully offline - No internet required after setup
• Real-time waveform - Visual feedback while recording
• Auto-injection - Text sent directly to focused terminal
• Keyboard shortcut - Quick access with Cmd+Shift+V

Troubleshooting

"Audio conversion failed. Please install ffmpeg" - Install ffmpeg: brew install ffmpeg

"Whisper binary not found" - Click the voice orb and install Whisper.cpp - Ensure you have development tools: xcode-select --install

"Model not found" - After installing Whisper.cpp, download a model (Base recommended)

Transcription is slow - First transcription takes longer due to model loading - Use a smaller model (Tiny or Base) for faster processing - Processing typically takes 2-5 seconds

Poor transcription accuracy - Speak clearly and closer to the microphone - Reduce background noise - Try the Small model for better accuracy

Troubleshooting

"agent-bridge failed" error

• Ensure claude CLI is installed and in PATH
• Check that MCP config files are being written (see console logs)
• Verify agents are connected in the graph before messaging

Termi