Soul and Agent Identity

What is Soul?

Soul is Alius’s Agent identity system. It defines the AI Agent’s role, expertise, and behavior. You can think of it as a structured Agent persona configuration, represented in Alius using an Agent Card compatible format.

Soul’s impact:

Determines how the Agent understands and responds to your requests
Influences the style and focus of plan generation
Sets behavioral preferences for code reviews, debugging, and other tasks

Two Levels of Soul Management

Alius distinguishes between the official repository cache and the local installed cache:

Command	Management Level	Description
`alius core update`	Official repository cache	Update or clone the official Soul repository cache
`alius soul update`	Local installed cache	Sync official Souls to the local cache
`alius soul list`	Local installed cache	List installed Soul cache entries

alius core and alius soul are two different operations: core manages the official repository, while soul manages local installations.

Configuring Soul in the Workspace

Via `/init` Initialization Wizard

The last step of the initialization wizard is selecting a Soul role. The selection takes effect immediately.

Via `/config` Configuration Center

Type /config, switch to the Soul tab, and select or change the Agent role.

Via Command Line

alius config soul --role senior-engineer

By Editing the Configuration File Directly

Edit .alius/config/soul.toml:

[soul]
role = "senior-engineer"
description = "A senior software engineer focused on testing, clean code, and documentation"
language = "en"

Available Roles

Common Soul roles include:

Role	Characteristics
senior-engineer	Focused on architecture, code quality, and best practices
code-reviewer	Specialized in reviewing code for bugs and improvements
docs-writer	Generates documentation and comments
debugger	Focused on diagnosing and fixing issues

Soul and Model Assignment

Soul roles and Plan/Execute/Review model assignments are independent configuration dimensions:

Soul defines the Agent’s identity and behavioral style
Model assignment defines which model handles which phase

They are managed in different tabs within the /config configuration center.

Soul Selection Prerequisites

Before selecting a Soul role in /config or /init, the following conditions must be met:

At least one enabled model in the local model library
Plan Model, Execute Model, and Review Model each assigned to an enabled model
The selected model’s referenced provider has a Base URL
The selected provider has a direct API Key or API Key environment variable source

Agent Card

The project’s Soul configuration is stored in .alius/config/soul.toml in an Agent Card compatible format. The Agent Card describes the Agent’s identity, capabilities, skills, and how protocols are exposed.