Chapter 1 — Getting Started

This chapter walks you through the very first minutes with AidaIDE — from launching the app to recognising every part of the main window. Read it once, then keep it open as a glossary while you explore.

What this chapter assumes

AidaIDE is installed. If not, grab the installer from aidaide.app and run it.
You have not yet entered a master password or set anything up.

If you have a license key, you can use it later — AidaIDE will launch without one.

Launching AidaIDE

Double-click the AidaIDE shortcut (or run aidaide from a terminal). The first thing you see is the Smart Login window — a navy panel about 460 × 600 px, centered on screen, with the $_ chip logo at the top.

The window is small, simple, and intentional: nothing else in the IDE will be visible until you authenticate.

Unlocking the vault

The login window has one job: unlock (or create) your vault. The vault is an encrypted file on disk that holds every secret AidaIDE knows about — SSH passwords, SSH key passphrases, API keys, database credentials, and the like.

First time (new install)

The status line reads "Create Master Key" and the button reads Create.

Type a master password. There is no recovery path — write it down somewhere safe.
Press Enter or click Create.
The vault is initialised, the splash plays, and the main window opens.

Returning user

The status line reads "Vault Locked" and the button reads Unlock.

Type your master password.
Press Enter or click Unlock.

If you have genuinely forgotten the password, the small link under the password box — Forgot password? Reset vault — will wipe the salt and force you to create a new one. Every secret previously stored in the vault is lost when you do this. You will have to re-enter every SSH password and key passphrase.

Soft-restart bypass

If AidaIDE restarted itself (because the web admin pushed a soft-restart, or because you applied an update), the login window may not appear at all. That is by design — your session is restored automatically. Lock the vault manually from File → Exit if you want to force a password prompt next launch.

Splash screen

After a successful unlock, a 4-second splash plays before the main IDE appears:

lite (default) — a small centered panel: the $_ tile draws itself in, the glyphs fade, the cursor blinks, then the tile collapses to a singularity.
full — full-screen with a cyan "code rain" of ~1,400 glyphs. Opt in by setting the environment variable AIDA_SPLASH=full.

You can skip the splash entirely with AIDA_SPLASH=off. The brand palette during the splash is navy #0B1620 with cyan #4DE4E4.

What you see

Once the splash clears, the main window has five named regions. Memorising these names makes the rest of the guide much easier.

┌───────────────────────────────────────────────────────────────────┐
│ Menu bar:  File  Edit  Tools  AI  Fleet  Network  Security ...   │
├───────────────────────────────────────────────────────────────────┤
│ Toolbar:  [+] [≡] [🔍] | Fleet ⚡ | Scan Serial Dash OTA | ★ AI ...│
├──────────┬─────────────────────────────────────┬──────────────────┤
│          │                                     │                  │
│ Sidebar  │    Notebook (tabs)                  │   LCOT panel     │
│ (left)   │    - Connection tabs (pinned left)  │   (right)        │
│          │    - Feature tabs   (pinned right)  │                  │
│          │                                     │                  │
├──────────┴─────────────────────────────────────┴──────────────────┤
│ Status bar                                                        │
└───────────────────────────────────────────────────────────────────┘

Menu bar — the dropdowns at the top.
Toolbar — icon buttons under the menu bar.
Sidebar (left) — collapsible panels for Connections, Files, and AI chat.
Notebook (center) — the tab strip where every workspace lives. Connection tabs (one per SSH host) pin to the left, feature tabs (Fleet Manager, Security Scanner, etc.) pin to the right.
LCOT panel (right) — the Local Chain of Thought one-click script library. Shows only when a connection tab is in front. See Chapter 4.
Status bar — current file, cursor position, encoding, line endings.

The complete menu list. Each item is covered in its own chapter — this is the lookup table.

File — New Tab, project templates, Open File, Save, Recent submenus, Workspaces, Connection Manager, Settings, Experimental Features, Keyboard Shortcuts…, Exit.
Edit — Undo/Redo, Cut/Copy/Paste, Find (Ctrl+F), Find in Files (Ctrl+Shift+F), Go to Line (Ctrl+G).
Tools — Git submenu, Protocol Wizard, Board Library Manager, Test Panel, Device Monitoring submenu, Plugins & Widgets submenu, Check for Core Updates.
AI — Toggle AI Sidebar, AI Chat, Claude Agent Manager, Agent Hierarchy Builder, Live Coding Agents, AI Agent Portal, Persona Portal, AI Workflows, Toggle Inline Suggestions, Save/Load Chat Session.
Fleet — Fleet Manager, Deploy Lite, Discover Devices, Device Dashboard, OTA Update Manager, Web Dashboard.
Network — Port Scanner, Network Topology, Packet Capture, Traffic Analyzer, Network Diagnostics, Host Discovery, Service Detection; Cameras submenu.
Security — Security Scanner, CVE Scanner, Dependency Scanner, Secret Scanner, SAST Scanner, Threat Intel Feeds, IOC Database, PKI Manager, Certificate Inventory, IP Access Control, Compliance Assessment.
Preview — early-access groups: Sysadmin, Database, Debug.
View — Command Palette, Feature Browser, Open Project Folder, Layout Mode (Classic Tabs / Grid), Theme, Layout Presets, sidebar toggles.
Help — Welcome Guide, Setup Wizard, Ask Macy (interactive tour), About, Documentation, Check for Updates, Enter License Key, License Status, Bug Reports.

