Chapter 9 — AI Hierarchy Builder

The Hierarchy Builder is the visual canvas where you compose multi-agent pipelines. Drag chips, wire ports, click Run, watch data flow. This chapter walks the UI region by region.

Prerequisites — read these first if you're brand new:
- An AI provider. AI Agent modules call a live model. You need a working key (or a local Ollama instance) before Run does anything interesting. See Ch. 8 §"I don't have an API key yet" — setup paths.
- The AI Hierarchy plan. The visual canvas is licence-gated separately from the API key. Open from AI → Agent Hierarchy Builder (Ctrl+Shift+H); if it's greyed out, see Ch. 17 — Activating your license.
- (Optional) Familiarity with the AI sidebar. If everything in Ch. 8 is new to you, skim that chapter first — the building blocks here assume you've already chatted with a model once.

Mental model

The builder is shaped like a circuit board.

SoC — System on Chip. The outermost container. One canvas = one SoC.
IC — Integrated Circuit. A chip you drop inside a SoC. Encapsulates a sub-workflow.
Module — Leaf component inside an IC: a Supervisor, a Worker, an AI Agent, a Filter, a protocol node.

Data flows through ports. The SoC has SoC-level In/Out ports on its outer boundary. Each IC, when first placed, has IN-0 and OUT-0 ports. You wire them together with cyan signal lines.

┌────────────────── SoC ────────────────────────┐
│  ●SoC In ──────────────────► ●SoC Out         │
│                                                │
│   ┌──── IC: "Triage" ────┐                    │
│   │  IN-0 ──► [filter] ──► [agent] ──► OUT-0  │
│   └──────────────────────┘                    │
│                                                │
└────────────────────────────────────────────────┘

When you double-click an IC you drill in — the canvas zooms into that IC and shows its modules. The path is shown as breadcrumbs at the top so you can walk back out.

Window layout

┌─────────────────────────────────────────────────────────────┐
│ Toolbar: Save | Load | Run | Pause | Stop | Trace | Theme   │
├──────────────┬──────────────────────────┬───────────────────┤
│ Library      │   Canvas                  │ Properties        │
│ ─ Search     │   (zoom, pan, multi-tab)  │   for selected    │
│ ─ Categories │                           │   node            │
│   (AI, Proto,│                           │                   │
│    Filter,...)│                          │                   │
│   drag from  │                           │                   │
│   library    │                           │                   │
│   onto       │                           │                   │
│   canvas     │                           │                   │
├──────────────┴──────────────────────────┤                   │
│ Minimap                                  │                   │
└──────────────────────────────────────────┴───────────────────┘

Library (left) — searchable, collapsible sections. Drag a chip onto the canvas to place it.
Canvas (center) — the actual board. Multi-tab; you can have several SoCs open at once.
Properties (right) — settings for the selected node (model, prompt, parameters).
Minimap (bottom-left of canvas) — bird's-eye view; click-to-jump.

Component library

Top-level sections in the library sidebar:

SoC — outer containers.
IC — chip containers (drop into a SoC).
Agent Modules — Supervisor, Worker, Critic, Planner, Retriever, AI Agent (generic with custom prompt).
Protocol Components — HTTP request, MQTT publish/subscribe, WebSocket, SSE, Modbus query, OPC UA tag read.
Data / Filter — Filter, Splitter, Joiner, Map, Reduce, JSON path, Regex extract.
IO — File read/write, Database query, Stdout sink.

Search by name. Drag onto the canvas to place.

Wiring data flow

Hover over a port on the source chip — the port becomes a target.
Click and drag to a port on the destination chip.
Release. A cyan line connects the two.

A few rules:

Output ports connect to input ports. Input → input or output → output are rejected.
You can branch one output to multiple inputs.
Joining many outputs into one input requires a Joiner module (the runtime picks one signal otherwise).
Click a wire and press Delete to remove it.

In-flight wires (mid-drag) can be cancelled with Esc.

Properties panel

Click a node to populate the right-side panel. Common fields:

Name — human label.
Description — free-text, for documentation.
Model (on AI Agents) — which Claude/OpenAI model.
System Prompt — the agent's instructions.
Tools — checkboxes for shell, file, web, MCP servers.
Retry / Timeout / Cost limit — runtime guardrails.

Changes save automatically when you click off the field.

Running a pipeline

The Execution Toolbar across the top of the canvas:

Run (▶) — starts the SignalFlowEngine. Signals flow from SoC In, through every wired chip, out SoC Out.
Pause (⏸) — stops new signals; in-flight modules finish.
Stop (■) — cancels everything immediately.
Trace mode — overlays per-message data on the wires as they fire. Slower; useful when debugging.

A running pipeline shows pulsing cyan on active wires. Each module shows a status badge: idle / running / waiting / errored.

Errors raise a non-modal toast at the bottom right with the module name and the exception. Click the toast to jump to that module on canvas and see the full trace in the properties panel.

