Agent Bridge

Agent bridge

This page covers the opt-in in-app automation bridge, window.__CHEMDRAFT_AGENT__.

The bridge is a testing and automation surface, not a product API. It is off by default and has no promise of long-term compatibility. Prefer the MCP Server or Command-Line CLI for normal agent work, because those interfaces create files without driving an open application window.

Enabling it

In a packaged desktop runtime, only the native launch gate is authoritative. Start the application with either CHEMDRAFT_AGENT_BRIDGE=1 in its environment or the --chemdraft-agent-bridge argument. Browser-preview/debug use may instead request it with ?agentBridge=1 or set local storage key chemdraft.agentBridge to enabled.

Browser flags do not enable the bridge inside a desktop runtime. This prevents a page URL or renderer storage from turning on automation behind the explicit desktop launch gate. When it is enabled, the application installs window.__CHEMDRAFT_AGENT__; it removes that global when the relevant UI effect is disposed.

Interface at a glance

The bridge has version 1. snapshot() returns the document, active tool command ID, selection, page/object summaries, viewport, file dirty/path state, and runtime source. command(commandId) runs a registered command and waits for the UI to settle. resolvePoint() and hitTest() accept page/client coordinates or object, atom, and bond targets. Pointer methods are pointerDown, pointerMove, pointerUp, and pointerCancel; click() and drag() provide composed gestures. waitForIdle() waits for the render/interaction state to settle, and debugArtObject(objectId) reports an art debug result when available.

A point target can be a page or client coordinate, an object with an optional centre/corner anchor, a named atom, or a named bond with midpoint/from/to anchor. Snapshots are safer than scraping visual DOM state, but commands still use command IDs from the application registry. Do not invent IDs: use those confirmed by the installed build.

Synthetic event caveat

Pointer calls dispatch synthetic pointer events. They are useful for reproducible automation, but they skip browser default actions such as moving focus. A workflow that depends on focus, blur, native input behavior, or browser defaults therefore also needs a real-event test. The returned pointer-dispatch result includes whether the event’s default was prevented; that does not mean browser default behavior occurred.

Changes triggered through the bridge must follow the same document rules as any agent edit: use registered commands and patches, produce labelled undo entries, and leave changed objects selected. The bridge is not permission to reach into private React state, DOM internals, or unregistered functions.

A cautious automation pattern

First call snapshot() and record the document/page state that the task expects. Next run a known registered command with command(), or resolve an intended page-space target with resolvePoint(). Use click() or drag() only after checking the target with hitTest(), then call waitForIdle() and take a fresh snapshot. Verify object counts, selection, and the intended document change before continuing. If a command changes chemistry, use the same checks the application exposes to ordinary users; a visual gesture alone is not proof of identity.

drag() defaults to an interpolated gesture and supports a requested number of steps, constrained to a finite range. Pointer options include pointer ID, button state, click detail, and Shift, Alt, Meta, and Control modifiers. Their presence models input data; it does not make the browser carry out a native shortcut or focus transition. Automation should be particularly careful around floating desktop windows, native dialogs, file selection, clipboard access, and keyboard-focus workflows, because they are outside what synthetic canvas pointer events can faithfully prove.

If the global is absent, treat the bridge as disabled—do not attempt to turn it on from application JavaScript. In a desktop build, relaunch with the explicit environment variable or argument. In browser-preview/debug use, start with the permitted URL flag or local-storage value before the UI loads. Keep any scripts that use the bridge tied to bridge version 1 and verify them against the installed build.

Next

• Commands and Registry
• Agent Tools Overview
• Testing and CI