OpenStudio AI Harness

OpenStudio AI Harness packages a local MCP runtime, host adapters, skills, knowledge, and workflow-state tools for AI-assisted building-energy modeling.

• OpenStudio MCP server for model lifecycle, simulation, results, SDK lookup, runtime storage, MCP-backed blackboard workflow state, and downloadable self-contained OSM geometry viewers.
• Claude Code plugin export.
• Codex plugin export.
• Opt-in, user-local learning evidence and review-gated personal lessons shared by Claude Code and Codex through MCP; the CLI curates candidates and detects repeated scripts as candidate measures. “Opt-in” means explicit learning-tool invocation, not a runtime enable/disable setting.
• HVAC workflow skills and generated child skills.
• Reviewed OpenStudio SDK knowledge packs.
• Packaging north-star plan for stable pip install and marketplace agentic installation paths.

New contributors can choose a reproducible Python 3.10 Dev Container or a manual standard/full environment. The full path installs the separately locked AUTOMA-AI and Streamlit development project; the standard path is sufficient for harness, MCP, adapter, skill, packaging, and documentation work. Follow the Developer Guide environment setup for the complete onboarding steps.

For a short guide to repository access, folder ownership, plugin exports, and a focused contribution check, see Contributing.

For a manual standard setup from this repository root:

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
python -m playwright install chromium

The production harness supports Python 3.10 or newer. The dev extra installs its test and release tools.

Install the runtime package after it is published:

python -m pip install openstudio-ai
openstudio-ai install-runtime
openstudio-ai doctor
openstudio-ai-mcp --transport stdio

OpenStudio AI requires both the PyPI openstudio Python package, installed as a dependency of openstudio-ai, and the native OpenStudio application/CLI. Set OPENSTUDIO_PATH when the CLI is not on PATH or when selecting a specific installation. Alternatively, after confirming the executable, save it for future Claude Code and Codex MCP launches with:

openstudio-ai configure-openstudio --path /path/to/openstudio

openstudio-ai doctor reports core plugin readiness only when the Python runtime, MCP command, native OpenStudio executable, and plugin compatibility are ready for energy modeling. Optional integrations such as NLR OpenStudio-MCP are reported separately and do not block core readiness. NLR discovery accepts openstudio-mcp in Codex or Claude project configuration. Detection means configured; verify NLR status/version through the connected server before modeling. PNNL’s foundational MCP advertises openstudio-ai-mcp and uses the host connection name openstudio_ai.

The base package is the recommended install for Claude Code, Codex, and other marketplace-style host integrations. It intentionally does not install AUTOMA-AI or Streamlit. The standalone local AI app is a separate optional development environment that also supports Python 3.10+:

uv sync --project standalone
uv run --project standalone streamlit run standalone/ui.py --server.port 8504

Standalone mode requires Python 3.10+ and user-provided LLM configuration, such as API keys or model endpoint settings, in the local environment.

For a browser-ready containerized demo, use docker compose --profile standalone up --build standalone and open http://localhost:8504. See standalone/README.md for the optional host-port override and environment setup.

Run focused tests:

python -m pytest -q \
  tests/test_mcp_openstudio_smoke.py \
  tests/test_openstudio_sdk_docs.py \
  tests/test_openstudio_learning_pipeline.py \
  tests/test_openstudio_codex_adapter.py \
  tests/test_openstudio_claude_code_adapter.py

Start the MCP server in stdio mode:

openstudio-ai-mcp --transport stdio

Curate local learning outside an active modeling session:

openstudio-ai learning curate
openstudio-ai learning propose-measures
openstudio-ai learning prune-preview

These commands never approve a candidate or delete one without explicit user action.

Export local development plugins:

openstudio-ai export claude \
  --output-dir /tmp/openstudio-ai-claude-plugin \
  --runtime-mode local

openstudio-ai export codex \
  --output-dir /tmp/openstudio-ai-codex-plugin \
  --runtime-mode local

Export marketplace-oriented plugins that expect an installed runtime command:

openstudio-ai export claude \
  --output-dir /tmp/openstudio-ai-claude-plugin \
  --runtime-mode marketplace

openstudio-ai export codex \
  --output-dir /tmp/openstudio-ai-codex-plugin \
  --runtime-mode marketplace

Export a publishable repository containing both host packages, generated install guides, and source provenance:

openstudio-ai export marketplace \
  --output-dir /path/to/openstudio-ai-plugins \
  --runtime-mode marketplace \
  --force

This produces a generated release tree; it validates both exports before completion. Keep the harness repository as the source of truth and do not edit generated plugin files directly.

For development exports from this checkout, use .venv/bin/openstudio-ai (or activate the repository virtualenv) so the command uses the current adapter code. An older pipx-installed command can combine older generated setup/helpers with this checkout's skill files; --workspace-root selects assets, not the installed exporter code. Both exports configure PNNL as openstudio_ai launching openstudio-ai-mcp; NLR setup uses openstudio-mcp. PNNL workflow records use nlr_openstudio as their stable provider identifier, separate from the host connection name.

After installing the Codex marketplace plugin, add the shared OpenStudio modeler policy to each Codex project that should route plain-language OpenStudio requests through the workflow orchestrator:

openstudio-ai install codex --target-dir /path/to/codex-project

This creates AGENTS.md when it does not exist. Use --dry-run to preview; an existing unmanaged AGENTS.md requires --force before the managed block is appended.

• Contributing
• Multi-lab Assessment and One-month Plan
• Harness Details
• Packaging North Star
• Runtime Installation Contract
• Marketplace Install Guide
• NLR OpenStudio-MCP in Claude Desktop
• PyPI Release Guide
• Developer Guidance

Local runtime state is intentionally ignored by Git:

• .openstudio_ai_mcp_workspace/
• .openstudio_ai_blackboards/
• logs/
• outputs/

The MCP runtime uses local SQLite metadata and filesystem workspaces for large OSM, SQL, and log artifacts.