Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Drive OpenBrIM with an AI Agent (Desktop App)

The OpenBrIM Desktop app wraps the OpenBrIM web app in a desktop window and runs a small local server that an AI agent — Claude (Desktop / cowork) or Codex — can connect to. The agent drives your model with the same actions you do in the UI (create objects, set parameters, run analysis, read results, export, …) while you watch and review each step in the live 3D window.

The server runs only on your own machine (127.0.0.1) and is protected by a token. The agent is a client that connects to it — nothing is exposed to the internet.

1. Install the app

  1. Download the latest installer from the Releases page (OpenBrIM-Desktop-Setup-x.y.z.exe).

  2. Run it. The app updates itself automatically when a new version is released, so you only install once.

2. First run — open a project

  1. On first launch, the app asks for your workspace URL. It suggests openbrim.org; keep it, or enter your company's workspace (<companyname>.openbrim.org). Then sign in.

  2. Open (or create) a project. Keep this window open while you work with the agent.

3. Open the connection dialog

In the menu bar choose Agent → Connect your AI agent…. The dialog has one tab per AI app — Claude Desktop, Claude Code, Codex and Other apps — each with numbered steps. Pick the tab for the app you use.

You do not need to install anything else — not even Node.js. Every option runs on software that is already on your machine: the AI app's own runtime, or the one built into OpenBrIM Desktop.

4. Connect Claude Desktop

  1. On the Claude Desktop tab, click Add to Claude Desktop.

  2. Claude opens its own install window. Click Install.

  3. Start a new chat in Claude and ask about your model — for example, "What objects are in my OpenBrIM model?"

If Claude Desktop is not installed (or is too old to install extensions), the dialog says so and offers a Get Claude Desktop button. Install it, then click Add to Claude Desktop again.

If nothing opens, click Show file in the dialog. In Claude, go to Settings → Extensions → Advanced settings → Install Extension… and choose that file.

Connected OpenBrIM to Claude before by editing its configuration file? Remove that openbrim-modeler entry from claude_desktop_config.json, or the tools are listed twice.

Don't use Claude's "Add custom connector". Custom connectors are reached from Anthropic's servers over the internet, so they cannot see the OpenBrIM server on your own computer. Use Add to Claude Desktop instead.

Prefer to edit Claude's configuration yourself?

  1. In Claude, open Settings → Developer and click Edit Config. Claude shows claude_desktop_config.json in File Explorer — open it in Notepad.

  2. Open Prefer to edit Claude's configuration yourself? on the Claude Desktop tab and click Copy. If the file is empty or holds only {}, replace its contents with the copied block. Otherwise copy just the "openbrim-modeler" part into the existing "mcpServers", keeping the servers already there. Save the file. The block looks like this, with your own install path and token filled in:

  3. Quit Claude completely (right-click its icon in the taskbar tray → Quit) and open it again.

5. Connect Claude Code

  1. On the Claude Code tab, click Copy and run the command in a terminal (PowerShell or Command Prompt):

    --scope user makes OpenBrIM available in every folder you use Claude Code in. If you added it before, run claude mcp remove openbrim-modeler --scope user first.

  2. Start a new Claude Code session and type /mcp — openbrim-modeler should be listed as connected.

6. Connect Codex

This works for the Codex app, the Codex CLI and the Codex extension for VS Code, which all share one settings file (%USERPROFILE%\.codex\config.toml).

  1. On the Codex tab, click Add to Codex. The dialog adds the OpenBrIM entry to Codex's settings file and changes nothing else. It saves a dated backup of the previous file (config.toml.openbrim-backup-<date>) first. If the file is laid out in a way the dialog can't edit safely, it changes nothing and asks you to add the entry by hand (below).

  2. Restart Codex — quit and reopen the Codex app, choose Restart extension in VS Code, or start a new codex session in the terminal.

If the dialog says it cannot find Codex's settings folder, open Codex once so it creates the folder, then try again.

Prefer to edit Codex's settings yourself?

On the Codex tab, open Prefer to edit Codex's settings yourself?, click Open config.toml, and paste the copied block at the end of the file. Replace any existing [mcp_servers.openbrim] and [mcp_servers.openbrim.env] sections. It looks like this:

tool_timeout_sec = 600 gives long operations such as analysis time to finish. Codex's default is 60 seconds.

Codex starts OpenBrIM's small bridge program (a STDIO server) through the OpenBrIM Desktop app itself, so nothing else needs to be installed. Save the file and restart Codex.

Codex running inside WSL keeps its settings in the Linux home folder, which this does not reach. Use Codex in Windows mode.

7. Other AI apps

