Contributions should remain easy to run manually through BIMO Run Python and predictable enough for future AI-agent discovery through BIMO MCP.
- Choose an existing category or create a focused lowercase category folder.
- Add a descriptively named
lower_snake_case.pyfile. - Add a Markdown file with the same stem.
- Register the script in
catalog.json. - Run
python tools/validate_catalog.py. - Describe any Revit testing performed in the pull request. Do not mark an untested version as tested.
Existing files with historical naming are allowed to keep their paths so saved BIMO presets continue to work.
New scripts should:
- declare either
ironpythonordynamo-cpython3in the catalog; - use BIMO-provided Revit globals only when the selected engine supports them;
- read optional positional values from
INand document every index; - assign a concise value to
OUTfor predictable manual and MCP results; - validate required selection and inputs before changing the model;
- avoid modal prompts and hidden dependencies when preselection or
INcan be used; - open their own Revit transaction for model changes;
- roll back a started transaction when an operation fails;
- allow exceptions to reach BIMO so failed executions are not reported as successful;
- avoid secrets, credentials, machine-specific paths, and unrequested network access.
IronPython scripts intended for BIMO may use these globals:
| Global | Value |
|---|---|
__doc__ |
Active Revit Document |
__uidoc__ |
Active Revit UIDocument |
__revit__, __uiapp__ |
Active UIApplication |
__selection__ |
Active Revit selection object |
IN |
Positional input list |
OUT |
Script result assigned by the script |
The paired Markdown file must state:
- purpose and expected user outcome;
- engine and minimum Revit version;
- whether the script reads, writes, or deletes model data;
- active-document and selection requirements;
- every
INvalue, type, order, and default; OUTformat;- important limitations and a manual Revit test scenario.
read: inspects model state without intentionally changing it;write: creates or modifies model state;destructive: deletes elements or performs changes that are difficult to reverse.
Risk metadata is guidance for users and agents. It does not replace BIMO authorization, code review, backups, or Revit transaction safety.
Run:
python tools/validate_catalog.pyThe validator checks JSON syntax, required metadata, unique IDs and paths, paired documentation, catalog coverage for every script, and CPython-parsable syntax. It does not execute Revit API code or prove runtime compatibility.