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

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:

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

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

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