Any app that can connect to an MCP server over HTTP can use the Other apps tab: it shows the server URL (http://127.0.0.1:8765/mcp), the token (send it as the header Authorization: Bearer <token>), and a ready-made JSON block. An app that can only start a program can use the Claude Desktop configuration instead.

Your token is unique to your install and works like a password. Always copy it from your app rather than from the examples on this page.

Both Claude and Codex (and several apps at once) can be connected to the same OpenBrIM app. It must be running with a project open for the tools to work.

8. Use it

Just ask in plain language. The agent picks the right tools and you see each change in the live window; model-changing actions also return a screenshot in the chat. Examples:

  • "Open a new steel I‑girder bridge template and add a superstructure and substructure."

  • "List the support lines, then set the second one's station to 150 ft."

  • "Validate the model, fix any issues, then analyze it."

  • "Show me the deformed shape for the girder stage and report the maximum displacement."

  • "Export the model to STAAD and Excel."

  • "List the project revisions and revert to the one from this morning."

What the agent can do, grouped. Each row lists the kind of work it can carry out for you.

Projects & templates

  • Browse and open projects — list your projects and recently opened ones, and open any of them by name.

  • Start from a template — list the available New‑Project templates (steel I‑girder, tub girder, concrete U‑girder, …) and create a new project from one, optionally overriding the template's default parameters.

  • Follow the workflow — read the project's workflow steps in order (the intended input sequence) and work through them one item at a time, including each item's documentation link.

Build & edit the model

  • Inspect before editing — list objects (optionally filtered by type), read any object's parameters (expression + evaluated value) and children, and look up an object type's input schema (what inputs it needs, their units, and what its references point to) before creating it.

  • Create, edit, delete — add objects exactly the way the spreadsheet's "new row" does, set one or many parameters, and delete objects. Every model‑changing action recompiles and returns a screenshot for review.

  • Bulk / rebuild — run many create/edit/delete operations under a single recompile to build or rebuild a model quickly.

  • Units handled correctly — the agent reads the project's internal units and converts your real‑world values (e.g. 100 ft, 90°) before writing them, so geometry lands where you expect.

  • Undo / redo / recompile — step changes back and forth and force a redraw.

Materials & sections (from the shared library)

  • Import standard materials — search the shared material databases (concrete grades like Fc_4ksi, steel grades like A709_50, AASHTO grades) and import the one you pick into the project so objects can reference it by name.

  • Import standard sections — search the section/shape databases (AISC rolled shapes such as W36, HSS, plus beam/box/girder databases) and import a chosen shape into the project.

Import external geometry

  • LandXML — import a LandXML file (horizontal/vertical alignments and surfaces) straight from disk into the model.

Generators

  • Run generative objects — list the template's generative objects and run one to emit a whole sub‑assembly in a single step: e.g. multi‑column bent, hammerhead pier, straddle bent, pile cap, the steel/concrete code‑check generators, and the construction & loading (staged‑construction) generators. The agent first reads each generator's exact inputs, then generates.

Validation & errors

  • Check the inputs — read the project's validation issues (the same list the Validation Issues panel shows) after setting parameters, so problems get caught and fixed.

  • Surface generation errors — read (and clear) the generation/render errors that would otherwise pop the blocking "Uh, Houston…" dialog, then fix the offending object.

Analysis, design & results

  • Analyze — run the FEA analysis and wait for it to finish.

  • Design — run the design‑code checks and report PASSED/FAILED, then open or read the detailed design report.

  • Explore results visually — list the analysis cases (load cases, combinations, eigen modes, and staged‑construction stages), switch the FEA view to a case, and view its deformed shape, loading, forces or stresses.

  • Read result values — pull the actual numbers — nodal displacements, support reactions, line/member forces, shell forces, FE composite forces — for any case or construction stage, in display units (the same numbers the FEA spreadsheet/Excel export show).

  • Screenshots — capture the full window or just the clean 3D/FEA canvas, switch between Model / FEA / CAD / Documents views, and zoom‑to‑extents to frame the whole model.

Revisions

  • History — list the project's server snapshots, compare two revisions (added/deleted objects and changed parameters), and revert to an earlier one.

FE core (raw finite‑element modeling)

  • Build elements directly — create FE nodes (with supports: fixed / pinned / roller / explicit DOF springs), line elements (beam, truss, tension/compression‑only, cable), shell surfaces (tri/quad), and springs (support or link).

  • Loads & cases — create analysis load cases (with AASHTO load types and optional self‑weight) and add nodal forces/moments.

  • Whole‑model build & templates — build an entire FE model in one recompile, list the FE core objects, or drop in a ready‑made analyzable template (simply‑supported beam, portal frame, truss).

Export

  • Interchange & analysis files — export the project to STAAD, SAP2000, CSiBridge, Midas, OpenSees, LARSA, OBJ, glTF, DXF (2D/3D), Tekla, IFC, DGN, or Excel. Files are written to your Documents/OpenBrIM Exports folder. (Analyze first if you want an export that reflects results.)

9. Review every step (recommended)

Each model‑changing action triggers your agent's approval prompt before it runs, and returns a screenshot afterward — so you stay in control. Don't blanket‑"always allow" the mutating tools; review them as they come.

Troubleshooting

  • No OpenBrIM tools in the agent — make sure OpenBrIM Desktop is running with a project open, and that you restarted the agent after connecting it.

  • "cannot reach the OpenBrIM desktop app … Is the app running?" — OpenBrIM Desktop is closed. Open it (with a project loaded) and try again.

  • "unauthorized" / 401 or "rejected this connection" — the token is stale or wrong. Open Agent → Connect your AI agent… and connect the app again from its tab.

  • The dialog warns that port 8765 was busy — another program (often a second copy of OpenBrIM) was using the port when OpenBrIM started. Close it and restart OpenBrIM; agents connected earlier then reach it again.

  • Tools call but nothing happens — a project must be loaded in the window; open one first.

PreviousCulvert Analysis Results [BC]
NextParametric Bridge Engineering

Last updated