Skip to main content
plugin CX Codex

contam-tools — Claude Code plugin: CONTAM workflows and setup

The contam-tools plugin connects an agent to a local CONTAM MCP server to inspect project files, run simulations, and review outputs. It fits workflows built around .prj models and ContamW.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install contam-tools@awesome-codex-plugins
Open on GitHub

What contam-tools does

Use the plugin to inspect .prj models, find broken external references, update supported file paths, and copy a baseline model into scenario folders. It can run contamx3.exe, collect outputs, compare .sim files, and export text from simread for review.

The package includes a Codex workflow skill, a local MCP server, and PowerShell scripts for project checks. The guard checks encoding and result settings, clears stale outputs, and performs basic count checks. ContamW workflows need GUI-safe result settings, so configure those before handing a project to someone else.

The toolkit is designed primarily for Windows. It can locate CONTAM executables and, when available, detect contamxpy bindings and ANT for Rhino/Grasshopper. An npx launch option is also provided for the MCP server.

What it helps with

  • inspect .prj references and project metadata
  • run ContamX and collect its output files
  • compare results stored in .sim files
  • prepare a project for ContamW checks
  • review XLog or simread text output

Example prompts for the agent

  • Inspect this .prj and summarize its references and date range.
  • Prepare this project for ContamW result review with GUI-safe settings.
  • Run this project and list the files it produces.

How to install contam-tools

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install contam-tools@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about contam-tools

How do I install contam-tools in Claude Code?

Add the plugin source with /plugin marketplace add hashgraph-online/awesome-codex-plugins, then install it with /plugin install contam-tools@awesome-codex-plugins.

What does contam-tools do?

It connects Claude Code and Codex to CONTAM through a local MCP server. The plugin checks .prj files, runs simulations, and helps review their outputs.

What should I set before opening a project in ContamW?

Run scripts/Invoke-ContamProjectGuard.ps1 in PowerShell with InputCheck mode and the GuiSafeResults profile. The toolkit is primarily designed for Windows.

Source text

CONTAM_plugin · MIT
# CONTAM Plugin

`CONTAM Plugin` is a Windows-first public toolkit for using CONTAM from AI coding agents and MCP-capable desktop tools.

It combines three layers in one repository:

- a local `stdio` MCP server for CONTAM command-line tools and ContamX bridge sessions
- a Codex plugin wrapper with workflow guidance for project creation, diagnosis, and simulation
- guard scripts for PRJ hygiene, ContamW-safe result settings, and optional `contam_chinese` linkage

The project is designed for public use. It helps an agent inspect `.prj` models, diagnose missing references, run simulations, compare outputs, generate simple ContamW SketchPad layouts, and separate solver failures from ContamW GUI result-display problems.

## Quick Use Through MCP

For most users, the easiest setup is an `npx`-launched local MCP server:

```text
command: npx
args: -y --package github:summer521521/CONTAM_plugin contam-mcp
```

The binary name remains `contam-mcp` because it launches the MCP server component. The repository and Codex plugin are named `CONTAM_plugin`.

Host-specific setup examples are in:

- [Host Setup Guide](docs/HOSTS.md)
- [Codex Windows App Setup](docs/CODEX_WINDOWS_APP.md)
- [Five-Minute Quickstart](docs/QUICKSTART.md)

## Codex Plugin Use

This repository can also be used as a Codex plugin source because the repository root contains:

- `.codex-plugin/plugin.json`
- `.mcp.json`
- `skills/contam-mcp/SKILL.md`
- `scripts/start-contam-plugin-mcp.ps1`
- `scripts/Invoke-ContamProjectGuard.ps1`

The plugin adds a CONTAM workflow skill that tells Codex to:

- inspect before editing
- keep case-specific data outside the plugin repository
- run ContamX input checks before GUI work
- keep only one active PRJ in a case folder unless scenarios are intentional
- use GUI-safe output settings when the user will run from ContamW
- record ContamW Building Check errors and fixes in case-local notes

## Main Capabilities

- discover bundled or configured CONTAM executables
- list `.prj`, `.sim`, `.wth`, `.ctm`, and related files
- inspect project metadata and external references
- diagnose broken project references
- update supported `.prj` file references
- clone baseline projects into named scenario folders
- create and optionally run small case matrices
- apply generated ContamW SketchPad layout data for rectangular rooms, zones, path icons, and source/sink icons
- run `contamx3.exe` and collect outputs
- run a PRJ guard for encoding, result profile, stale-output cleanup, XLog triage, and basic count checks
- discover and use optional `contamxpy` bindings for paper-style ContamX API co-simulation
- discover Rhino/Grasshopper ANT availability for model-creation workflows
- upgrade old `.prj` files with `prjup.exe`
- compare `.sim` files with `simcomp.exe`
- export `simread` text output
- summarize generic CONTAM text outputs for quick result triage
- start, inspect, advance, and close ContamX bridge sessions

## Project Guard

Before handing a generated PRJ to another user or asking someone to run it in ContamW, run:

