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, and MCP-backed blackboard workflow state.
• 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

From this repository root:

python -m pip install -e ".[dev,standalone]"

Use .[dev,standalone] for full local harness development. The standalone extra installs the optional AUTOMA-AI and Streamlit dependencies used by agent.py, ui.py, and tests that exercise the local A2A agent path.

Install the runtime package after it is published:

python -m pip install openstudio-ai
openstudio-ai install-runtime
OPENSTUDIO_PATH=/path/to/openstudio 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.

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. To run the standalone local AI app, install:

python -m pip install "openstudio-ai[standalone]"
python agent.py
streamlit run ui.py

Standalone mode requires 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:

python -m adapters.claude_code_adapter export-plugin \
  --output-dir /tmp/openstudio-ai-claude-plugin

python -m adapters.codex_adapter export-plugin \
  --output-dir /tmp/openstudio-ai-codex-plugin

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

python -m adapters.claude_code_adapter export-plugin \
  --output-dir /tmp/openstudio-ai-claude-plugin \
  --runtime-mode marketplace

python -m adapters.codex_adapter export-plugin \
  --output-dir /tmp/openstudio-ai-codex-plugin \
  --runtime-mode marketplace

Key Docs

• 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.