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.

Current Capabilities

• 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.
• Learning contracts for candidate drafting; host plugins do not persist candidate records yet.
• 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.

Development Setup

New contributors can choose a reproducible Python 3.12 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 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 Python 3.12+ development environment:

uv sync --project standalone
uv run --project standalone python standalone/agent.py
uv run --project standalone streamlit run standalone/ui.py

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

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

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.

Key Docs

• Multi-lab Assessment and One-month Plan
• Harness Details
• Packaging North Star
• Runtime Installation Contract
• Marketplace Install Guide
• PyPI Release Guide
• Developer Guidance

Runtime State

Local runtime state is intentionally ignored by Git:

• .openstudio_mcp_workspace/
• .openstudio_ai_blackboards/
• logs/
• outputs/

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