Vulcan Analyst

Vulcan Analyst is a command-line assistant for working through a Vulcan Home Energy Model workspace. It can inspect model inputs, validate geometry, review thermal bridges, summarise batch results, and ground answers in Vulcan documentation and approved source references.

Analyst is experimental. It is intended to assist an assessor, not replace assessment judgement. Review any answer that affects compliance, lodgement, or design decisions against the underlying Vulcan files and calculation results.

Requirements

• Node.js 22.19.0 or newer.
• npm available in the same terminal.
• A Vulcan workspace created by the browser app.
• A vulcan-mcp-config.json file in that workspace.
• A model connection available in Vulcan Analyst.

Create the workspace config file in Vulcan from Profile -> Integrations by clicking Generate Config File. The same file is used for Vulcan tools and Analyst. It is valid for about 30 days.

Install

Analyst is shipped through npm, so the terminal must be able to see Node and npm:

node --version
npm --version

Analyst requires Node 22.19.0 or newer. If either command is missing, or Node is older than 22.19.0, install or update Node.js first and open a new terminal.

For the smallest install surface, run Analyst directly from npm:

npx --yes @vulcan-energy/analyst@latest

If Vulcan access is missing, Analyst starts setup immediately. It uses the workspace vulcan-mcp-config.json when present. If terminal chat asks for model credentials, use /login inside Vulcan Analyst. doctor remains available for support diagnostics; it is not part of the normal first run.

For repeated use, install the CLI globally:

npm install -g @vulcan-energy/analyst

Start

Run Analyst from a workspace:

cd /path/to/vulcan-workspace
vulcan-analyst

Or pass the workspace path directly:

vulcan-analyst /path/to/vulcan-workspace

For one prompt and exit:

vulcan-analyst ask /path/to/vulcan-workspace --prompt "Inspect this workspace and summarise the highest priority issue."

Common Prompts

List the active Vulcan tools.
Inspect this workspace and summarise the model.
Validate the geometry and explain any warnings.
Review the thermal bridge assumptions.
List the batch result models and available result columns.
Find relevant Vulcan documentation about heat pumps.

Access And Model

Analyst uses the vulcan-mcp-config.json file generated by Vulcan. If access is missing or expired, open Vulcan, go to Profile -> Integrations, and generate the config file again in the workspace.

Keep vulcan-mcp-config.json private. Do not commit it to source control.

If terminal chat starts without a model credential, use /login inside Vulcan Analyst.

Local Commands

Inside Analyst:

/help         Show local commands.
/status       Show readiness and current state.
/tools        Show available Vulcan and workspace tools.
/session-log  Show the local session log path.
/exit         Close Analyst.

Analyst writes session logs under .vulcan/analyst/sessions in the workspace.

Deterministic Commands

Analyst also exposes deterministic commands for scripts and repeatable checks:

vulcan-analyst commands
vulcan-analyst doctor
vulcan-analyst inspect <workspace-or-csv-path>
vulcan-analyst geometry validate <workspace-or-csv-path> --fail-on none
vulcan-analyst thermal-bridges auto <workspace-or-csv-path> --mode summary
vulcan-analyst thermal-bridges validate <workspace-or-csv-path> --with-auto
vulcan-analyst parameters list <workspace>
vulcan-analyst parameters view <workspace> <category> <parameter-id>
vulcan-analyst parameters save <workspace> <category> <parameter-id> --content-file snippet.json
vulcan-analyst batch-config create <workspace> <config-name> --base-model base --weather-file weather --parameters-file parameters.json
vulcan-analyst batch run <workspace> <config-name>
vulcan-analyst batch status <workspace> --config-name <config-name>
vulcan-analyst results models <workspace> <config-name>
vulcan-analyst results columns <workspace> <config-name> <model-name>
vulcan-analyst metrics calculate <workspace> <config-name> --models model_a,model_b --metrics-file metrics.json
vulcan-analyst docs list
vulcan-analyst docs get --query "heat pump sizing"
vulcan-analyst source symbols --query runBatch
vulcan-analyst source inspect <symbol-id>
vulcan-analyst retrieval report

Add --json to deterministic commands when you want machine-readable output.

Troubleshooting

If Analyst reports that access is missing, regenerate the workspace config file from Vulcan and rerun Analyst against that workspace. Support may ask you to run vulcan-analyst doctor for diagnostics.

If node --version is missing, install Node.js. If npm --version is missing, repair the Node/npm install or terminal PATH. If doctor reports that Node is too old, run Analyst with Node 22.19.0 or newer from a new terminal.

If npm reports prefix, cache, or permission errors, avoid global install first and retry the npx command:

npx --yes @vulcan-energy/analyst@latest

Most users do not need an Analyst-specific provider override. Support can help pin one if your local model setup needs it.