> 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, enter your **workspace URL** (`<companyname>.openbrim.org`) and sign in.
2. Open (or create) a project. Keep this window open while you work with the agent.

## 3. Get your connection details

In the menu bar choose **Agent → Connect your AI agent…**. The dialog shows two things:

* **URL:** `http://127.0.0.1:8765/mcp`
* **Token:** a long secret string (treat it like a password)

Click **Copy config** to copy a ready-made configuration block (URL + token already filled in).

{% hint style="warning" %}
Your URL/token are unique to your install. Use the values shown in **your** app, not the examples below.
{% endhint %}

## 4. Connect Claude (Desktop / cowork)

Add the copied block to your `claude_desktop_config.json` (Claude Desktop → **Settings → Developer → Edit Config**), then **restart Claude**:

```json
{
  "mcpServers": {
    "openbrim-modeler": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:8765/mcp",
        "--header", "Authorization: Bearer <YOUR-TOKEN>"
      ]
    }
  }
}
```

After restarting, Claude shows the **openbrim-modeler** tools. Ask it to do something and it will drive the OpenBrIM Desktop window.

## 5. Connect Codex

Add the same server to your Codex `config.toml` under `[mcp_servers.openbrim]`:

```toml
[mcp_servers.openbrim]
command = "npx"
args = ["-y", "mcp-remote", "http://127.0.0.1:8765/mcp", "--header", "Authorization: Bearer <YOUR-TOKEN>"]
```

Restart Codex; it will pick up the OpenBrIM tools.

{% hint style="info" %}
Both clients use the same local server, so you can connect either one (or both). The OpenBrIM Desktop app must be **running with a project open** for the tools to work.
{% endhint %}

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

## 7. 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 the app is running with a project open, you restarted the agent after editing its config, and the token matches the one in **Agent → Connect your AI agent…**.
* **"unauthorized" / 401** — the token is wrong or missing from the `Authorization: Bearer` header.
* **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 current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
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.