Left to right:

New Tab (+) — opens a connection tab. If you have at least one saved host it shows a chooser; otherwise opens Connection Manager.
Connections (≡) — opens Connection Manager.
Features (magnifier) — opens the Feature Browser (every feature tab grouped by category, with search).
Fleet Manager — opens the fleet management tab.
Deploy ESP32 (⚡ orange) — shortcut to Deploy Lite scoped to ESP32 targets.
Scan / Serial / Dashboard / OTA Update — monitoring shortcuts.
AI Assistant (★ green) — opens Claude Agent Manager.
Workspace: label + layout-preset combo, save layout (floppy), Layout Wizard (✨).
Git Branch dropdown and Git Push (↑).
Settings (gear, far right).

Every button has a tooltip; hover for a second to see its name and shortcut.

First-run wizards

The very first session may show one (or both) wizards. They are independent:

Onboarding Wizard

Fires when no saved connections exist and config["onboarding_completed"] is false. Seven steps:

Welcome — short description of what AidaIDE is.
Theme — pick a colour theme with live preview.
AI Assistant Setup — choose a provider (Anthropic Claude is recommended), paste an API key, set a skill level. Skipping is fine; you can do this later in AI → Claude Agent Manager.
Editor Preferences — font family and size.
First Connection — optional. Add one SSH host now or skip and use Connection Manager later.
Navigation Guide — quick tour of where things live.
Keyboard Shortcuts — printable reference of default bindings.

Device Setup Wizard

Fires when ~/.aidaide/first_run_complete is missing. Six steps focused on hardware:

Welcome.
Device Type — pick from cards: Raspberry Pi, ESP32, Arduino, generic Linux.
Connection Method — SSH (most common), Serial, or mDNS auto-discovery.
First Connection — validate live.
(Optional) deploy a sample project to your device.
Success — you are ready to go.

If you skip or close either wizard, AidaIDE remembers and will not re-prompt. To re-run either one, use Help → Setup Wizard.

Onboarding & guided tours

Help-menu tours you can replay at any time:

Welcome Guide — short overview of what each menu does.
Setup Wizard — re-runs the appropriate first-run wizard.
Ask Macy (Interactive Guide) — voice-narrated tour. Two flavours:
General IDE tour — every region of the main window.
Hierarchy Builder tour — 16 sections, covered in Chapter 9. Run it from inside the Hierarchy Builder tab.

Exiting AidaIDE

File → Exit (or close the window) saves your workspace state and locks the vault. Next launch you will need your master password again.

If you would rather have the IDE come back with your current tabs open, use File → Save Workspace As… first. Then on next launch open it with File → Open Workspace… or pick it from File → Recent Workspaces.

Terms & Setup

Vault

The encrypted store for all your secrets — SSH passwords, SSH key passphrases, API tokens, database credentials, license info. Backed by Fernet symmetric encryption derived from your master password plus a per-install salt. Lives on your machine; never transmitted anywhere.

Master password

The password you set on the Smart Login window. There is no recovery path — write it down. If you lose it, the Forgot password? Reset vault link nukes the vault and starts over.

Splash

The 4-second animated reveal between vault unlock and the main IDE. Cosmetic only; the IDE is loading in the background. Disable with the AIDA_SPLASH=off environment variable.

Connection tab vs feature tab

A connection tab is your workspace for one SSH host: terminal + file browser + editor + LCOT panel. A feature tab is a tool that does not belong to a single host: Fleet Manager, Security Scanner, Database Manager, AI Hierarchy Builder, etc.

Feature Browser

A searchable list of every feature tab grouped by category. Open it from the toolbar magnifier or View → Feature Browser. The fastest way to find a tool when you forget which menu it lives under.

"I do not have an SSH server yet"

You can launch AidaIDE without one, but most workflows assume at least one device you can SSH into. The quickest options:

Local OpenSSH on Windows — Settings → Apps → Optional Features → Add → OpenSSH Server. Start the OpenSSH SSH Server service. Connect AidaIDE to localhost:22 with your Windows username.
A Raspberry Pi — Pi OS has SSH disabled by default since 2016. Enable it with sudo raspi-config → Interface Options → SSH → Enable, or by dropping an empty file named ssh (no extension) in the boot partition.
A cloud VM — DigitalOcean, AWS, Azure all give you a Linux VM with SSH enabled in minutes.
WSL — On Windows, wsl --install gives you a Linux environment that AidaIDE can SSH into via localhost.

See Chapter 2 for the full add-host walkthrough.

Where do my settings live?

Vault and salt: %APPDATA%\AidaIDE\ on Windows, ~/Library/Application Support/AidaIDE/ on macOS, ~/.aidaide/ on Linux.
Workspaces: ~/.aidaide/workspaces/.
Hierarchy Builder drafts: ~/.aidaide/builder_drafts/.
Logs (for bug reports): ~/.aidaide/logs/.