This guide walks you from installation to completing your first Plan-driven task.

Step 1: Install Alius

curl -fsSL https://alius.tech/install | sh

Verify the installation:

alius --version

Step 2: Initialize Your Project

Navigate to your project directory and run the initialization wizard:

cd your-project
alius init

The initialization wizard guides you through the following steps:

1. Language selection — Choose the workspace interface language (e.g., English, 中文, 日本語)
2. Model pool configuration — Select providers (BigModel GLM, Xiaomi MiMo, DeepSeek, etc.), enter your API Key, and import available models from remote
3. Model assignment — Choose models for the Plan Model, Execute Model, and Review Model roles
4. Soul selection — Choose the Agent’s role identity (e.g., senior-engineer, code-reviewer, etc.)

After initialization, the .alius/ directory contains:

.alius/
├── config/             # Project configuration
│   ├── config.toml     # Main configuration
│   ├── providers.toml  # Providers, model pool, API Keys
│   ├── model.toml      # Plan/Execute/Review model assignment
│   ├── soul.toml       # Agent identity
│   ├── tools.toml      # Tool configuration
│   ├── permissions.toml # Security permissions
│   └── mcp.json        # MCP servers
├── memory/             # Project memory
└── workspace/          # Workspace documents

Initialization is resumable. If you interrupt at any step, running alius init again will ask whether to continue from where you left off or start over.

Step 3: Enter the Workspace

alius

You will see the TUI workspace welcome screen, displaying the version number, current Soul, model assignment, and mode information.

Press Enter to enter the workspace.

Step 4: Bypass Mode — Quick Query

The workspace starts in Bypass mode by default. Bypass mode is suitable for quick single-turn interactions:

> Explain the authentication module in this project

Bypass mode behavior:

• Sends input directly to single-turn execution
• The model may request one tool call
• Does not enter a multi-turn iteration loop
• Suitable for Q&A, explanations, and lightweight analysis

Step 5: Plan Mode — Complex Tasks

Press Shift+Tab to switch to Plan mode for tasks that require multi-step execution:

> Refactor the database connection pool to support async

The complete Plan mode workflow:

1. Goal understanding — If the goal is unclear, the model proactively asks questions
   • Questions appear as options (single-select, multi-select, or free input)
   • You select or type answers, minimizing typing
2. Plan generation — After fully understanding the goal, the model generates an executable plan list
3. Approval — The plan list is displayed in the session area, and the interaction area asks you to approve or reject
4. Execution — Approved plan nodes execute step by step
   • Tool calls go through Shell Gate approval
   • The session area shows real-time execution progress
5. Completion — After all nodes finish executing, you confirm the plan is complete, and the plan panel closes

Step 6: In-workspace Configuration

You can adjust configuration at any time within the workspace without leaving.

/config — Configuration Center

Type /config to open the embedded configuration center with three tabs:

Controls:

• Tab / Shift+Tab switch configuration tabs
• Up / Down navigate options
• Space toggle multi-select options
• Enter confirm selection
• Esc exit (all changes take effect immediately, no save button needed)

/model — Model Pool Manager

Type /model to manage the local model pool:

• View the list of imported models
• Add models from remote providers (select provider → API mode → enter Base URL and API Key → fetch remotely → multi-select to import)
• Delete imported models (models currently assigned in /config cannot be deleted; reassign first)

All /model operations take effect immediately and are written to .alius/config/providers.toml.

/init — Re-initialize

Type /init to re-run the initialization wizard. Note: this clears existing configuration and starts over.

Step 7: Save Memory

After completing a task, save important findings to project memory:

> /memory save Async connection pool requires tokio runtime

Memory persists across Sessions, so the Agent can leverage previously accumulated knowledge next time.

Step 8: Resume Next Time

Sessions are automatically saved to the workspace. Next time you work on this project:

alius

You can resume a previous Session in the workspace, continuing from where you left off.

Common Shortcuts

Inside the configuration center, Tab / Shift+Tab switch configuration tabs, not execution modes.

Next Steps

• Core Concepts — Deep dive into workspaces and Sessions
• Plan and Bypass Modes — Detailed comparison of the two modes
• Commands — Complete command reference
• Configuration — Configuration file details