Open Studio → AI Shell Agent under Extend, enable natural language shell control and choose a compiler. Download the required models from that page. Downloads show their actual byte counts in the card background, verify SHA-256 before installation and build a command index. Pause keeps partial files for resume; Cancel removes partial files. Models have their own licenses, shown on their cards, and are never bundled or downloaded by the installer.
Type !dark mode or ! set volume to 40 in the launcher. A bare ! shows
examples. While the agent is on, the launcher’s empty search field lists
! beside its other prefixes in every look. Ordinary launcher searches do not start inference. The same rows
show retrieval candidates and the final action preview in Classic, Grid and
Beacon. Enter runs the previewed actions through Mandara’s command dispatcher;
Esc cancels. The preview is a proposal, so check its command and target values.
| Component | Download including tokenizer | License |
|---|---|---|
| Arctic Embed XS, int8 ONNX | about 24 MB | Apache-2.0 |
| FunctionGemma 270M, Q4_K_M, default compiler | about 287 MB | Gemma |
| Qwen3 0.6B, Q4_K_M, optional compiler | about 409 MB | Apache-2.0 |
The default setup downloads about 311 MB. These are verified artifact sizes,
not RAM requirements. Inference needs additional working memory. The models
are stored in $XDG_DATA_HOME/mandara/models/agent-*, normally
~/.local/share/mandara/models/. Delete them from their cards to reclaim disk
space. mandara msg models list, models download <id> and
models remove <id> expose the same model inventory.
FunctionGemma compiles one action. Qwen permits up to four actions and supports multilingual requests. It translates non-English requests, then splits them into concise English search clauses for Arctic retrieval. Their candidate lists share the same ten-tool budget, so one action cannot crowd out the others. The compiler chooses among the compatible candidates for each clause; a numeric setting cannot become a related toggle or lose its explicit value. Single English requests stay single actions. FunctionGemma uses its native function declarations and call delimiters, preserving typed values and string arguments. Compiler weights are reused with KV state cleared between calls. The combined preview is validated before execution. Compiler weights are read in place from the memory-mapped model file instead of being copied into the worker’s private memory, and token embeddings stay quantized, so the operating system can share and reclaim those pages. A single English Qwen request is ranked before Qwen loads, as with FunctionGemma; Qwen loads first only to translate or split a request.
The test bench shows the candidates, generated JSON and measured retrieval and compilation time without executing anything. It also has a purge button.
Each request runs in a short-lived child invocation of the same Rust binary.
Loading, tokenization, retrieval and sampling stay off the UI thread. Only retrieved tools enter
the compiler context, with the compatible alternatives for each intent. A grammar masks invalid tokens;
the output is checked again against those schemas and the live dispatcher.
Closing the launcher, removing !, changing the query or disabling the agent
cancels its worker. A request also ends after 15 seconds without a new query.
Downloads and explicit verification check SHA-256; interactive requests check
installed file sizes to keep disk work out of the query path.
After successful compilation the worker exits before execution, releasing all
model state and dependency thread pools. Cold loading and inference speed
depend on the CPU and storage; no fixed sub-millisecond latency is promised.
The index is cached at
$XDG_CACHE_HOME/mandara/agent/mandara-commands-embeddings.bin and rebuilt when
command descriptions, arguments, examples or the router model change. Typed
Studio settings are indexed as config set actions, including their real
paths, choices and numeric bounds. This catalog is built inside the worker. A stale
or corrupt cache is rejected. Setup can spend longer building this cache;
interactive inference keeps the 15-second limit.
Settings live under [launcher.agent]: enabled defaults to false,
engine is function-gemma or qwen, and debounce_ms defaults to 180
within 100..=1000. Existing configurations stay disabled until you opt in.
The same non-executing paths are available over IPC:
mandara msg agent status
mandara msg agent prepare
mandara msg agent preview 'set volume to 40'
mandara msg agent purge
agent prepare rebuilds the current command index after models are installed.
After an update or plugin change, refresh it in Studio → AI Shell Agent →
Download all required models. Installed model files are verified and reused;
this setup step has more time to build the index than an ordinary query.
agent preview never executes its output. agent purge cancels the shell’s
active inference requests; Studio’s purge button cancels both processes.
Candidates remain visible beneath a compiled launcher preview. Choose an
alternative to compile it with your original request, then review the new
arguments before running it. The first row runs the whole preview; clicking
a compiled action runs just that step. For example, !open quran,
!open jannah and !open calendar open shell panels without inventing a
verse, hadith or calendar source. !enable light mode changes appearance;
!read quran 2:255 opens a specific ayah and keeps the reference you supplied.
!disable on-screen displays turns that feature off. Include values directly,
such as !set volume to 47.