Autosave & crash recovery

Every 30 seconds, the current SoC is autosaved to ~/.aidaide/builder_drafts/ with a timestamp. If AidaIDE crashes mid-edit, the next launch prompts you to restore the most recent draft.

Manual save: Save in the toolbar. Save As… to give the file a permanent name. Pipelines you intend to keep should be saved under a name; drafts are auto-cleaned after 7 days.

Pipeline & Teams

The "Pipelines" dropdown above the canvas has:

Create New — scaffolds a fresh SoC with two-level ports (SoC In/Out plus a starter IC with IN-0/OUT-0).
AI Army Team — a starter team-style pipeline (supervisor + 3 workers + critic).
Load Saved — pick a previously saved SoC.

The chip library is extensible via the Marketplace (Tools → Plugins & Widgets → Marketplace Store) — installed chips show up in the library after a Refresh Library click. A <<ChipLibraryChanged>> event makes this happen automatically when the marketplace finishes.

Zoom — mouse wheel, or Ctrl++ / Ctrl+-. Clamped at min/max per tier (you cannot zoom out of a SoC by scrolling).
Pan — middle-click drag, or hold space + drag.
Drill in — double-click an IC. Breadcrumbs at the top show the path.
Walk out — click a breadcrumb, or press Esc (when nothing else is focused).
Minimap — click anywhere in the minimap to pan the main view.
Select multiple — drag a rubber-band, or Ctrl+click individual nodes.
Cut / Copy / Paste — standard shortcuts.
Delete — selected nodes and incident wires.

Visual themes

The canvas honours the global AidaIDE theme. The brand defaults are navy #0B1620 background and cyan #4DE4E4 signals. Switch theme from View → Theme or the Hierarchy Builder toolbar's small palette icon.

The guided tour

Help → Ask Macy → Hierarchy Builder Tour opens a 16-section voice-narrated walkthrough that highlights each region in turn. Useful first-pass for new users. You can dismiss any step early with Skip.

The 16 sections:

Welcome
Window Layout
Component Library
Canvas Workspace
Execution Toolbar
Agent Modules
Protocol Components
Wiring & Data Flow
Properties Panel
Control Panel
Pipeline & Teams
Advanced Features
Visual Theme
Navigation & Tools
Power User Features
Finish

Worked example — "Triage support tickets"

A minimal pipeline that demonstrates the workflow:

Create New — fresh SoC scaffolded with SoC In/Out and one starter IC.
Rename the IC to "Triage."
Drill in to the IC.
Drag from library: a JSON path filter, an AI Agent, a Joiner.
Wire: IN-0 → JSON path (extract subject+body) → AI Agent (classify into [bug, feature_request, billing]) → Joiner → OUT-0.
On the AI Agent, set Model = Sonnet, System Prompt = "Classify the message…".
Walk out of the IC.
Wire SoC In → IC IN-0 and IC OUT-0 → SoC Out.
Run. The Properties panel of SoC In has a manual-trigger field — paste a ticket JSON, click Send, watch the signal pulse through to SoC Out where the classification appears.

That is the whole shape. Pipelines that read from a Slack source, fan out to multiple workers, and write to a database are built the same way with more chips and more wires.

Web Composer (browser version)

A browser version of the Hierarchy Builder ships with the Cloud Portal. Open it from a device's web dashboard via the Composer button. It mirrors the desktop builder's modes (flat / IC / SoC / hierarchy) and shares its document format — drafts in ~/.aidaide/builder_drafts/ round-trip between the two.

The web toolbar has Zoom In / Out / Fit, Auto Layout, Auto Wire, Validate, and Run / Stop. See Ch. 21 §Web Hierarchy Composer for the full walkthrough and known parity gaps (animated trace, right-click menus, Macy tour are desktop-only as of 2026-05-29).

Terms & Setup

SignalFlowEngine

The in-process runtime that walks the graph and executes modules. Each wired connection becomes a queue; each module is an async coroutine driven by _chip_module_executor. Runs in the AidaIDE process, no external orchestrator.

Trace mode

A run option that emits per-message snapshots into the canvas overlay. Adds overhead — turn off for benchmark runs.

Drafts

Autosave files in ~/.aidaide/builder_drafts/. Auto-clean after 7 days. Drafts you want to keep should be Save As-ed into your own folder.

"My wire will not connect"

Both endpoints must be ports. Hover until the port turns highlighted before clicking.
Direction matters: output → input.
One input usually accepts one wire (Joiner is the exception).

"My pipeline runs but produces nothing"

Check the SoC's Out port. If the chain inside ends at an IC whose OUT-0 is not wired to SoC Out, nothing leaves.
Use Trace mode to see which wire stops carrying messages.

"A module errors out repeatedly"

Properties → click the module → look at the Last error field.
For AI Agents: bad API key, rate limited, or the system prompt asks for a tool the age