024 · Desktop

Desktop app (spec_desktop_024)

Blitz.app is a window onto the per-user Blitz service, laid out like an IDE: the workspace in view chosen from a dropdown, its files, an editor and the conversation, with its changes and workers a click away. It contains no engine. Every workspace, turn, approval, session and worker lives in the service (blitzd), which keeps running — and keeps running workers — after the window closes. The app adds only what the service can’t do for itself: detecting and installing the service, native dialogs, and a bridge from the web view to the service’s Unix socket.

It keeps only its own settings (theme, layout, the workspaces it knows and how they are named) in ~/.blitz/desktop.json. The design follows Material 3, with an IDE’s layout since 2026-09-27 (files, editor, chat; earlier Google AI Studio’s: a navigation drawer, a centred conversation, a run settings panel). Not yet: see §16.

• DSK-01 Product name Blitz; macOS bundle Blitz.app, bundle identifier dev.blitz.desktop, executable blitz-desktop on Linux; version stamped into release builds from the git tag (//build:version, spec_monorepo_028 MR-20), dev otherwise; the page asks for it (Version()); copyright “Ryan McGuinness, Apache License 2.0”. 2026-10-15 (the owner’s request): where people read Blitz’s version (Settings › About, the Service pane and its stale-service note, the window’s stale-service banner, the restart message, the status bar), a release’s is shown as vN.N.N (shownVersion, serviceVersion.ts), as the tags, releases and docs write it; dev and a commit stay as they are. The stamped version has no v (packages need a digit first), and it’s what the stale check compares.
• DSK-02 Removed in v0.7.0 (the Wails app; see spec_electron_038). The app’s executable must never be named blitz/Blitz: macOS file systems ignore case, and the bundled CLI (Contents/MacOS/blitz) would overwrite it.
• DSK-03 Removed in v0.7.0 (the Wails app; see spec_electron_038). Minimum macOS 13.0: the build sets -mmacosx-version-min=13.0, and LSMinimumSystemVersion in Info.plist/Info.dev.plist says the same.
• DSK-04 The CLI and the service (blitz, blitzd) are packaged with the app (since v0.7.0 in the app’s bin/ with blitz-tray: Blitz.app/Contents/Resources/app/bin/ on macOS, resources/app/bin/ elsewhere; EL-03, EL-80) so the app can install the service without a separate install: blitz service install finds blitzd beside itself.
• DSK-05 Releases package the app for macOS (a notarised disk image; universal until v0.6.5, one per Mac since) and Linux (a .deb, and a .pkg.tar.zst for Arch Linux): spec_release_025 REL-20–26. There’s no Windows package: on Windows the tray serves this page to a browser instead (spec_windows_036). Since v0.7.0 the desktop app released is the Electron app, on every platform, Windows included (spec_electron_038 EL-80); the Wails app is removed from the repository.

Until v0.6.5 (the Wails app). Since v0.7.0 the page runs in the Electron window and its host is blitz-tray --serve (pkg/pagehost, pkg/pageserver): spec_electron_038 §2.

┌──────────────── Blitz.app ────────────────┐        ┌────────── blitzd ───────────┐
│ Web view (React page, embedded dist/)     │        │ Connect API: Session,       │
│   ├─ Connect-ES clients ─► same origin ───┼─┐      │ Workspace, Worker services  │
│   └─ window.go.main.App.* (Wails binding) │ │      │ workspaces, turns, workers  │
│ Go (Wails v2):                            │ │ HTTP │                             │
│   ├─ asset server: page files             │ │ over │                             │
│   ├─ serviceProxy: /blitz.v1.* ───────────┼─┴─Unix─► ~/.blitz/run/blitz.sock    │
│   └─ App: ServiceStatus, InstallService,  │  socket└─────────────────────────────┘
│           ChooseWorkspace, Get/SavePrefs, │
│           OpenURL                         │
└───────────────────────────────────────────┘

• DSK-10 Part of the repository’s one Go module. Until v0.6.5 the desktop app alone used cgo (WebKit on macOS, WebKitGTK on Linux); since, its Go is the host’s (pkg/pagehost in blitz-tray), pure Go but for the tray’s Dock icon on macOS. It never reaches the engine or the service’s internals (spec_monorepo_028 MR-01): it uses pkg/socket (the socket’s path, BaseURL and HTTP client), pkg/loginitem, pkg/config and pkg/legal; its tests run a real service through apps/service/servicetest.
• DSK-11 Window: title “Blitz”, 1280×820, minimum 720×480. On macOS the title bar is hidden and inset: the page draws the whole window in its theme’s colours, leaves room for the window buttons at the left of the top bar, and marks its top areas as drag regions (.drag-region; controls in them are no-drag). Since v0.7.0 that’s the Electron window (apps/electron/src/main.ts, EL-12); until then the Wails window (mac.TitleBarHiddenInset, --wails-draggable, one Go App value bound to the page as window.go.main.App).
• DSK-100 Removed in v0.7.0 (the Wails app; see spec_electron_038). On Linux the Electron window draws with the graphics card unless BLITZ_GPU=off or the gpu preference (Use the graphics card) is off: EL-07. What follows was the Wails app’s. 2026-10-13 (the owner’s request, after a Linux soak run held WebKit at 100% CPU idle). On Linux the window draws with the graphics card where WebKitGTK can use it (linux.Options.WebviewGpuPolicy on demand; Wails, given no Linux options, draws in software, its default since wails#2977). Use the graphics card (gpu, "on" by default, in the preferences; Settings › Appearance with the advanced settings, shown only in the Linux app) turns it off, from the next start. BLITZ_GPU=off (or on) in the environment overrides the setting, for a driver that keeps the app from starting at all. On NVIDIA (/dev/nvidiactl present) WebKitGTK leaves its DMA-BUF renderer off and draws in software whatever the policy says, so with the GPU on Blitz sets WEBKIT_FORCE_DMABUF_RENDERER=1 and WEBKIT_DMABUF_RENDERER_FORCE_SHM=1 (each unless already set; neither when WEBKIT_DISABLE_DMABUF_RENDERER is set): the web process draws on the GPU and hands frames to the GTK3 window in shared memory. Forced on with GPU buffers, NVIDIA’s EGL attaches a Wayland explicit-sync object (wp_linux_drm_syncobj_surface_v1) to GTK3’s surface, which commits without an acquire point, and the compositor ends the connection (protocol error 71). Closing the window (once the editor’s unsaved changes are settled) ends the web processes through WebKitGTK (webkit_web_view_terminate_web_process) before GTK’s main loop and the window go (the Wails app’s webprocess package): left to exit on its own with the GPU on NVIDIA, the web process segfaults in its exit handlers, NVIDIA’s EGL tearing down while WebKit’s painting threads still release their GL contexts, a core dump and a crash report on about half the closes; ended by WebKit, it’s killed and runs none. bazel run //apps/desktop/gpucheck:gpu_check checks on a machine with a GPU that WebKit draws with it (manual verification §37). Drawing in software sets WEBKIT_DISABLE_DMABUF_RENDERER=1 (unless the environment already sets it), the usual fix for a blank or garbled window on NVIDIA’s drivers and in VMs. The window’s class is blitz-desktop (GTK’s program name, the launcher’s StartupWMClass), so the dock or taskbar groups it under the launcher’s icon however the binary was started, and the window carries the app icon (256 px, windowicon.png) for a taskbar that doesn’t find the launcher’s. The chat input’s ring turns only while the agent works: turning, it repaints every frame (an animated registered property the compositor can’t take), a core’s worth in software.
• DSK-101 2026-10-13 (the owner’s request). macOS’s menu bar is the app’s own (since v0.7.0 the Electron app’s, setMenu in apps/electron/src/main.ts, EL-13; until then options.App.Menu, appmenu.go): the app menu has About Blitz, Settings… (⌘,), Hide Blitz (⌘H), Hide Others (⌥⌘H), Show All and Quit Blitz (⌘Q, asking first about unsaved changes as closing does), then the Edit and Window menus. About and Settings send the page menu:about and menu:settings, which open Settings › About and Settings › Appearance. The page sends the labels in its language (SetMenu) as it starts and when the language changes; until then they’re English. Linux and Windows have no native menu bar: the page’s is the only one. In full screen on macOS, Escape stays the page’s (closing a dialog or popover); ⌃⌘F, F11 or the window’s button leave it.
• DSK-102 2026-10-14 (the owner’s request: the window had 18 of the terminal’s 49 commands). The window’s slash commands match the terminal’s (slashCommands.ts, one registry the composer’s menu, the command palette and /help share). Every command the REPL’s /help lists is a built-in here, in the same seven groups (Session, Agents and models, Planning and long work, Workspace and files, Permissions and safety, Extensions, Settings), each sorted by name, answering with a notice, a turn or the window’s own UI through the service’s API: among them /status, /copy, /export (a workspace file), /fork, /rewind, /style, /pin_model, /unpin, /model_settings, /goal (the terminal’s prompt), /loop (timers in the window while it’s open; Workers outlive it), /tasks, /attach, /init, /memory, /trust (the project review when settings wait), /approvals, /hooks, /permissions, /sandbox, /envs, /mcp, /skills (and update), /tools, /config (or /set; no arguments opens Settings › Settings file, --save writes the user’s file), /locale (the reply language) and /theme. /clear, /exit and /quit, /paste, /cd and !<command> stay the terminal’s; /help names them with the window’s way instead. /help lists the custom commands by source after the built-ins. slashParity.test.ts reads the REPL’s helpGroups and fails when a terminal command is neither here nor terminal-only.
• DSK-103 2026-10-14 (the owner’s request: the docs can change over time). The app carries the user docs of its own release: the home page, Getting started, Tutorials, Guide, Products and Releases of docs/content, and their picture (//docs:user_docs, bundled into the page as its own chunk by src/docs/content.ts; the specifications, development and architecture pages are left to the website). src/docs/index.ts reads them as the site does (front matter title and weight for the order; relative .md links, _index.md the section) and resolves a page’s links: to another page the app carries, a heading, or the website for anything else; its search ranks title, then headings, then text. The viewer (DocsDrawer.tsx, Settings’ layout) has the navigation, search, a breadcrumb, back and forward (⌘[ ⌘]) and Open on the web, and renders with the page’s Markdown (Mermaid, tables, math) under a docs link context. It opens where it was left, page and scroll (apps/desktop/web/src/docs/place.ts, the window’s storage), and on Tutorials the first time; Help’s section links, the palette and /docs topic open their page. It fits narrow windows (container queries on the viewer): under 700 px the navigation folds behind Contents; on a page under 680 px a table’s rows stack as cards (the first cell as the heading, the others labelled with their column), and a table of four or more columns stacks under 900 px; wider, every cell is at least 8em (a crowded table scrolls) and code in a cell stays on one line. Help › User guide (where it was left), a Help link per section (Getting started, Tutorials, Products, Guide, Releases; apps/desktop/web/src/docs/sections.ts, checked against the docs), /docs [topic] (the best match) and a Docs group in the ⌘K palette open it (openDocs). The website stays published. docs.test.ts checks every carried page and link; docsCommands.test.ts that every command products/cli.md documents exists in the terminal or among the bundled commands. 2026-10-15: the release shortcode ({{< release >}}, in install snippets) is the app’s own release there (withRelease, src/docs/index.ts), or vX.Y.Z in a build that isn’t a release.
• DSK-12 The page is built by Bazel (//apps/desktop/web:page, Vite) for the host platform: since v0.7.0 carried in the Electron app’s page/ (EL-03) and embedded in the Windows tray (apps/tray/page.go); until then embedded in the Wails binary. Nothing is written into the source tree.

• DSK-20 A web view can’t open a Unix socket, so the handler serving the page (since v0.7.0 blitz-tray --serve, SVC-53a; until then the Wails asset server’s) forwards every request whose path starts with /blitz.v1. to the service socket ($BLITZ_SOCKET or ~/.blitz/run/blitz.sock, resolved at start), rewriting the URL to the service’s BaseURL. The page’s Connect client uses window.location.origin as its base URL, so it talks to its own origin and needs no CORS.
• DSK-21 Responses stream as they arrive (FlushInterval: -1): turn events and worker-run events must appear as they happen. WebKitGTK (Linux, the Wails app) streamed them, but sometimes held back the last data written before a pause until more arrives (found 2026-09-28: an approval request, after which the service waits, stayed unseen and the turn showed “Working…”). So a Connect stream (application/connect+json or +proto) goes through keepalive: the service’s messages pass whole, and after 250 ms of quiet an empty message ({}, or no bytes in protobuf) follows, never inside a message or after the end-of-stream one; the page skips messages without an event.
• DSK-22 If the service can’t be reached, the proxy answers 503 with Connect’s JSON error shape {"code":"unavailable","message":"the Blitz service isn't answering"}, which the page’s client reports like any API error.
• DSK-23 Any other path the handler receives is 404, apart from the page’s own files and the host’s /host/ calls (since v0.7.0 both served by blitz-tray --serve; until then Wails served the page from the embedded assets).
• DSK-24 Security: the socket is owner-only (spec_service_021 SVC-02); the proxy listens only on a loopback address behind a one-time link and a cookie (WIN-11–13; the Wails app’s opened no listener), so nothing new is reachable from the network. Only the embedded page runs in the web view. Model and tool output becomes React elements (Markdown through react-markdown, raw HTML skipped; everything else escaped), never HTML; its links open only in the system browser through OpenURL (web and mail schemes only), and its images are never fetched from the web (a picture written into it as a data: URL, or in a document one in the workspace, is shown: spec_files_029 FIL-65), so output can’t navigate the web view, inject script or make the app load anything.

Since v0.7.0 the Electron window answers ChooseWorkspace, Notify, OpenURL, PrintPDF and the window’s own calls (EL-20), and the host answers the rest through /host/ (pkg/pagehost, EL-21); until then they were Go methods bound to the Wails window.

• DSK-30 The page calls the Electron window for what it answers (window.blitzElectron, EL-40), else asks the program serving it which calls it answers (/host/info: blitz-tray --serve, or the tray on Windows, spec_windows_036 WIN-14–15) and calls those there. For the rest (and in a browser in development) it uses stand-ins: preferences in localStorage, the status from a call to the service through the dev server’s proxy, a prompt for the directory, links in a new tab. Calling one that nothing answers throws “not running inside the Blitz desktop app”.

• DSK-35 Material 3 tokens (m3.css): the colour roles (primary, secondary, tertiary, error, warning containers, and surface / surface-container-lowest…highest, outline, outline-variant, inverse, scrim, diff colours) in a light and a dark scheme derived from Google blue #0B57D0, with AI Studio-like neutral surfaces (dark surface #131314); shape (4–28 px, full), elevation 1–3, type scale (display, headline, title, label, body) in Google Sans/Roboto with system fallbacks and a monospace stack. Components use only tokens: buttons (filled, tonal, outlined, text, danger), icon buttons, chips, segmented buttons, outlined fields and selects, switches, sliders, lists, cards, a menu bar with a search bar, menus (an item may carry a button at its end, MenuItem.action, shown on hover or focus; right-click menus are dense: 28 px rows, 16 px icons, key hints on the right), dialogs, a snackbar, progress indicators and badges, all with M3 state layers. Since 2026-10-04 (the owner’s request) the controls share the chat input’s ring’s colours, an accent: --accent-a to --accent-b, --accent-grad (light: a brighter blue than the primary, #1a73e8, to teal #00838f; dark: the primary #a8c7fa 45% toward the tertiary, teal rather than green). Filled buttons and filled icon buttons are that gradient at 135° with a soft accent shadow, a hairline highlight on top and, on hover, a deeper shadow and a 1 px lift (none with reduced motion); disabled, they go flat (surface-container-highest, no shadow). Danger stays solid red. Tonal buttons and everything selected (icon buttons such as Files’ hidden-files eye, chips, segmented buttons, list items, menu items, the command palette’s, search hits, the file tree’s row, a table’s focused row) are a tint of the same gradient (--accent-tint: light, 18% of each end over white; dark, each end 30% over a deep blue and a deep teal), so they read as a lighter version of the filled colour; segmented buttons and outlined buttons have accent-tinted borders, and the editor’s open tab the gradient along its top. Every field-like box (inputs, text areas, selects, the find bar, the settings and CSS editors) has one radius, --field-radius (8 px), and the outline border; fields have their own surface (nearly opaque under glass) and, focused, the accent’s border with a 3 px halo (red when invalid); focus rings, checked switches, sliders and progress bars are the accent. Button text keeps 4.5:1 or more on both ends of the gradient (light: white, 4.5:1; dark: on-primary, 7.3:1). Icons are Material Design icons as inline SVG paths (@mdi/js, tree-shaken), not a font.
• DSK-36 Theme: the user chooses System (the default), Light or Dark; System follows the OS setting live (prefers-color-scheme). The choice is applied as html[data-theme]; density (Comfortable or Compact) as html[data-density]. Motion is reduced when the OS asks for it.
• DSK-37 Narrower windows: the view switcher shows icons only under 1100 px. Since 2026-10-04 (the owner’s request) no panel ever floats over another: the Files shelf keeps its column at every width (it floated over the editor under 1100 px, hiding the chat’s tiles at center stage), and in a narrow window the panels give way to their minimums — the shelf down to 180 px, the editor to 160 px, the chat to 320 px — the shelf minimized to the rail when you want the room. Opening a file no longer minimizes it. A Changes pane under 760 px wide lists its files and turns above the diff (a container query). The composer’s key hint hides when the composer is under 560 px wide, and a long file path in the editor gives way from its folders, keeping the file’s name. The snackbar sits bottom left, above the status bar, clear of the composer. 2026-10-14 (#37): it sits at the top center, just below the top bar (following it down when a banner shows), clear of the composer. 2026-10-15 (the owner’s request): it sits below the panes’ headers too (the editor’s tabs and toolbar, the Files and side panels’ heads, wherever they’re under its 640 px), which it covered just under the top bar. Since v0.6.3 it has rounded corners (16 px) and, with glass on, is a pane of glass like the others: nearly opaque (--glass-strong), the page’s ink and accent, not Material’s inverse slab.
• DSK-38 Glass (glass.css): with Settings › Appearance › Transparency on (the default; transparency in the preferences) and the system not asking for reduced transparency, html[data-glass="on"] makes the surface roles translucent, the top bar, panels, editor and status bar blur what’s behind them (backdrop-filter), and dialogs, menus, the composer and the snackbar get a light edge and a soft shadow. Since 2026-10-02 light glass is frosted rather than clear, so it stays usable: surfaces 78–93% opaque (they were 50–80%), borders and outlines a grey that shows on white (--glass-border rgb(110 122 145 / .28), --md-outline-variant at 45%), a stronger shadow and scrim, and a backdrop a step deeper (#e3e8f1, with more saturated glows) so the panes lift off it; text and muted text keep 13:1 and 7.7:1 or more on every surface, the ring’s colours 5:1 or more. Dark glass is unchanged. The page’s backdrop is a soft gradient; in the macOS app the window itself is translucent (Electron’s vibrancy, EL-12; html[data-native-glass]), so the desktop shows through. The workspace’s areas (Files, the editor or center, the chat) float as rounded glass panes 8 px apart, and the top bar sits on the backdrop itself. A dialog’s scrim blurs the window behind it. Since 2026-10-04, the macOS window’s blur takes the page’s theme, not the system’s: a light page in a dark system had its top bar, gaps and buttons on a dark blur, all but unreadable. applyTheme calls SetAppearance with the user’s choice (NSApp.appearance: Aqua for Light, Dark Aqua for Dark, and for System none, so the window follows the system again — it must, since the page’s prefers-color-scheme reports the window’s appearance, and a window held light would hide the system’s switch to dark; on the main thread; nothing on other systems), and under data-native-glass the body is the backdrop’s glows, translucent, over a base in the theme (--backdrop-native; light rgb(227 232 241 / .68), dark rgb(11 14 21 / .55)) rather than clear: the gradient reaches the top bar and the gaps between the panes, as in VS Code, and the ink stays on its own theme even where the blur doesn’t follow. Light glass also has the menus in on-surface, muted text #3c4043, the text and outlined buttons’ blue #0842a0, and disabled buttons at 50% (38% elsewhere). What floats over other text (dialogs, menus) is nearly opaque, so it stays readable where the blur isn’t drawn. Off: the solid Material surfaces. Since v0.6.3 (the owner’s request) warnings are glass too: the banner over the window (the service lost or out of date) and warning cards (.card.warn: a model unavailable, a setting’s problem) are nearly opaque panes (--glass-strong) with the warning colour on their left edge and icon, not a solid yellow block; the window’s banner floats with the panes’ gap and corners. Since v0.7.0 the drawer (DSK-65c) is one more pane: the same border, corners, blur and shadow, 8 px from the window’s edges, but opaque (--glass-solid, the nearly opaque glass’s colour in full): it covers the whole middle, and the panes faintly showing through only got in the way.
• DSK-38a Since v0.7.0 (the owner’s request: “not everyone will like what I like”). Colour themes, chosen as VS Code’s preferred light and dark themes are: Settings › Appearance › Light theme (Blitz, One Light) and Dark theme (Blitz, One Dark Pro), beside Theme (System, Light, Dark), which picks between them; light_theme and dark_theme in the preferences (blitz by default; anything else, or a dark theme for light, is read as blitz). The page sets html[data-palette] to the one in effect (paletteOf, themes.ts); themes.css gives each other theme the M3 roles’ colours, the highlighting’s (--hl-*, so the editor, code blocks and diffs follow) and the accent’s, taken from the themes themselves (Atom’s One Light UI and syntax; Binaryify’s One Dark Pro; MIT, credited in the third-party notices from third_party/themes). They’re solid: glass (DSK-38) is Blitz’s own theme’s, so Transparency is off, and says why, while another is in effect.
• DSK-37a Since v0.7.0 (the owner’s request: “when a large amount of output is shown, the narrow view is not readable”). With files open, the chat’s header and the editor’s tab bar each have Expand (Workspace.tsx wide): the one expanded takes the middle of the window and the other is hidden, kept as it was (the editor’s tabs, views and web pages; the chat’s conversation, the composer still at the window’s foot). The hidden one leaves a rail on its side, as the Files shelf’s (PaneRail): its icon and name, the number of files open (the editor’s) or a dot while the agent waits for you (the chat’s), so it reads as shrunk, not closed; clicking it, or Shrink, puts the two side by side again, and opening a file or a web page shows the editor.
• DSK-39 Status bar (StatusBar.tsx): a 26 px strip under the whole window, glass with Transparency on, shown on every view including the welcome screen. Left: the service (connected, or reconnecting; its version on hover), the workspace in view (its colour and name), and its git branch (the short commit when detached) with the files that differ from HEAD, untracked included, and since v0.6.3 the commits to pull (↓n) and push (↑n) as of the last fetch, with a merge icon while a pull’s merge or rebase waits (WorkspaceService.GetGitStatus, asked on showing, 0.5 s after a tool touches files, on focus and every 10 s while visible; git runs read-only with the repository’s filters and fsmonitor off; nothing outside a repository) — clicking shows Changes. Right: a turn running, or waiting for you (clicking it brings the approval or question into view and focuses it; one also comes into view as it arrives), the background runs going or waiting (opening the inbox), the workspace’s failed worker runs (showing Workers), the editor’s line, column, selection and language while a file is shown, the agent and model (a menu of the agents, as /agent lists them: each with its description and pinned model, the one working on the conversation marked; choosing one is SetAgent, as /agent <name>, so it takes over mid-conversation from the next turn, the history kept; at its foot Workspace settings…, Settings › Workspaces), the permission mode (a menu of the modes, with their meaning; bypass in red; a refusal because the sandbox is off is explained), the reasoning effort (a menu: Auto, Minimal … Max), the context in tokens with a meter against the compaction threshold (red past 85%), and the session’s cost with the last turn’s usage on hover. The parts of the page that know each fact publish it (status.ts: the workspace its settings, the conversation its usage, the editor its cursor). The line of usage under the composer is gone. Below 900 px the labels drop, keeping icons and numbers; below 640 px the cursor and workspace too.

• DSK-40 ~/.blitz/desktop.json (Prefs): theme (system|light|dark), density (comfortable|compact), width (full, the default: the conversation fills its panel; readable: a column of --content-width, 860 px), notifications (on|off), language (system or a language tag), files (the Files shelf expanded, else a rail), show_hidden, chat_width (0: a third of the window), files_width (0: 272 px), show_thoughts, active (a directory), and workspaces: every workspace the window has opened, each {dir, name, description, color, open}. Normalization: unknown values fall back to defaults; directories are cleaned, must be absolute, and appear once; open workspaces come first in tab order, then closed ones (at most 20, most recent first); active must be an open workspace, else the first open one.
• DSK-41 The rules for the list are pure functions (prefs.ts), unit-tested: opening a known workspace keeps its name, description and colour and shows it (opening an open one just shows it); closing moves it to the front of the recent ones and shows the tab after it (else before); a closed workspace can be forgotten (open ones can’t); open ones can be reordered. A workspace is shown by its name, else its directory’s last element.
• DSK-43 The host (pkg/pagehost PrefsStore) always sends workspaces as a list ([], never null), and the page normalizes whatever it loads (normalizePrefs, unit-tested: every field of the right type, else its default; workspaces without a directory dropped). An error while drawing the page shows “Something went wrong” with the details, Reload the window and Copy the details (an error boundary), never a frozen or blank window.
• DSK-42 Saving happens on every change, one save after another so the file ends with the latest.

• DSK-50 On start the page loads the preferences and asks ServiceStatus, showing a splash meanwhile. If the service isn’t running it explains that the service holds workspaces and runs scheduled workers and keeps running after the window closes, and offers Install and start the service (or Start the service when the login item exists); it then polls the status every 2.5 s until the service answers. Without a CLI it says to install Blitz’s CLI and run blitz service install.
• DSK-51 When any call fails with unavailable (the proxy’s answer when the socket doesn’t answer, or the service shutting down), a banner “The Blitz service isn’t answering. Reconnecting…” appears and the status is polled every 2.5 s; when the service answers again every open workspace reloads (sessions, settings) and a snackbar says “Reconnected”. The open workspaces and the one shown are kept throughout.
• DSK-51a The window talks to whatever service holds the socket, which may be an older install or one whose program has since been removed or replaced. Once the service answers (and after each reconnection) the page asks it GetServiceInfo (spec_service_021 SVC-06) and checks, with ProgramExists, that its program is still there. The service is stale when it’s too old to answer (“older than this app”), when its program is gone or was replaced since it started (replaced: a new build or package installed over it, which also tells development builds apart, all dev), or when its version differs from the app’s (Version()). A stale service gets a banner with Restart the service (RestartService: stop it, then install this app’s blitzd as the login item and start it; it waits up to 30 s for the expected version). Settings › Service shows the service’s version (since v0.7.1 only the service’s; the app’s is in About, and both are named only in the stale warning), the service program, and Restart and Stop while it runs. StopService(pid) stops the login item’s service (launchd bootout, systemd stop), else — or if it still answers — the process GetServiceInfo reported (SIGTERM, 15 s). The app manages the service itself through pkg/loginitem, with no CLI: it finds blitzd beside its executable (Blitz.app, the .deb), in its Bazel runfiles (bazel run), or on PATH; without one the buttons are off and the window says to reinstall Blitz. Rules in serviceVersion.ts, unit-tested; stopping a real blitzd by its process is tested.
• DSK-51b 2026-10-18 (a workflow run lost to a restart). Stopping the service stops the workflow runs going in it, so nothing stops it unasked: Restart (the stale-service banner, Settings), Stop and Reinstall first ask when runs are going (useStopGuard: how many, and which), and do nothing unless told to stop them. Start on the service-down screen looks again first and leaves a service that answers alone. Installing the same login item again (loginitem.Install: the same plist and loaded, or the same unit) only starts the service if it isn’t running (launchctl kickstart, systemctl --user start), never stops it; only another program in its place replaces it.
• DSK-52 Replaced 2026-10-02 by the Workspaces menu (DSK-65a). The workspace dropdown at the left of the top bar (2026-09-27 to 2026-10-02): the shown workspace’s avatar and name, its open and recent workspaces, Edit details, Close, Forget and Open workspace….
• DSK-53 With no open workspace: a welcome page with Open a workspace and up to six recent workspaces as cards, under a top bar with the app’s name, the workspace dropdown and Settings.
• DSK-54 Open workspaces stay mounted while another is shown (hidden, not destroyed), so a running turn keeps streaming and its approval waits.
• DSK-55 Closing a workspace: if a turn from this window runs in it, a dialog asks “Stop the turn and close?”; stopping aborts the turn and waits for it to end. The tab then closes (it moves to Recent), the service is asked to CloseWorkspace (a TURN_RUNNING refusal — another client’s turn — is ignored: the tab still closes and the service keeps the workspace), and a snackbar offers Undo (reopen).
• DSK-56 Replaced 2026-10-02. The workspace details dialog (name, description, colour, folder; Save/Cancel) is gone: those fields (WorkspaceFields.tsx) are the Workspace card of a workspace’s settings (DSK-85a), in its panel and in Settings › Workspaces, saved as they’re changed.

• DSK-36a Full screen: F11, ⌃⌘F on macOS, or Full screen in the command palette, toggles the window (the Electron window’s ToggleFullscreen; in a browser, the page). The window has no maximum size (the Wails app set MaxWidth/MaxHeight 16384, since Wails capped a Linux window at one monitor’s size).

• DSK-60 Settings (⌘, or Ctrl+, opens it) in the drawer (DSK-65c; since v0.7.0, a dialog over most of the window before): ✕, or Escape with the focus in it unless something inside used the key (such as the editor’s completion list), closes it, and settings apply as they’re changed, so there’s no Done. The sections are a list at its left, and a rail of their icons (their names in tooltips) when the drawer is under 600 px; a setting’s control goes under its description when the pane is under 520 px. Since v0.7.1 (the owner’s request) the sections are, in order: Providers & keys, Appearance, Agents, Skills, Workspaces, Permissions, Service, Logs, About, and Settings opens on Providers & keys (the gear, ⌘,). Its title bar holds Show advanced (a labelled switch, DSK-60a; its words hidden under 600 px) and, with advanced settings, Show the settings file (</>): Settings turns over, a quarter turn out and back in (at once with reduced motion), to the settings file (DSK-61) across its whole width, as a page’s source, and </> turns it back; what’s typed in the file is kept while turning back and forth, until Settings closes. The file is no longer a section, nor is Documents. Segmented choices in Appearance and Documents are all as wide as the widest (Segmented equal), and Appearance’s menus (the light and dark themes, the language) share a width. In sections: Appearance — theme (segmented System/Light/Dark with icons), Interface language (System, or one of the shipped catalogs by its own name), density, Conversation width (Full or Readable), Show thinking, Continue after background tasks, and Documents (Document styles…, a dialog: CSS for Markdown previews, per theme, spec_files_029 FIL-57); Providers & keys and the settings file (DSK-61); Permissions — the global permission rules and the built-in read-only rules (the form DSK-85 describes); Workspaces — every workspace the window knows with its avatar, name and directory, Forget for closed ones, and a pencil (Settings for …) that shows its settings in place, with a back arrow: for an open workspace the workspace settings form (WorkspaceSettingsForm, the panel’s, DSK-85a: every card, changes told to the window with configChanged, and Edit the settings file turning Settings over to its file); for a closed one how it’s shown (name, description, colour, folder) and Open (since 2026-10-02; project settings are reviewed from the form’s Project settings card, the bar above the conversation, or when a workspace opens with settings waiting for trust, spec_project_config_031 PRJ-33); Service — running or not, whether it starts at login (Install/Reinstall), the socket and the CLI path, Show in the system tray (a switch: SetTray, which runs the blitz-tray beside the app with --install or --uninstall, SVC-54; off, with a note, when there’s none); OS sandbox (Linux only: whether bubblewrap runs, SandboxStatus; Allow bubblewrap when AppArmor’s restriction stops it, FixSandbox, spec_shell_007 SH-20b, with the system’s password dialog, then the service restarted (RestartService, waiting for it) so what it opens next is sandboxed; the commands to run by hand when that fails). A workspace that didn’t open for want of the sandbox (its settings fail with SANDBOX_UNAVAILABLE) shows the same above its panes: why, Allow bubblewrap when AppArmor is the cause (the fix, then the restart, then the workspace reloaded), else how to install bubblewrap or set auto (SandboxNotice.tsx, sharing useSandboxFix with the row); Command line (the blitz beside the app and whether a new terminal finds it: CLIStatus asks the login shell, $SHELL -i -l -c, for its PATH, since the app’s own isn’t the terminal’s; when no blitz is on it, Install (InstallCLI) links the app’s into the first of ~/.local/bin, ~/bin or a writable /usr/local/bin on that PATH, else into ~/.local/bin, adding it to PATH in the shell’s startup file: .zshrc (under $ZDOTDIR if set), .bash_profile on macOS and .bashrc on Linux, fish’s conf.d/blitz.fish, else .profile; it replaces a stale link there but never a file; when a blitz is on PATH, this app’s or another’s, it says where, and since 2026-10-04 (the owner’s request) Reinstall (ReinstallCLI), for developers’ machines with links to old builds: it removes the dead blitz links in PATH’s folders, points the blitz link a terminal finds at this app’s (a new link renamed over the old, so there’s always one), and with none left links it as Install does; a blitz that’s a program, not a link, is left alone with a message; the note lists the dead links it removed; since v0.7.0, on Windows (the tray’s page and the Electron app), the app’s folder goes on the user’s PATH instead, worded so, spec_windows_036 WIN-14); Logs — the service’s log (LogViewer.tsx, SVC-06a): a day (Newest or one of the days there are), a level (All, Info, Warnings, Errors: that level and above), a search (every word, any field, as typing pauses), Refresh, Delete for a past day (canDelete in logs.ts: today’s is being written; a dialog confirms, then DeleteLogDay, SVC-06a, and the view goes back to the newest day), and in the app Open the folder (OpenFolder: only an existing directory, in the file manager); records newest first, each its time to the millisecond, level (errors tinted), message and fields, selectable; the file’s path above, and “the newest n of m” when the limit cuts them; “the log is off” when log.level is off; after installing, restarting or stopping it waits for the service to be running (or stopped), up to 15 s (“Waiting for the service…”, then an error if it doesn’t settle; waitForService), the version check gives up after 5 s, and the section refreshes every 5 s while open; About — the app’s version (Version(), the release’s tag), where its settings live, and Licenses / Third-party notices, which open the Licenses dialog (Notice, Apache License 2.0, Third-party notices; /license [full|third-party] in the composer opens it too). The agent’s settings are per workspace, in Workspaces (§13).

• DSK-60a 2026-10-02 (the owner’s request). Simple and advanced. The window starts simple (advanced in the preferences, false by default, so existing windows start simple too): it shows what a newcomer needs, and Show advanced (a switch in Settings’ title bar; until v0.7.1 the first row of Appearance) shows the rest. Hidden settings keep working with their defaults or what they’re set to: hiding never resets anything. What’s advanced (the larger choices in simpleMode.ts, unit-tested; the smaller where they’re drawn, with useAdvanced):

  • Settings sections: Documents, Permissions, Agents, Skills (spec_skills_013 SK-96, 2026-10-14), Settings file, Service and Logs (simple keeps Appearance, Providers & keys, Workspaces and About; a hidden section asked for opens Appearance). Since v0.7.1 the sections are in four groups, each under a heading in the side list (sectionGroups, shownGroups; a thin rule when the list is icons only; no headings in simple mode): Getting started (Providers & keys, Appearance), Global setup (Agents, Skills, Workers, MCP servers, Secrets: Studio’s order), Workspaces and access (Workspaces, Permissions) and System (Service, Logs, About).
  • Appearance: Chat input, Density, Transparency, Conversation width, Show thinking and Continue after background tasks (simple keeps the switch, Theme, Light theme, Dark theme, Interface language and Notifications).
  • Providers & keys: the sign-in choice (Google Cloud, an Anthropic account) with its fields, and Base URL, unless the provider already signs in some other way than an API key (showsSignIn).
  • A workspace’s settings: Behaviour’s Agency and Output style, and every card under Advanced settings (Thinking, Generation, API keys, Permission rules, Standing approvals, Project settings, Settings file, Context); simple keeps Workspace, Agent and model, and Behaviour’s Permission mode and Replies in.
  • Menu bar: the Studio menu (the Agents and Workers menus until v0.7.1, spec_studio_040 STU-01), and Changes’ Version control source (simple’s Changes is a button for this session’s).
  • Conversation: a prompt’s Rewind menu (Edit stays), Copy as Markdown and Copy the whole answer, Always allow on approvals, and a tool’s arguments and result.
  • Files and editor: the shelf’s Refresh, Collapse all and Show hidden files, the context menu’s Git actions and Copy relative path, and the editor’s Wrap long lines.
  • Changes: the This session / Git switch and Refresh.
  • Command palette: Show the workers.

  The status bar is the same in both.

• DSK-61 Settings and keys, through ConfigService (spec_service_021 SVC-35; the page never sees a key). Providers & keys (global) and a workspace’s API keys (its own, DSK-85) share one form (ProviderSettings.tsx): where keys are kept; the provider (global: the one set, Gemini when none is, as the service does; workspace: “Use the global setting” or one), default model and how the provider signs in are one change, on a card laid out a row at a time (provider and model; the sign-in; the sign-in’s fields; one column in a workspace’s settings) — Sign in with (segmented; a menu in a workspace’s settings) for Gemini (API key, Google Cloud ADC, or since 2026-10-04 Google account (OAuth): project and location fields for both) and Anthropic (API key, Anthropic account OAuth: an ant profile field, or Google Cloud ADC: Claude on Vertex AI, project and location fields), a note saying the sign-in happens on the service’s machine (gcloud auth application-default login, ant auth login) and, since 2026-10-04, above it the sign-in itself (SignInPanel.tsx; which one, signin.ts: adc and Claude on Vertex Google, oauth Anthropic, Bedrock AWS, Azure Entra ID, also shown when one of the cloud providers is configured): Signed in to … with its detail, or Not signed in, from GetSignIn; Sign in runs SignIn, streaming the tool’s progress (“Finish signing in in your browser”, Open the sign-in page for its URL, a device code in large type) with Cancel, then refreshes the model check; Sign out; when the tool isn’t installed, which one, and Get … (its install page). Signing in adds to the API key, which stays a choice, else its API key (a password field, “Leave empty to keep the current key” when there is one): nothing is saved until Save or Enter (SetProvider), Revert puts back what’s saved. The chosen provider’s form holds everything about it — there are no separate sections per provider, and no list of the other providers’ keys: with an API key, the key’s source as a chip — Keychain, Plain text and Obfuscated (in the error colour, with Move to keychain), Environment, Global (a workspace inheriting), Not set, Missing (a reference to a secret that isn’t there) — with a sentence saying what it means, and Remove for a key in this scope’s file; for Anthropic and OpenAI, the base URL (not in a workspace’s settings). The cloud providers (bedrock, azure, vertex-anthropic) are set in the settings file. Settings file (settingsfile/): the global file or a known workspace’s, in the Files view’s CodeMirror editor with TOML highlighting (⌘S saves, Revert), and its path. Completion comes from the settings reference, not the file’s words (settingsCompletions): in a header, the tables ([) or arrays of tables ([[); at a line’s start, the current table’s settings not yet set, each with its type, default and description, inserted as key = and going on to the values; after =, true and false for a boolean, else the default. A panel beside the editor describes the setting or table at the cursor (key, type, default, description; below it on narrow windows). Validate checks the text without saving (CheckConfigFile) and lists the problems below the editor, errors in the error colour, each with its line (a click goes there), and marks their lines in the editor, tinted, with a ✕ (error) or ! (warning) in a gutter beside the line numbers (the messages on hover); the first error’s line is shown. Save validates first and saves only without errors; warnings (unknown settings, plain-text keys, skill policy) don’t stop it. After an edit the list says it may be out of date. Hovering a key or a table’s name shows the reference’s entry (GetSettingsReference: key, type, default, description; findSetting matches quoted names to <model>-style keys and [[array]] tables to name[]), and Every setting (n) lists the whole reference, searchable by key and description (searchSettings). After any change open workspaces ask again whether their model works (configChanged → GetModel), and a model still unavailable is said in the form, until the next change; the conversation’s “model isn’t available” note has Check again, and while it shows, the window coming back into focus asks again (a sign-in made in a terminal); the conversation’s “model isn’t available” note says where to set a key.

• DSK-65 Laid out like an IDE (the owner’s request, 2026-09-27). The top bar is the window’s title bar (a drag region, inset for macOS’s window buttons): the app’s mark and name (⚡ Blitz) over the Files shelf, then the menu bar (DSK-65a) from the center panel’s left edge. Below it, left to right: the Files shelf (minimized to a rail with Show files and Go to file, which opens the command palette), the middle (the editor; since 2026-10-02 the changes, an agent or a worker open over it in a dialog, DSK-65b), the chat (always shown; its left edge drags its width, saved). With the editor chosen and no file open, the chat takes the middle (center stage, the owner’s request); opening a file moves it back to the side, and closing the last one brings it back — the same conversation, so a running turn carries on. Settings (agent, model, mode, effort) are loaded on open and after any change, turn or reconnection.

• DSK-65a 2026-10-02 (the owner’s request). The top bar is a menu bar (MenuBar.tsx), replacing the workspace dropdown, the view switch and the icon buttons. The brand sits over the Files shelf (.topbar-lead, after macOS’s window buttons, at least 120 px: the mark alone when narrower than 180 px), and the menus start at the center panel’s left edge (the editor’s, or the chat’s at center stage), measured as the shelf opens, closes, floats or is resized (Workspace.tsx, a ResizeObserver). From the left: Workspaces (below), Changes › Session (this session’s changes) or Version control (the Changes dialog on that source); Agents › Add agent, then the workspace’s agents (a click edits one in the agent dialog; a remove button, or Delete, asks to delete it); Workers › Add worker, Background runs (the inbox dialog, with how many go on or wait), then the workspace’s workers, each with its state and schedule (a click opens its dialog) and buttons on its row: Run and Disable for an enabled one, else Review and enable (shows it, its permissions and Enable: never enabled unseen), Edit (its dialog) and Delete (asks, then DeleteWorker) (workerActions, MenuItem.actions), its button badged with the runs going on (red while one waits) and a red dot for failed worker runs; Workspaces (first, since 2026-10-02) › Open workspace…, the open workspaces (each folder icon in its workspace’s colour, MenuItem.iconColor; the shown one marked, with “Waiting for you”, “Working” or failed runs; a click shows one; on the row, Settings for … (a pencil: Settings › Workspaces on it, DSK-85b) and Close), then up to eight recent ones (a click reopens, Forget), a red dot when another workspace waits; Help › User guide (the published guide, in the browser), Set up the agent harness, About Blitz. At the right: the search bar (DSK-78e) and Settings, an icon button for the global settings (⌘,; the dialog on Appearance). A workspace’s own settings are its workspace settings panel (DSK-85a). An open menu is in the highest surface. Lists are asked for when the workspace opens and each time their menu opens. The Agents and Workers menus ask their views through an intent (intent.ts: add, show, edit or delete an item, run or disable a worker, by path or name), and the dialogs have no list of their own. (Settings › Agents, which has no menu, keeps its list.) Under 1100 px the search bar folds to its icon; under 800 px the menus drop their chevrons. The welcome screen’s bar has the brand, Workspaces, Help, the search bar and Settings. A workspace’s settings also open from the status bar (the agent and model) and the command palette (Workspace settings).

• DSK-65b 2026-10-02 (the owner’s request). No views: the middle is always the editor (with no file open, the chat at center stage), and what the menus open slides over it in the drawer (DSK-65c; before v0.7.0, over it in a dialog that a click outside closed), so working on them never switches away from the editor. Changes (ChangesDrawer, edge to edge). Forms in dialogs share their look: labels in the same style whether Field’s or the worker form’s, and their buttons in the dialog’s footer (.dialog-actions): the Changes view (DSK-90), starting on the source the menu chose. An agent (AgentEditor with drawer, in the drawer since v0.7.0, laid out as the worker form: the drawer’s padding and scroll, Name and Description side by side, its buttons in the footer: where it’s saved, Delete, Revert or Cancel, Save): the agent form (DSK-91b), titled with its name, “Unsaved changes” beside the title; closing with unsaved edits, or another view taking the drawer, asks first (Discard); deleting it, or cancelling a new one, closes it. A worker (WorkerDrawer, in the drawer): two views in one drawer. The read view (what DSK-91 shows for a worker: its description, schedule, permissions, limits and runs; Run now, Enable/Disable, Edit, Delete; its state as a chip beside the title) and the edit view (the worker form, WorkerEditor, its Cancel and Save or Create in the dialog’s footer), switching in place in the same drawer (no second one opens); with unsaved changes in the form, ✕, Escape or another view taking the drawer asks first (Discard, or Cancel to keep editing): Edit opens the form, Cancel or saving goes back to the read view; Add worker starts on the form, and saving shows the new worker’s read view; Delete asks, then closes; deleting from the menu only asks. Run and disable from the menu open the read view and do it there (a run shows live). Opening a run’s conversation closes the dialog. The status bar’s changed files and failed worker runs, the command palette’s Show changes and Show workers, and a turn’s link to its changes open the same dialogs (showView: “changes” or “workers”; “editor” closes what’s open); without a name, the worker dialog shows the first worker whose last run failed, else the first. Opening a worker sees the workspace’s failed runs (BL-WK-11).

• DSK-65c Since v0.7.0 (the owner’s request: a click meant for the window, such as moving it by its title bar, closed Settings; and the forms wanted room). Panels stay put. The drawer (ui/Drawer.tsx): the views (Settings, the user guide, Changes, History, an agent, a worker, the background runs’ inbox, Licenses) slide down from under the top menu as a sheet over the window’s whole middle (the Files shelf, the editor, the chat and the pinned input, which steps aside while it’s up) to the status bar, clipped at the top menu’s edge so they come out from under it. The title bar and the status bar stay: the menus work (opening another view from them replaces the sheet’s), the title bar moves the window, and nothing outside the sheet closes it. Its header has the view’s icon, title, actions and ✕; its footer the view’s buttons. ✕, or Escape with the focus inside it and no dialog over it, closes it. Forms keep to a measure in it (Settings’ sections at the left and its pane up to 960 px; an agent, a worker, the inbox and Licenses up to 1,080 px, centred); Changes, History and the guide take its width. One at a time (DrawerClaims, unit-tested): a view that opens closes the one it replaces, or, when that one has unsaved changes (an agent’s or a worker’s form), asks first: Discard closes it, Cancel closes the new one and shows the old one again as it was (it stays mounted, hidden, while asked). Glass on, it’s a pane 8 px from the window’s edges, opaque (DSK-38). It focuses what asks for it (or its first field) when it opens and gives the focus back when it closes. Dialogs stay for short forms and questions (committing, a new branch or a merge, Rewrite with AI, the project’s settings, confirmations): Escape or their own buttons close them, never a click on the scrim, and a strip over the title bar (.scrim-drag) keeps moving the window while one is open. The command palette and search still close on a click beside them (pickers, like menus), and have the same strip.

• DSK-66 Files (spec_files_029 §5–6): the Files shelf on the left (minimizes to a rail), Go to file (⌘P, the rail’s search button, or the top bar’s search: the command palette’s files, DSK-78e), and the editor in the middle. Paths in tool calls, and inline code in answers naming a workspace file, open it (switching the middle to the editor).

• DSK-66a 2026-10-01. Welcome tiles and setup. A new chat’s welcome screen asks GetSuggestions and shows at most four tiles, worded in the window’s language (suggestions.ts, unit-tested): Set up this workspace for agents first and highlighted when the harness is missing (spec_memory_012 MEM-23); The specification changed: update the skills and agents when a spec is newer than them (MEM-44; sends /skills update); Continue “