Overview

What the desktop app does with your projects, boards, serial output, recordings and agents.

The espx desktop app is a window over the same core as the espx command. It creates and runs projects, shows attached boards and their serial output, records sessions, and connects AI agent clients to espx. It is in early development.

Start it

On an Apple silicon Mac, install the app and the espx command with one line:

curl -fsSL https://www.espx.dev/install.sh | sh -s -- --desktop

The app lands in ~/Applications/espx.app. The download page has the disk image too; macOS asks you to allow an app opened from it once, under System Settings > Privacy & Security > Open Anyway, because the app is signed ad hoc and not notarized. Installation covers both routes and how to check the signatures. The app updates itself once a day, and Check for Updates… in the espx menu checks now; see Updating.

The app is built with gpui, Zed's UI framework. To run it from a clone of the espx repository instead:

cargo run --release -p espx-desktop

On macOS it compiles its Metal shaders when it starts, so the Xcode Command Line Tools are enough. On Linux, building it needs the X11 and Wayland development libraries (libxkbcommon, libwayland, libxcb). Launched this way the app is a bare binary, so macOS names it espx-desktop in the menu bar and the Dock.

For agent connections the app needs the espx command. The installed app carries its own copy, and Install Command Line Tool in the espx menu links ~/.espx/bin/espx to it. The app looks for the command in ~/.espx/bin, beside the app, and on your PATH, and the AI agents page explains what to do when it is missing.

The window

A sidebar on the left holds Home, Toolchain, AI agents and Recordings, then your open projects and the attached boards. A bar at the top shows where you are, with back and forward, Stop, and a Run button whose menu also has Run and record, Build, Flash and Clean. A status bar at the bottom shows the toolchain, problems, the running project, any recording in progress, the board, the last agent call, and a light and dark toggle.

The command palette (Cmd-K or Cmd-Shift-P) lists everything the app can do right now. Home starts with a get-started checklist: toolchain, board, project, agent.

Toolchain

The Toolchain page shows the same checks as espx doctor. Install fetches the tools and the RISC-V targets in one click, the same run as espx setup. When any of the Xtensa pieces is missing, Install Xtensa toolchain runs espx setup --chip esp32,esp32s2,esp32s3, which installs Espressif's Rust fork. The app gives cargo the fork's environment itself, so it does not offer to edit your shell config.

Projects

New project (Cmd-N) opens a dialog with:

Field	What it sets
Name	The project name, checked as you type with the same rules as `espx new`
Location	The parent folder; created if it is missing
Chip	Defaults to the chip of the first attached board espx can identify; preview chips are marked
Board	Optional dev board model; choosing one sets its chip
Bind to	Optional attached board, written to `espx.toml` as `[board] id`, as `espx new --board-id` does
Template	Panic backtraces (on by default), defmt logging, Embassy, Heap allocation; each becomes esp-generate options

Create runs the same flow as espx new, so the project gets its README and AGENTS.md too. Open Folder (Cmd-O) opens an existing project. Open projects come back at the next launch.

Each project page has three tabs:

Output: the board's serial output, with a level filter, Follow and Clear. Panics show their frames, boots show their reason.
Problems: compiler errors and warnings from the last build, and any panic or exception from the board.
Details: the esp-rs crates from Cargo.lock, esp-hal's features, a link to the esp-hal examples of the exact release, and Copy agent context, which copies the text espx context prints.

Run, Build, Flash and Clean

Action	Keys	What it does
Run	`Cmd-R`	Builds, flashes and follows the board's output
Stop	`Cmd-.`	Stops the build or the monitor; a flash in progress finishes first
Build	`Cmd-Shift-B`	Builds and reports the time, warnings and image size against the app partition
Flash	`Cmd-U`	Builds and flashes, without opening a monitor
Clean	`Cmd-Shift-K`	Runs `cargo clean`; refused while the project is building or flashing

Run and Flash take over the board, so they stop other projects' sessions. Build and Clean leave them running. When the bootloader does not answer, the app retries once at 115200 baud, as the CLI does.

When a board needs you

When a flash fails in a way only a person can fix, the app shows a banner on every page saying what to do: hold BOOT and tap RESET, or replug the board. A toast appears, and on macOS the Dock icon bounces once if the window is in the background. The banner offers Run again or Flash again, and goes away when the board is back or a flash succeeds. The same banner appears when an AI agent's flash needs a person, read from the agent audit log.

