Wizard Setup

Whether you installed through Microsoft Store, Desktop, or Docker Compose, the first time you open HagiCode’s Web interface you enter the Initialization Wizard. When you finish it, you will have a usable default Hagicoder and at least one project, and can start your first session right away.

How It Differs from Desktop’s First-Time Setup

Desktop’s “First-Time Setup” on first launch (choose a language, confirm the legal documents, download Hagicode Server) happens before the Web interface appears; see Desktop Installation. This page covers the Initialization Wizard that appears afterwards in the Web interface.

Before You Begin

Please confirm the following first:

• At least one Agent CLI is installed and signed in. The wizard only lists CLIs detected on the machine that runs Hagicode Server; if none is detected, you cannot continue creating a Hagicoder. For supported CLIs and installation methods, see AI Agent CLI Installation.
• Desktop / Store users: you have installed Node.js 24+ and Git as described in the Installation Guide.
• Docker users: you have configured the API provider and Token in Docker Compose Builder.
• Have a local repository or working directory ready to connect: Step 3 will have you register it.

Wizard Overview

The wizard has 4 steps, and the left navigation shows the current progress:

Step	Goal	Completion marker
1. Setup	Choose the interface language and theme	Click “Next: Set up Hagicoder”
2. Set up Hagicoder	Choose a CLI and model, and create the default Hagicoder	Click “Confirm and create Hagicoder”, or a usable Agent already exists
3. Create a project	Create at least one project	The project step shows “Project step complete”
4. Community guide	Learn about the community entry points	Click “Start using HagiCode”

Step 1: Setup

Goal: Decide the interface language and theme.

1. Under “Choose interface language”, pick a language. This only switches the interface text; it does not change the language style of the Hagicoder.
2. Under “Choose theme”, pick a theme. “Spring Light” and “Spring Dark” are currently available.
3. Click “Next: Set up Hagicoder”.

Step 2: Set up Hagicoder

Goal: Create the default Agent, whose name is fixed as Hagicoder.

If the system already has an Agent, this step shows “Existing Agents found”, and you can simply keep your current lineup. Otherwise:

1. Choose your primary AgentCLI: the dropdown only shows CLIs detected on this machine. If it says no usable CLI was detected, first install and sign in by following AI Agent CLI Installation, then come back and refresh.
2. Choose your primary Model:
   • Select an existing template: reuse an existing model template under that CLI; you can search by name or model ID.
   • Enter a custom model: type a model name manually, for example gpt-5.5, glm-5.1, or claude-opus-4-7; the matching template is reused or created automatically on creation.
3. (Optional) Click “Test availability”: sends one ping-pong check to the selected CLI and model to confirm the model can reply with pong. The result only applies to the current CLI and model combination and must be re-run after you change either one; creating a Hagicoder does not require the test to pass.
4. (Optional) Click “Shuffle” to change the default portrait; the avatar is drawn at random from the image gallery.
5. Click “Confirm and create Hagicoder”. After creation succeeds, it is added to the emergency team, and the selected CLI and model are written to its default configuration.

Which CLIs Are Supported

The CLIs you can pick in the wizard depend on the Agent CLIs installed and detected on this machine, and are not limited to one. The full supported range and installation methods are as listed in AI Agent CLI Installation; Hermes, Gemini, and DeepAgents need manual installation or authentication first.

Common Issues

• My CLI is not in the list: confirm it is installed and available in the environment where Hagicode Server runs; Desktop users should restart Desktop to refresh PATH.
• The availability test fails: common causes include the CLI not being signed in yet, an invalid token, or a model name that the CLI does not support. First run a minimal conversation with that CLI in a terminal to confirm it works on its own.
• Joining the emergency team fails: the page offers “Retry emergency team”; just retry.

Step 3: Create a project

Goal: Register at least one project, so later sessions have a readable working directory. The wizard first checks whether a local project already exists: if one does, it shows the current project summary; if not, you need to register one first.

1. Under “Register one local project”, enter the project name, the folder path, and an optional project description. The fields and path validation are exactly the same as in the “New Project” dialog of the main interface.
2. Click “Create and continue” to go to the next step; if you want to stay on this step and keep adding projects, click “Create project”.
3. If you already have a project, you can click “Continue to community” directly, or “Create another project”, or go back to setup.

Want to Try a Sample Project First?

The wizard only offers registering a local project. The demo project lives on the “Demo Project” tab of the “New Project” dialog in the main interface: it automatically clones and registers the official MonoSpecs Demo repository. The default path is data/repos/monospecs-demo, and the actual directory follows the runtime data directory (DataDir) configuration. This method needs Git and access to GitHub.

Common Issues

• Path validation fails: confirm the folder path is correct and really exists; for Docker deployments, you must enter a mounted directory that is accessible inside the container, not a path on the host.

Step 4: Community guide

Goal: Keep the community entry points at hand.

The official website’s “About” page collects all the community entry points. Links open in a new tab; when you are done, return to the wizard and click “Start using HagiCode” to enter the workspace. You can still reopen the wizard at any time after this step.

Next Steps

Create a Conversation SessionStart in the default read-only mode and let the AI understand the project, then decide whether to switch to edit mode once the direction is confirmed.

Create Proposal SessionWhen you need to break down a plan or review an approach, use a proposal session to turn an idea into a structured implementation plan.