MutinyBIM

MutinyBIM is a browser-based building information modeling (BIM) engine. It is
built for many people and many AI agents editing the same model at the same
time. It is meant for every trade on a building project: architecture,
structural, civil, mechanical, electrical, plumbing, fire protection, the
general contractor, and the owner or developer who tracks cost.

The core idea is one shared kernel with trade add-ons on top. The kernel knows
elements, types, parameters, typed units, connected networks, spaces, phases,
sheets and commits. It does not know what a duct, a panel or a beam is. Each
trade is an add-on that plugs into versioned extension points. The add-ons in
this repository are built only through that contract, and tests hold them to
it.

MutinyBIM is open source under the Apache License 2.0. PermitZIP maintains it
and runs it in production in its own engineering work.

Start here: packages/bim-script/examples
has four short scripts that each build something whole: a small office, a
rooftop unit with its ducts, a plumbing riser and an electrical room. Run one
with npm run example -- rooftop-unit, or paste it to an assistant connected
to the tool server.

Status: early, and honest about it

This is the engine, not yet the full product.

In this repository now

• The engine: kernel, typed units, formulas, solid geometry, sync, sheets and
  PDF output, IFC 4.3 export, calculations, coordination lint, the firm
  library format, and the add-on contract.
• Trade add-ons: architecture, structural, civil, site, development (pro forma),
  electrical, mechanical, plumbing and gas, plus fire protection inside the
  first-party bundle.
• Viewers and UI kit: a plan editor, a 3D view, a theme and component kit, a
  virtualized data grid and schedule screens.
• The Building Model editor (packages/bim-editor): plan, 3D and sheet views,
  placing, routing and sizing, levels, spaces, schedules, notes, sheets,
  branches and versions. It runs in any app that implements the small host
  contract in packages/bim-editor-host, and ships with a standalone host.
• A dev server with the editor demo that runs in memory. No database, no Docker.
• The scripting kit, with the mutinybim-script run | check | pack command.
• The tool server (packages/bim-mcp): MutinyBIM's agent tools over the Model
  Context Protocol (MCP), on stdio or HTTP, for Claude, ChatGPT, Cursor and
  any other MCP client. Its main job is running the scripts an assistant
  writes. A local script runner (packages/bim-script-runner) comes with it,
  and every other tool family (parts, routing and fittings, electrical and
  plumbing, views, sheets and drafting, schedules, coordination) is an add-on
  pack in packages/bim-mcp-packs.
• The model server: one owner per model, durable commits in Postgres, live
  sync over WebSocket.
• The free hosted app is in apps/mutinybim-web: accounts, saved models,
  sharing, the editor, bring-your-own AI, and the tool server at /mcp that
  Claude, ChatGPT and Grok connect to by address (npm run web).
• A one-command local stack: docker compose up starts Postgres, the model
  server on its real Postgres store, a local sign-in and the editor pointed
  at that server.
• The performance gate: measured budgets for 250,000-element models, run on
  every pull request that touches the kernel, sync, viewers, editor or model
  server (docs/PERFORMANCE.md).

Not in this repository yet

• The editor screens that need a hosted app's data (saved preferences, a
  firm's part libraries, design limits, stored drawings, linked Revit models,
  code studies, file storage and a built-in agent). In the local demo they say
  "not available here"; the rest of the editor works.
• Model server sign-in for any provider, with built-in member roles. Today it
  verifies tokens from one configured sign-in service; the local stack brings
  its own, for one computer.

See ROADMAP.md.

Quick start

You need Node 22.13 or newer.

npm install
npm run demo

Open http://127.0.0.1:3095. The editor runs against an in-memory model on
the dev server. The first start builds the editor (about a minute); later
starts reuse that build. Open the same address in a second window with
&name=Priya added to edit together. Nothing is saved when you stop the server.

The full stack, with Docker

You need Docker with Compose v2.

docker compose up --build

Open http://localhost:3095/m/demo?view=plan. This time the editor talks to
the real model server, which keeps every edit in Postgres: stop the stack,
start it again, and the model is still there. Open a second window with
&name=Avery to edit together. The people who can sign in are You, Avery,
Priya and Sam (a local sign-in for one computer; never expose it).
docker compose down -v deletes the model. What each service does:
docker-compose.yml.