```powershell
.\scripts\Invoke-ContamProjectGuard.ps1 `
  -ProjectPath "<case>\model.prj" `
  -Mode InputCheck `
  -ResultProfile GuiSafeResults `
  -CleanOutputs `
  -RequireSingleProject
```

For a command-line full run:

```powershell
.\scripts\Invoke-ContamProjectGuard.ps1 `
  -ProjectPath "<case>\model.prj" `
  -Mode Run `
  -ResultProfile GuiSafeResults
```

The guard does not prove a hand-drawn SketchPad layout is perfect, but it catches common project-sharing and simulation issues before the GUI step.

## Link With contam_chinese

`CONTAM_plugin` can use the localized executables distributed by [`contam_chinese`](https://github.com/summer521521/contam_chinese).

After extracting a `contam_chinese` release package, link it for the current PowerShell session:

```powershell
.\scripts\link-contam-chinese.ps1 -Path "<extracted-contam-chinese-release>"
```

Or persist it for your Windows user:

```powershell
.\scripts\link-contam-chinese.ps1 -Path "<extracted-contam-chinese-release>" -User
```

The launcher honors these variables in order:

- explicit tool overrides such as `CONTAMX_PATH`
- `CONTAM_HOME`
- `CONTAM_CHINESE_HOME`
- bundled executables in this repository

Use `contam_chinese` for localized ContamW and Chinese help. Use `CONTAM_plugin` for MCP automation, project checks, simulation workflows, and report-oriented result extraction.

## Repository Layout

- `.codex-plugin/`: Codex plugin manifest
- `.mcp.json`: MCP server launch definition for plugin hosts
- `skills/`: Codex workflow skill for CONTAM work
- `scripts/`: launch, guard, localization-link, setup, and maintenance scripts
- `contam-mcp/`: MCP server source, developer guide, and regression scripts
- `docs/`: public quickstart and host setup guides
- `.github/workflows/`: GitHub Actions workflows
- repository root: bundled CONTAM executables and supporting DLLs

## Privacy And CI

This repository includes a privacy check that scans tracked files for personal filesystem paths before public sharing:

```powershell
npm run privacy:check
```

Run the basic plugin launcher check with:

```powershell
npm run plugin:check
```

Run official regression cases with:

```powershell
npm run regression:official
```

## Example Prompts

- `Call discover_contam_installation and confirm CONTAM is available.`
- `List CONTAM case files in this folder.`
- `Inspect this PRJ file and summarize its references and date range.`
- `Run a test input only check for this PRJ.`
- `Make this PRJ safe for ContamW Building Check and result review.`
- `Run this PRJ and list the generated outputs.`
- `Apply a rectangular SketchPad layout to this PRJ so ContamW opens with visible rooms and icons.`
- `Run a small case matrix from this baseline model.`
- `Analyze this CONTAM xlog or simread text export.`
- `Discover whether contamxpy and ANT are available.`
- `Start a CONTAM bridge session for this project.`
- `Advance the active bridge session by 300 seconds and return path flow updates.`

## References

- [contam_chinese](https://github.com/summer521521/contam_chinese)
- [NIST CONTAM Download Page](https://www.nist.gov/el/energy-and-environment-division-73200/nist-multizone-modeling/software/contam/download)
- [NIST CONTAM Software Page](https://www.nist.gov/services-resources/software/contam)
- [NIST TN 1887r1](https://doi.org/10.6028/NIST.TN.1887r1)
- [Model Context Protocol](https://modelcontextprotocol.io/)

© summer521521 · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Science and research →

From the same set391

The whole set →
damnpdfs Connects 71 tools for PDFs, Office documents and images through a paired DamnPDFs browser tab. CX Codex ★ 1,596repo stars court-rules court-rules is a Claude Code and Codex plugin that searches US federal and state filing rules, judges’ standing orders, and court holidays. Results cite the court’s own documents. CX Codex ★ 1,596repo stars coolify This plugin connects Claude Code to Coolify Cloud or a self-hosted Coolify instance, letting the agent manage applications, view deployment history, check logs, and control environment variables through the Coolify API. CX Codex ★ 1,596repo stars context-pack context-pack generates a compact first-pass repository briefing for coding agents. It saves initial tool calls when exploring unfamiliar codebases. CX Codex ★ 1,596repo stars computer-usage-summary-skill computer-usage-summary-skill turns local ActivityWatch data into a daily report of app time, AFK, a timeline and foreground browser pages. Nothing leaves the machine. CX Codex ★ 1,596repo stars cometchat-skills Adds CometChat text chat, voice, and video calling skills to React, Angular, React Native, iOS, Android, and Flutter projects using the live Docs MCP. CX Codex ★ 1,596repo stars cohesivity Connect a coding agent to Cohesivity services for hosting, Postgres, email, and more through MCP or an API. CX Codex ★ 1,596repo stars codex-usage-tracker codex-usage-tracker is a Claude Code plugin that reads local Codex session logs for token summaries, session details, CSV exports, and dashboards. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open