Boards

Each attached board has a page with two tabs.

Overview shows the USB details, what is using the board (a running project, a monitor, an agent holding it), its last boot and reason, the bound projects and what agents may do to it. When espx knows the board model, it also shows the pins: LED, BOOT button and UART. From here you can:

Rename the board inline. The name goes to ~/.espx/boards.toml, as espx boards name does.
Read board info (chip, revision, crystal, flash size, features, MAC). This resets the board.
Reset it, or Erase its flash after a confirmation.

Monitor is a live serial monitor without a project. Type a line and press Enter to send it to the board, as espx monitor --input does. A monitor opened while a project runs on the same board reads the same stream.

Recordings

While a project runs or a board monitor is live, Record saves the session as a recording. Its menu has Record from the last boot, which first writes what espx still holds since the board last booted, so you can still keep a panic that happened a moment ago. Run and record arms the project to record its next run, and Settings > Recordings > Record every run does that for every run. Cmd-Shift-R starts or stops recording the board on the page you are on.

A recording in progress shows as REC on the board in the sidebar and in the status bar, until you stop it. Recordings are the same files espx monitor --record writes, kept in ~/.espx/sessions/ with one folder per board.

The Recordings page lists them by board, newest first, with Play, Rename, Delete and Show in Finder. File > Open Recording… opens any recording file. Playback keeps the original timing, with Play again, Play fast and Stop. Old recordings are deleted past the age or space you choose in settings; named ones are always kept.

AI agents

The AI agents page connects coding agents to espx mcp. It finds which of Claude Code, Codex, Cursor, VS Code and Claude Desktop are installed and whether espx is set up in each. Connect and Disconnect act for your whole user account:

Claude Code and Codex: the app runs claude mcp add --scope user or codex mcp add (or remove).
Cursor, VS Code and Claude Desktop: the app edits the client's own config file, touching only espx's entry.

Before you click, the page shows the command Connect will run or the file it will change. A client that is not installed gets the line to copy instead.

Below the clients, each open project's agent permissions: which boards agents may touch, and switches for Flash and Erase. Changing one rewrites the [agent] table in that project's espx.toml in place, keeping the rest of the file and its comments. Hand edits to espx.toml show up within a second.

Last, the activity: every call each agent made, newest first, with its tool, board, outcome and duration. A call the policy denied has an Allow button, which asks for confirmation and makes the smallest change to espx.toml that lets it through, the same as espx agent allow. See Agent policy.

The app serves its board hub on ~/.espx/hub.sock while it runs. espx flash, espx monitor and espx mcp in other processes reach the boards the app has open through it, and the app shows their boots. If another espx process already serves the hub, the app takes over once that process exits. See Sharing a board.

Settings

Settings (Cmd-,) opens a separate window with a search field and these categories: Appearance, Layout, Output, Notifications, Toolchain, Boards, Recordings, Agents, Key bindings and About. Every change is saved to ~/.espx/desktop.toml at once. The file with every default:

~/.espx/desktop.toml

[appearance]
theme = "system"             # system, light, dark
ui_font_size = "default"     # small, default, large, extra_large
reduce_motion = false

[layout]
sidebar = "left"             # left, right
sidebar_width = 208          # 160 to 400
status_bar = true
get_started = true
reopen_projects = true
projects_view = "list"       # list, grid

[output]
follow = true
clear_on_run = true
timestamps = true
clock = "elapsed"            # elapsed, local
max_lines = 4000             # 100 to 20000

[notifications]
board_connections = true
board_actions = true
duration = "default"         # short, default, long

[toolchain]
check_at_launch = true

[boards]
monitor_baud = 115200
all_ports = false
confirm_erase = true

[recordings]
record_runs = false
keep = "forever"             # forever, three_months, month, week
space = "1gb"                # unlimited, 250mb, 1gb, 5gb

[agents]
status_bar = true

A broken file never stops the app. An unknown key or an invalid value shows as a banner in the settings window and keeps the default for that key only. A file that is not valid TOML is never overwritten; changes then last for the session only. Keys a later version wrote are kept when the app saves. The list of recent projects lives apart, in ~/.espx/desktop-state.toml.

The Key bindings category lists every action with its keys.