Installation Guide

HagiCode offers three installation methods. First pick a path for your scenario, then confirm the prerequisites that path needs, and finally go to the matching installation page.

Choose an Installation Method

Your scenario	Recommended method
Personal local use on Windows	Microsoft Store Installation
Personal local use on macOS / Linux, or Windows where the Store is unavailable	Desktop Installation
Servers, NAS, team sharing, or when you need environment isolation	Docker Compose Installation

Microsoft Store InstallationThe default recommended entry for Windows. Install and receive later updates through the official Store.

Desktop InstallationA graphical installation and management flow. Suits macOS / Linux, and Windows users who need to download the installer manually.

Docker Compose InstallationSuits scenarios that need environment isolation, standardized deployment, or team collaboration.

Before You Install

Each path has different prerequisites:

Installation method	Node.js	Git
Microsoft Store / Desktop	Install it yourself, version 24 or higher	Install it yourself
Docker Compose	Not needed on the host	Not needed on the host

Desktop No Longer Bundles Node.js

Desktop only bundles the .NET runtime needed to run HagiCode Server and no longer provides Node.js. It looks for node and npm on the system PATH, and installs managed packages such as Agent CLIs into your local npm global directory. Install Node.js 24 or higher before you launch Desktop for the first time. See Installing Node.js for details.

Install Git

Desktop checks for node, npm, and git at startup, and the “Demo Project” in the “New Project” dialog of the main interface also needs Git to clone the official sample repository. Pick one of these ways to install it for your system:

• Windows: run winget install --id Git.Git -e, or download the installer from git-scm.com.
• macOS: run xcode-select --install, or use Homebrew and run brew install git.
• Debian / Ubuntu: run sudo apt-get install -y git.
• Fedora: run sudo dnf install -y git.

After installation, reopen your terminal and confirm the commands are available:

node --version
npm --version
git --version

Install First, Then Launch Desktop

Desktop reads the system PATH at startup. If you install Node.js or Git while Desktop is already open, fully quit and restart Desktop.

Agent CLI

HagiCode works through Agent CLIs that are installed and signed in on your machine. The initialization wizard only lists CLIs it has detected locally, so install and sign in to at least one before you enter the wizard. The currently supported CLIs, their installation methods, and official entry points are maintained in one place at AI Agent CLI Installation.

Related Software

Install Node.jsPrepare Node.js 24+ and npm, which Desktop and most Agent CLIs depend on.

Introduction to OpenSpecGo to the standalone OpenSpec documentation site to learn about installation, core concepts, and the specification-driven workflow.

Install AI Agent CLISee the currently supported Agent CLIs and tell one-click installation apart from manual installation / authentication.

Next Steps

1. Choose an installation method from the table above and complete its prerequisites first.
2. Finish installing and launch HagiCode for the first time, then follow Wizard Setup to create your default Hagicoder and your first project.
3. To learn about the OpenSpec proposal workflow, read the Introduction to OpenSpec and Create a Proposal Session.