Other root commands:

npm test           # unit tests (Jest)
npm run typecheck  # TypeScript across the packages
npm run lint       # ESLint, including the boundary and license rules
npm run example -- rooftop-unit   # run an example script against a fresh model (packages/bim-script/examples)
npm run mutinybim-script -- run script.json --slice slice.json   # run a script against a model slice
npm run mcp        # the tool server on stdio, for an assistant to start (see below)
npm run mcp:http   # the tool server at http://127.0.0.1:3333/mcp
npm run perf:bim:ci    # the perf gate at 250k (MUTINYBIM_PERF_BUDGETS=relative on a busy machine)
npm run perf:suites    # the perf tests that build a full-size model, one at a time
npm run proof-packs -- origin/main HEAD   # the proof-pack commit rule over a range

BIM_DEV_PORT=3096 npm run demo starts the demo on another port.

Repository map

Package names use the @permitzip/bim-* prefix. Tagged releases publish
them to GitHub Packages (see docs/RELEASING.md). To
change the code, work in this workspace.

Foundations

Kernel

Services on the kernel

Add-on contract

Trade add-ons

Viewers and UI

Tools and servers

Architecture in one page

Layers, lowest first. A lower layer never imports a higher one. A test walks
every import and fails on a new violation or a new import cycle.

1. Units, formula and geometry.
2. The kernel.
3. Sync, sheets, IFC, calculations, lint and the library.
4. Add-ons, through the contract only.
5. Viewers and UI.
6. The dev server and the model server.

Every change to a model is an intent command (route_run, move_elements,
create_level, …). A client runs the command locally to preview it. The server
runs the same command again on the current model with its own code, checks for
conflicts with edits made since the client's base revision, and commits a
changeset. Everyone else receives the changeset. People and agents use the
same commands and the same checks.

More: docs/ARCHITECTURE.md,
docs/ADD-ON-CONTRACT.md,
docs/SCRIPTING.md,
docs/PERFORMANCE.md.

Working with AI assistants

MutinyBIM is agent-first. Connect Claude, ChatGPT, Cursor or any other MCP
client to the tool server and ask it to change the model:

npm run mcp:http    # or let your assistant start `npm run mcp` itself (stdio)

The tool server has a deliberately small tool list. Its main job is running
scripts: the assistant reads the kit's reference, writes a script, checks
it, runs it for a preview that changes nothing, and lands it after you
approve in your assistant. Walls, routes, equipment, circuits, sheets and
schedules are kit functions inside a script, not more tools, so the
assistant's context stays small however much the kit grows. Setup for each
assistant and a worked example: docs/CONNECT-AN-AGENT.md.

Assistants can also work without the tool server:

• Scripts on the command line. mutinybim-script runs a script against a
  slice of a model and checks the output.
• The sync protocol. A program connects to the dev server (or the model
  server) over WebSocket and sends the same commands a person's editor sends.
• The plugin standard. packages/bim-plugin describes the agent tools as
  an Agent Plugins 1.0 package: tool packs, skills and MCP server entries.

Agents never get more access than the person they act for. An agent edits
under its own name, tied to that person, and nothing lands until a person
approves it.

Contributing

We welcome contributions from engineers, architects, contractors, developers
and software people. You do not need to be added to the repository. Fork it,
open an issue, or send a pull request. Start with
CONTRIBUTING.md.

• A starting task: good first issue.
• Questions, ideas and show-and-tell go in Discussions. Bug reports and feature requests use the issue forms.
• Every commit needs a DCO sign-off (git commit -s). No other paperwork.
• Build on the shared kernel, never beside it. Trade logic goes in add-ons.
• Engineering calculations get the needs licensed review label and a review
  by a licensed professional in that discipline.

Please read Governance. Report security problems privately: see
SECURITY.md.

Engineering disclaimer

MutinyBIM is software, not engineering judgment. Built-in values and formulas
are labelled where they need checking for permit work, and licensed tables
(such as fitting loss databases) are not bundled. A licensed professional is
responsible for any design that relies on it.

License and trademarks

Code is licensed under the Apache License 2.0. See NOTICE
for third-party notices.

The MutinyBIM name and logo are trademarks and are not covered by the code
license. See TRADEMARKS.md.

Copyright 2026 PermitZIP.