Vulcan Analyst is an experimental command-line assistant for working through a Vulcan workspace. It can inspect HEM inputs, run batches, review results, retrieve Vulcan documentation, and use selected source references to ground its answers.

Use Analyst for assessment checks, debugging, batch result review, and guided investigation. Keep checking important inputs and outputs yourself before relying on any AI-assisted recommendation.

Requirements

You need:

A Vulcan account with Vulcan Pro. See Plans and billing.
A workspace created by the Vulcan browser app.
Node.js 22.19.0 or newer.
A vulcan-mcp-config.json file in the workspace.
Your own AI model account. If chat asks for model credentials, run /login inside Analyst. Usage is billed by your provider.
Models saved by the current app need Vulcan Analyst 0.1.0-alpha.9 or later and Google Chrome. On first use, Analyst downloads and caches the model's HEM model version (about 12 MB for Rust, 75 MB for Python).

The config file is created in Vulcan from Profile → Integrations by clicking Generate Config File. The same file gives access to Vulcan tools and Analyst. It contains a signed access token for your Vulcan account and is valid for up to seven days (less if your Pro seat ends sooner). Analyst verifies it locally, so it works offline until it expires; when it expires, generate a new config from the same place. Run vulcan-analyst auth status to see the exact expiry and which capabilities the config carries.

Install

Install Analyst in the environment where you want to run it:

npm install -g @vulcan-energy/analyst

Check that the CLI can start:

vulcan-analyst doctor --json

If you also want to expose Vulcan tools to a desktop assistant or local scripts through the MCP helper, follow the Vulcan MCP Server Guide. Analyst does not require the helper server to be running; it uses the same workspace access file.

Start Analyst

Run Analyst from a workspace that contains vulcan-mcp-config.json:

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

You can also point it at a workspace from another directory:

vulcan-analyst /path/to/vulcan-workspace

For a one-off prompt:

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

Common workflows

Ask Analyst direct questions about the workspace:

List the active Vulcan tools.
Inspect this workspace and summarise the model.
List the batch result models and available result columns.

Analyst writes a session log under .vulcan/analyst/sessions in the workspace so you can review which tools were used during the conversation.

Tool profiles

vulcan-analyst chat and vulcan-analyst ask accept --profile to set which tools Analyst can use:

analyst (default): Vulcan tools, and general tools that read, write, and edit workspace files and run shell commands.
support: Vulcan tools only. No general file, shell, or coding tools.
advanced: The same tools as analyst, for experienced users.
developer: The same tools as analyst, for internal debugging.

In interactive chat, Analyst asks you to approve a tool that changes files, runs a shell command, or starts a simulation.

vulcan-analyst ask /path/to/vulcan-workspace --profile support --prompt "Validate the geometry CSV and list the critical issues."

How access works

Analyst reuses the same signed access file as Vulcan tools. There is no separate Analyst token. If Analyst reports that 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 or send it to support unless specifically asked to share a redacted copy.

Current limits

Vulcan Analyst is experimental. It is intended to assist an assessor, not replace assessment judgement. Provider-backed chat may send prompts and selected tool outputs to the configured model provider. Review any answer that affects compliance, lodgement, or design decisions against the underlying Vulcan files and calculation results.

Vulcan Analyst Guide