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 workspace created by the Vulcan browser app.
- Node.js 22.19.0 or newer.
- For Vulcan Pro tools only: sign in with
vulcan-analyst auth login, or avulcan-mcp-config.jsonfile in the workspace. - Your own AI model account. If chat asks for model credentials, run
/logininside 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. From the Analyst version after 0.1.0-alpha.14, inspecting and merging need no browser, and only running a batch needs Google Chrome. On the first run, Analyst downloads and caches the model's HEM model version (about 12 MB for Rust, 75 MB for Python).
Analyst is free to run. Without a config it answers questions, inspects and validates your workspace, proposes thermal bridges and runs single scenarios. Vulcan Pro adds scenario batches, model comparisons and cost metrics; when a request needs Pro, Analyst says what is missing.
To unlock Pro, run vulcan-analyst auth login: it shows a link to usevulcan.app/connect and a short code; open the link, check the code and click Connect. Alternatively, 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 asanalyst, for experienced users.developer: The same tools asanalyst, 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 uses the workspace's vulcan-mcp-config.json when it holds a usable token; otherwise it uses the token vulcan-analyst auth login stores in the Analyst config directory. Either way the token only unlocks the Pro tools. If Analyst reports that Pro access is missing or expired, run vulcan-analyst auth login again, or 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.
