Neqsim Setup

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:

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:

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.