AI Agent Integration

Since 2.3.0, MultiProg ships an IPC bridge that lets an external AI agent (Claude, Cursor, GLM, opencode, or any MCP-capable client) drive the same Lua scripting engine that powers the in-app Script Console. The agent drops a request file into a folder, MultiProg runs the Lua, and writes a result file back — all over plain JSON files, no sockets.

This is the same mp.* API surface the in-app console exposes (see Scripting) — programming, hex buffer, file I/O, target database, checksums.

Settings dialog Settings → AI Agent Integration with the Enable checkbox, IPC folder path, Auth token row (Show / Copy / Regenerate) and the Copy starter prompt for external agent button visible.

When ready, replace this admonition with: ![AI Agent settings](/img/mp_settings_ai_agent.png) :::

Where to find it

Settings → AI Agent Integration opens the configuration dialog. Everything you need lives there.

Settings dialog

• Enable Agent IPC bridge — master toggle. When unchecked, requests dropped into the folder are ignored.
• IPC folder — the directory MultiProg watches. Default lives under the user profile; Browse…, Open folder and Copy path buttons make it easy to point your agent at the right place.
• Auth token — 64-hex-character per-user token, mandatory on every request. Buttons: Show / Hide, Copy, Regenerate. Regenerate revokes any client still using the old value.
• Copy starter prompt for external agent — generates a ready-made briefing (paths, auth token, protocol pointers) and copies it to the clipboard. Paste into your agent of choice, append your task, send.
• Apply / Close — Apply reconciles the runner state at runtime; no restart needed.

The token is stored at %APPDATA%/KuragaTech/MultiProg/agent_token (NTFS-restricted to the current user). Treat it as a session secret — never commit it to source, never echo it back in agent replies.

CLI flags and environment overrides

There are two ways to force-enable the bridge from outside the GUI:

• --agent-mode command-line flag — starts MultiProg with the bridge on at the default IPC path and with destructive backend ops (write / erase / flash) blocked by default. A script that needs hardware writes opts in explicitly with mp.app.allow_hw_writes(true). In --agent-mode the dialog locks all controls (read-only banner).
• MULTIPROG_AGENT_IPC_DIR environment variable — overrides the IPC folder path. Useful for CI pipelines. The dialog locks the path field and shows the active value.

Override precedence (high → low):

--agent-mode  >  MULTIPROG_AGENT_IPC_DIR  >  persisted prefs

What ends up in the IPC folder

Once the bridge is running, MultiProg auto-populates the folder with:

File	Direction	Purpose
AGENT_README.md	MP → agent	Authoritative protocol reference. Auto-regenerated on every launch. Read this first.
agent_request.json	agent → MP	Next request to run. Write .tmp then rename for atomic delivery.
agent_result.json	MP → agent	Result of the last request.
agent_stream.log	MP → agent	Live mp.log.* stream during long-running scripts (tail this).
agent_token	shared secret	Per-user 64-hex auth token. Stored in %APPDATA%/KuragaTech/MultiProg/, not in the IPC folder.
session.lock	MP-internal	Prevents two MultiProg instances racing on the same IPC dir.

Quick start

1. Open Settings → AI Agent Integration.
2. Enable the bridge, pick (or accept) the IPC folder.
3. Click Copy starter prompt for external agent.
4. Paste it into your AI client (Claude Code, Cursor, opencode, GLM, any MCP-capable agent), append the task you want done, send.

The starter prompt instructs the agent to:

• read AGENT_README.md for the protocol;
• introspect the live API by sending print(mp.utils.json_encode(mp.app.api_surface()));
• always include auth on every request, including cancel and op:"quit";
• set timeout_ms on every request (the default watchdog is 10 minutes);
• tail agent_stream.log for long ops instead of polling the result;
• avoid mp.ui.* modal dialogs in autonomous mode.

How it relates to the in-app Script Console

• Same Lua engine, same mp.* API surface — anything you can do in the Script Console you can do over IPC.
• The Script Console runs scripts you type in the GUI; the IPC bridge runs scripts your agent submits as files.
• Only one script runs at a time. While the Console is busy, IPC requests get reason:"busy" and should retry; same in reverse.

Safety

Trust boundary

Any process able to write to the IPC folder can run code as MultiProg. Pick a path only you control. The 64-hex auth token keeps the protocol authenticated, but folder write permission is the actual trust boundary — once a request file lands, MultiProg will read the auth field and accept it if it matches.

• The agent token is stored under %APPDATA%, where NTFS DACLs restrict it to your user.
• --agent-mode blocks destructive ops by default; a script must explicitly opt in via mp.app.allow_hw_writes(true) to flash hardware.
• Erase always asks the user. mp.backend.erase and mp.backend.erase_blocks raise a synchronous GUI confirmation modal on every call ("Script requested mp.backend.erase() on target XXX — Allow this erase?"), even after mp.app.allow_hw_writes(true) and even outside --agent-mode. There is no override flag. Erase wipes calibration / serial / pairing data that may not live in your HEX, so it requires a human at the keyboard. The dialog blocks the request until the user answers; cancelling returns {false, "erase canceled by user"}. The bridge logs [QT-WARN] mp.backend.<op>: GUI confirmation modal raised — … to agent_stream.log the moment the dialog pops, so a tailing agent sees the cause of the apparent freeze. Plan your agent flow with a human in the loop, or skip erase.
• Standard Lua os.* and io.* libs are sandboxed inside the engine — scripts use mp.file.*, mp.app.list_dir, mp.app.run_process for any filesystem / process work.
• Cancelling: send { "id": <next>, "auth": "<token>", "cancel": true } to stop an in-flight script.
• Quitting: send { "id": <next>, "auth": "<token>", "op": "quit" } to ask MultiProg to shut down cleanly. The bridge writes one last result file (reason: "quitting") before the app exits.

Full protocol reference

The complete request / response shape, every reason value, the "buffer vs device" model, autonomous-mode discipline, cancel semantics, streaming, and corner cases live in the AGENT_README.md file that MultiProg writes into the IPC folder on every launch. It is the authoritative reference — start there if you are writing a client.

For the Lua API itself, see the Scripting section and API reference.