NeqSim setup (/neqsim-setup)
Walk the user through the three user-level settings the task workflow depends
on, then run neqsim doctor. Everything here is stored in
~/.neqsim/task_defaults.json, so it is shared by the workspace checkout, the
pip-installed toolkit and the agent plugin.
0. Find the CLI
Run neqsim --show-task-root. If the shell says neqsim is not recognized,
use <python-executable> -m neqsim_cli --show-task-root where
<python-executable> is NEQSIM_PYTHON if set, else the first python3 /
py -3 / python on PATH. Use that same form for every command below. If
neither works the toolkit is not installed yet. In a plugin install the
SessionStart hook installs it in the background on the first prompt of a
session; check ~/.neqsim/plugin-install/neqsim/install.log (last line
== ... OK or == ... FAILED with the pip error above it). If the log is
missing or failed, install by hand from the plugin's vendored copy:
<python-executable> -m pip install "<plugin folder>/toolkit" where the
plugin folder is
%USERPROFILE%\.vscode\agent-plugins\github.com\equinor\neqsim-copilot-plugin\neqsim
on Windows (~/.vscode/agent-plugins/... on Linux and macOS). A marketplace
install lands there, not under agentPlugins in the VS Code user-data
folder — that one only holds synced customization plugins, so do not conclude
from its absence that the plugin is not installed. A Copilot CLI install lands
in ~/.copilot/installed-plugins/neqsim-copilot-plugin/<plugin>. Without a
plugin:
<python-executable> -m pip install "neqsim-dev-setup @ git+https://github.com/equinor/neqsim.git#subdirectory=devtools".
Installing the toolkit also pip-installs the neqsim PyPI package (the packaged
JAR + jpype bridge), and the hook's own install.log runs IMPORT_OK=1 IMPORT_FAILED=0 against it afterwards, so a plugin-only install always ends up
with the full NeqSim Python API importable — not just the CLI.
The neqsim-community and neqsim-enterprise plugins install their skill
packages through the same hook, into the same interpreter:
~/.neqsim/plugin-install/<plugin>/install.log. A healthy log ends with
live dependencies: all N installed, IMPORT_OK=<n> IMPORT_FAILED=0 and
== ... OK. Each FAILED <package> (<error>) line names a skill package that
does not import and why — most often a missing live dependency
(ModuleNotFoundError: stidapi, eq_api_connector, msal_bearer, pepr_client,
tagreader), which means the STID / SAP-Maintenance / PDM / PEPR / historian
agents cannot reach their systems. Fix by hand with
<python-executable> -m pip install -e "<plugin folder>/neqsim-enterprise" --no-deps
followed by
<python-executable> -m pip install -r "<plugin folder>/neqsim-enterprise/requirements-live.txt"
(add --no-index --find-links "<plugin folder>/neqsim-enterprise/wheels" for an
offline bundle). A missing log means the hook never ran for that plugin: start a
new chat, then check the plugin version against these known hook failures —
all fixed by updating the plugin:
| Hook error in chat | Cause | Fixed in |
|---|---|---|
| The argument '/scripts/install_skill_packages.ps1' ... does not exist | VS Code does not expand ${PLUGIN_ROOT} |
1.1.1 / 1.0.1 |
PowerShell parse errors with variables replaced by nothing (+ = ''; if (-not ...) |
the hook's windows string had its $ tokens stripped |
a later 1.1.x / 1.0.x |
install_skill_packages.ps1 ... is not digitally signed. You cannot run this script on the current system (often arriving as a #< CLIXML blob), once per installed plugin |
a Group Policy execution policy on a managed PC overrides -ExecutionPolicy Bypass, so the hook's unsigned .ps1 cannot run; nothing is pip-installed and the MCP entry is never repaired |
neqsim 1.1.7 / community 1.0.5 / enterprise 1.0.8 |
On an older plugin, do the hook's work by hand (pip and a .py are not
covered by the execution policy):
<python-executable> "<plugin folder>\scripts\install_skill_packages.py" with
PLUGIN_ROOT set to that folder, for each installed plugin.
1. Ask for the three paths (skip any the user already has)
Show the current values first:
neqsim --show-task-root
neqsim --show-document-root
neqsim --show-report-template
Then ask, one question each, with the current value as the default:
| Setting | Question | Command |
|---|---|---|
| Task root | "Where should new task folders be created? (a OneDrive/shared folder is common; cwd means the terminal's folder)" |
neqsim --set-task-root "PATH" |
| Document root | "Which folder holds your standards, TRs, datasheets and drawings? Agents search it and all subfolders before declaring a document unavailable. Leave empty to skip." | neqsim --set-document-root "PATH" |
| Report template | "Which .docx/.dotx template should Word reports use? Leave empty for built-in styling." |
neqsim --set-report-template "PATH" |
After setting the task root or the document root (skip for cwd, which has no
single folder to reveal), ask: "Open this folder in File Explorer now?" and, if
yes, re-run the same --set-task-root / --set-document-root command with
--explorer appended (add --vscode too if the user also wants it added to the
VS Code workspace — both flags combine freely, e.g.
neqsim --set-document-root "PATH" --vscode --explorer). Without --explorer
the command still prints how to open the folder by hand.
Quote paths with spaces. Do not guess or persist a path the user did not give;
--reset-task-root / --reset-document-root / --reset-report-template
remove a saved value. Per-session overrides are the environment variables
NEQSIM_TASK_ROOT, NEQSIM_DOCUMENT_ROOT, NEQSIM_REPORT_TEMPLATE.
2. Verify
Run neqsim doctor and relay the result. It detects its own mode:
- workspace (source checkout): Java, Maven, built JAR, Python
neqsim, agents/skills files, task root, template, document root, git. - toolkit (pip / plugin, no checkout): Java (>= 8 for NeqSim, >= 21 for
the MCP server), the packaged NeqSim JAR starts and flashes, MCP server jar
cache,
neqsimCLI, task root, template, document root.
Report only the [!!] and [??] lines with their fix hints. Typical fixes:
| Symptom | Fix |
|---|---|
| Java < 21 | install a JDK 21+ first on PATH (winget install EclipseAdoptium.Temurin.21.JDK); NeqSim itself runs on 8+ but the MCP server needs 21 |
MCP output shows Could not find or load main class ${PLUGIN_ROOT}.servers.NeqsimMcpLauncher.java, exit code 1 |
expected: VS Code does not expand ${PLUGIN_ROOT} in an Agent Plugins mcp.json (microsoft/vscode#336882), so the plugin's own neqsim server entry always errors. Do not blame Java and do not edit the plugin's mcp.json. The working entry is an absolute one in the VS Code user mcp.json (%APPDATA%\Code\User\mcp.json), which the SessionStart hook writes; if it is missing the hook never ran — see §0. Manual equivalent: "servers": { "neqsim": { "type": "stdio", "command": "java", "args": ["<plugin folder>/servers/NeqsimMcpLauncher.java"] } }, then open a new chat |
Registered server java FAIL, or no neqsim_* tools and ~/.neqsim/mcp-server/ missing |
the neqsim entry in the VS Code user mcp.json runs a Java below 21 (typically Java 8 first on PATH shadowing a newer JDK): the launcher is source-launched and dies with Could not find or load main class before it can complain. Re-run the plugin install script (it pins the newest JDK 21+ into the entry) or set NEQSIM_MCP_JAVA and start a new chat (the session hook re-pins). Prove the fix without VS Code: "<jdk21+>/bin/java" "<plugin>/servers/NeqsimMcpLauncher.java" --prefetch (exit 0 = OK). MCP tools bind at chat-session start: after any fix open a new chat or Reload Window |
| no packaged JAR | <python-executable> -m pip install neqsim or set NEQSIM_JAR |
neqsim on PATH comes from another interpreter |
use <python-executable> -m neqsim_cli explicitly |
| task root not writable | choose another folder with --set-task-root |
3. Confirm
Finish with a three-line summary: task root, document root (or "not set - work
from user-supplied documents"), report template (or "built-in"), and the
doctor pass count. Optionally list the document root's contents with
neqsim documents so the user sees what agents will be able to find.