> For the complete documentation index, see [llms.txt](https://docs.openbrim.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openbrim.org/quick-guides/drive-openbrim-with-an-ai-agent.md).

# 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**.

{% hint style="info" %}
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.
{% endhint %}

## 1. Install the app

1. Download the latest installer from the [**Releases** page](https://github.com/openbrim/desktop-releases/releases/latest) (`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.

{% hint style="info" %}
**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.
{% endhint %}

## 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.

{% hint style="warning" %}
**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.
{% endhint %}

<details>

<summary>Prefer to edit Claude's configuration yourself?</summary>

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:

   ```json
   {
     "mcpServers": {
       "openbrim-modeler": {
         "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\OpenBrIM Desktop\\OpenBrIM Desktop.exe",
         "args": ["C:\\Users\\<you>\\AppData\\Local\\Programs\\OpenBrIM Desktop\\resources\\app.asar.unpacked\\mcp-bridge.js", "http://127.0.0.1:8765/mcp"],
         "env": { "ELECTRON_RUN_AS_NODE": "1", "OPENBRIM_MCP_TOKEN": "<YOUR-TOKEN>" }
       }
     }
   }
   ```
3. Quit Claude completely (right-click its icon in the taskbar tray → **Quit**) and open it again.

</details>

## 5. Connect Claude Code

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

   ```
   claude mcp add --scope user --transport http openbrim-modeler http://127.0.0.1:8765/mcp --header "Authorization: Bearer <YOUR-TOKEN>"
   ```

   `--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.

<details>

<summary>Prefer to edit Codex's settings yourself?</summary>

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:

```toml
[mcp_servers.openbrim]
command = "C:\\Users\\<you>\\AppData\\Local\\Programs\\OpenBrIM Desktop\\OpenBrIM Desktop.exe"
args = [ "C:\\Users\\<you>\\AppData\\Local\\Programs\\OpenBrIM Desktop\\resources\\app.asar.unpacked\\mcp-bridge.js", "http://127.0.0.1:8765/mcp" ]
tool_timeout_sec = 600

[mcp_servers.openbrim.env]
ELECTRON_RUN_AS_NODE = "1"
OPENBRIM_MCP_TOKEN = "<YOUR-TOKEN>"
```

`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.

</details>

{% hint style="info" %}
Codex running **inside WSL** keeps its settings in the Linux home folder, which this does not reach. Use Codex in Windows mode.
{% endhint %}

## 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.

{% hint style="warning" %}
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.
{% endhint %}

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openbrim.org/quick-guides/drive-openbrim-with-an-ai-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.