How Desktop Uses Your Node Environment

HagiCode Desktop uses the external node and npm installed on your system. Install Node.js before you launch Desktop for the first time and make sure both commands are available on the system PATH.

This FAQ explains how Desktop finds your external Node environment, where Agent CLIs are installed, and how to troubleshoot missing Node or npm commands.

Version Requirements

Node.js 24 or higher is required (24 is also the minimum). npm is installed together with Node.js. For installation, see Installing Node.js.

Git also needs to be installed by you; see the Installation Guide.

How Desktop Finds node and npm

Desktop reads the system PATH at startup and looks for node, npm, and git in it. This means:

• The version you see from node --version in a terminal is usually the version Desktop uses.
• Desktop only uses your Node environment; it does not replace or modify it.
• If you install or upgrade Node.js while Desktop is already open, fully quit and restart Desktop so it reads the new PATH.

Version Management Tools and PATH

On macOS and Linux, version management tools such as nvm and fnm usually set PATH only in shell configuration files. Desktop launched from the Dock, the application menu, or a desktop icon does not read those files and may not find node. Launch Desktop from a terminal where node already works, or switch to a system-wide installation.

Where Agent CLIs and Other Managed Packages Are Installed

Desktop’s dependency management page discovers the node and npm on PATH, shows the npm global prefix they resolve to, and installs the CLI packages listed in its catalog into this external global directory.

For each managed CLI, Desktop looks for the executable in the following order:

1. An existing managed path
2. The npm global bin directory (on Windows this includes the .cmd and .ps1 launch scripts)
3. PATH

npm mirror settings apply to install and sync operations. Uninstalling also targets the external global directory and requires confirmation in the interface. You can check the current global directory with this command:

npm prefix -g

If the global directory is in a location that requires administrator privileges, you may see permission errors during installation; see Configuring the npm Global Directory.

What to Do When Node or npm Is Not Found

1. Run node --version in a terminal and confirm Node.js is version 24 or higher; then run npm --version to confirm npm is available.
2. If it is not installed or the version is too old, install Node.js outside Desktop first.
3. Fully quit and restart Desktop, then go back to the dependency page and click refresh.

When Desktop says a CLI package must be installed manually, run the command it gives in a terminal outside Desktop, then return to Desktop and refresh once so it detects the package again.