2. Tools & Tooling

MALDA provides a complete set of development tools including an interactive interpreter, a dual-mode compiler, and a package manager. This chapter covers how to use these tools to develop, run, and deploy MALDA applications. The table in 2.0 is the command index: every malda <verb> with a one-line pointer. How-tos stay in the sections named there. malda help or malda help <command> prints the same list from the binary.

2.0 CLI command index

Run a file with no verb: malda app.malda (optional --strict-types, --profile). malda -e "…" / --exec executes a snippet — that is not malda eval, which runs suite / case. malda --eval is rejected so the two are not confused. malda --check "…" is a syntax-only compile check; prefer malda check --json for IDE/LSP diagnostics.

Getting started

Build, test, and ship

AI and automation

Packages and diagnostics

malda play writes into a sibling .malda-play/ directory and copies assets/ when present. It watches the source, sibling index.html, and assets/, rebuilds in place, and reloads the browser. Use --no-watch to serve the first compile only. Full-stack score apps (malda new game --fullstack) are refused; compile --mode fullstack instead. Details: docs/llm/malda-gotchas.md.

2.1 Interpreter

The MALDA interpreter allows you to run MALDA code interactively or execute MALDA source files. It provides both an interactive REPL (Read-Eval-Print Loop) mode and command-line execution capabilities.

2.1.1 Interactive Mode

To start the interactive interpreter, simply run malda without any arguments:

$ malda
MALDA (Multi Agent Language with Development Automation) Interpreter
Version 1.0.39
You can enter multiline code - type 'run', 'compile', or 'transpile' to execute the buffer, or a blank line to submit it and return to the prompt
Type 'exit' to quit, 'vars' to list definitions, 'source' to print their code, 'help' for help
(c) 2026 - Andrea Maldini
> 

In interactive mode, you can:

• Enter code: Type MALDA code line by line. A complete statement runs as soon as you press Enter; a block that is still open continues on the ..> continuation prompt. A blank line at ..> (typical after a closing }) submits the buffer and returns to > — it does not quit the session. Type exit to leave the interpreter.
• Session state: Variables, functions, and classes defined in one entry stay visible in later entries. A later class Name { … } or brace-less class Name function … for a name already defined in this session augments that class (same rules as in a file: no primary constructor, no changing extends, no repeated member names). Instances created before the later entry see the new methods. schema, sum-type, and api declarations are not carried across entries — declare them in the same entry that uses them.
• Bare expressions: An expression with no trailing ; and no assignment echoes its value, so 1 + 2 prints 3.
• vars (aliases defs, who): List user-defined variables, functions, classes, prompts, actors, and workflows. Host names such as math / str / io are omitted. Optional filter: vars functions, vars classes, and so on. This is a REPL command, not a language built-in. Typing a name still inspects that one binding.
• source (alias src): Print those definitions in source form, as they were entered. Optional filter by kind (source functions) or by name (source add). A name prints line numbers starting at 1; editline and insert use those numbers, and editline add or insert add without a line number prints the same listing. A kind filter or a full dump stays the original text so it can be re-entered. Later class augmentations are concatenated so the dump can recreate the class. This is the original text, not a live-value dump — use vars for current values. Failed entries are omitted.
• drop (alias undef): Remove a user definition from the session by name (drop add, drop Point). Lambdas bound to a variable (var add = (a, b) => a + b) appear under functions as add(a, b) and are dropped with that variable name. Host names such as math cannot be dropped. After dropping a class, a later class Point(x, y); is a first declaration again (it does not augment). Existing instances keep the old class object.
• replace (alias edit): Drop the named definition and reprint its recorded source so you can paste or retype a new one. Functions can also be replaced by entering function name … again without drop. A non-const lambda can be overwritten the same way with another var add = …; replace add reprints the original assignment. Classes cannot be overwritten in place — use replace Point first.
• editline: Replace one line of a recorded definition. The line number is the one source add prints, starting at 1. The same listing is printed again above the continuation prompt. A successful patch prints the definition with those numbers. editline add 2 return a - b; replaces line 2. Omit the text to type several lines in its place; a blank line on ..> finishes, and an immediate blank line deletes that line. The result has to stay a definition of the same name, or the previous definition is kept. A class is dropped and defined again from the patched source, so existing instances keep the previous class object.
• insert: Insert one or more lines after a source line. insert add prints the numbered listing; insert add after 2 opens the continuation prompt under that listing, and a blank line finishes. On a one-line function such as function add(a, b) a + b;, insert add after 1 wraps it in a block, places the new lines first, and keeps the original expression as the final return.
• run: Execute the buffered code
• compile: Compile the buffered code to an executable (interpreter mode)
• transpile: Compile the buffered code to an executable (transpiled to C#)
• help: Show help message with available commands and language features
• exit: Exit the interpreter

Example: Interactive Session

> var x = 10;
> var y = 20;
> function add(a, b) { return a + b; }
> add(x, y)
30
> vars
variables:
  x = 10
  y = 20
functions:
  add(a, b)
> source
var x = 10;
var y = 20;
function add(a, b) { return a + b; }
> print(x + y);
30
> 

Example: Edit or insert lines

> function add(a, b) {
..>     return a + b;
..> }
..>
> source add
1| function add(a, b) {
2|     return a + b;
3| }
> editline add 2
1| function add(a, b) {
2|     return a + b;
3| }
..>     return a - b;
..>
Updated function 'add'.
1| function add(a, b) {
2|     return a - b;
3| }
> add(5, 2)
3
> insert add after 1
1| function add(a, b) {
2|     return a - b;
3| }
..>     if (a < 0) return 0;
..>
> add(-1, 4)
0
> 

Example: Multiline Entry

> var total = 0;
> while (total < 3) {
..>     total = total + 1;
..> }
..> print(total);
..> run
3
> 

2.1.2 Command-Line Usage

The interpreter can also execute code from the command line:

Run a MALDA File

malda <file.malda>

Executes the specified MALDA source file.

Execute Code Directly

malda -e "<code>"
malda --exec "<code>"

Executes the provided code string directly. That is not malda eval (suite / case). malda --eval is rejected.

Execute from Standard Input

echo "print('Hello, World!');" | malda

Reads and executes code from standard input.

Diagnose without executing

malda check app.malda
malda check app.malda --json
malda check -e "<code>" --json

malda check runs the same LanguageService diagnostics as the IDE and LSP (parser, type hints, schema / sum-type names, interpolation, UI loop, workflow determinism) and does not execute the program. Default type-mismatch severity matches the IDE (Errors). --strict-types adds match / @pure / bounds / const; --lenient-types turns type mismatches into warnings. Exit 0 when there are no errors (warnings are allowed), 1 when any diagnostic is an error, 2 for usage or missing files.

--json prints a stable object for generate → diagnose → patch loops: ok, executed (always false), file, errorCount / warningCount / infoCount, and diagnostics[] with 1-based line / column, code (for example parser, malda-schema, malda-interp), message, optional hint / suggestedFix / fix.

malda --check "<code>"

malda --check "<code>" remains a syntax-only compiler validate (parse errors, no IDE diagnostics). Prefer malda check --json for agent loops.

--fix applies mechanical edits only (flat aliases, $"…" interpolation, .length() → .length). Not every gotcha is auto-fixed. Narrative: 24. Agentic Runs §24.10.

malda check app.malda --fix

Eval suites

malda eval runs suite / case declarations. Ordinary malda run skips them (like property). That is not malda test. See 24.1.

malda eval Examples/Prompts/eval_suite_offline.malda
malda eval path.malda --baseline .malda/evals.json
malda eval path.malda --baseline .malda/evals.json --update-baseline

Prompt hash diff

malda prompts --diff .malda/evals.json

Compares prompt hashes against an eval baseline. Optional @version("…") on a prompt is an informational pin.

Cassettes and the run journal

MALDA_RECORD=tests/cassettes/name.jsonl   malda Examples/path.malda
MALDA_REPLAY=tests/cassettes/name.jsonl   malda Examples/path.malda
MALDA_REPLAY_STRICT=1                    malda Examples/path.malda
MALDA_TRACE=jsonl                        malda Examples/path.malda

Cassettes record/replay every LLM Chat. A miss journals cassette_miss and falls through to a live call unless MALDA_REPLAY_STRICT=1. MALDA_TRACE exports the in-process run journal; it is not the existing malda trace CLI (session .malda-trace.jsonl files). See 24.2 and 24.3.

2.1.3 Getting Help

To see all available commands and language features, use:

malda help
malda --help
malda -h

This displays comprehensive help including:

• Interactive commands
• Command-line usage examples
• Compilation options
• Language basics and syntax
• Built-in functions
• AI features
• Quick examples

2.2 Compiler

The MALDA compiler can create standalone executables from MALDA source code. It supports two compilation modes: interpreter mode and transpile mode.

Runtime modes at a glance

MALDA code can run in three common execution contexts. Use this table to choose the right path before you compile or deploy.

Rule of thumb: develop and debug with the interpreter; ship performance-sensitive server apps with transpile mode; use the JavaScript backend when the UI must run in the browser and MALDA stays on the server or in a JS bundle.

2.2.1 Compilation Modes

Interpreter Mode (Default)

In interpreter mode, the compiler embeds the MALDA source code and the MALDA runtime interpreter into a standalone executable. When the executable runs, it uses the embedded interpreter to execute the source code.

Advantages:

• Fast compilation
• Full runtime flexibility
• Easy debugging

Use when:

• Rapid development and testing
• You need full interpreter features
• Code size is not a concern

Transpile Mode

In transpile mode, the compiler first transpiles MALDA code to C#, then compiles the C# code to a native .NET executable. The resulting executable includes the MALDA runtime integrated directly into the compiled code.

Advantages:

• Better performance (native .NET code)
• Smaller executable size (no embedded interpreter)
• Full .NET integration

Use when:

• Performance is critical
• You want smaller executables
• You need native .NET performance

DLL Mode

DLL mode transpiles MALDA code to C# and compiles it as a .NET DLL library instead of an executable. This allows you to create reusable MALDA libraries that can be referenced by other .NET projects.

Use when:

• Creating reusable libraries
• Integrating MALDA code into existing .NET projects
• Building component libraries

2.2.2 Compiling from Command Line

Basic Compilation

malda compile <file.malda>

Compiles a MALDA file to an executable using interpreter mode (default). The output executable will be named based on the input file (e.g., program.exe from program.malda).

Specify Output Path

malda compile <file.malda> -o <output.exe>
malda compile <file.malda> --output <output.exe>

Specifies the output executable path.

Choose Compilation Mode

malda compile <file.malda> --mode interpreter
malda compile <file.malda> --mode transpile
malda compile <file.malda> --mode dll

Selects the compilation mode. If not specified, interpreter mode is used by default.

Embed a Folder into the Executable

malda compile app.malda -o app.exe --mode transpile --embed-folder secondbrain
malda compile app.malda -o app.exe --mode transpile --embed-folder ./data=assets

Packs a directory into the published executable as assembly resources. At runtime, programs read those files with the virtual scheme embed:<alias>/<relative> (see Built-in Functions §13.8.0). The alias defaults to the folder name; use path=alias to rename. The flag is repeatable. Files are not extracted to disk.

Compile Code Directly

malda -c "<code>" -o output.exe --mode transpile
malda --compile "<code>" -o output.exe --mode interpreter

Compiles code provided directly on the command line instead of from a file. If --mode is not specified, interpreter mode is used by default.

2.2.3 Compilation Examples

Example 1: Basic Compilation (Interpreter Mode)

$ malda compile hello.malda -o hello.exe
Compiling hello.malda...
Output: hello.exe
Mode: Interpreter
Compilation successful! Executable saved to: hello.exe

Example 2: Transpile Mode

$ malda compile app.malda -o app.exe --mode transpile
Compiling app.malda...
Output: app.exe
Mode: TranspileToCSharp
Compilation successful! Executable saved to: app.exe

Example 3: Create DLL Library

$ malda compile library.malda -o library.dll --mode dll
Compiling library.malda...
Output: library.dll
Mode: TranspileToDll
Compilation successful! DLL saved to: library.dll

2.2.4 Compiled Executable Features

Compiled executables include:

• Embedded MALDA Runtime: The full MALDA runtime is embedded in the executable
• AI Capabilities: All AI features (LLM clients, agents, tools) are available in compiled executables
• Standalone Execution: No need to install MALDA on the target machine (for interpreter mode)
• External Dependencies: Some external dependencies (e.g., SQL Server/PostgreSQL client libraries, LLamaSharp native DLLs) may require additional DLLs to be deployed alongside the executable

2.3 Package Manager

MALDA reuses libraries through workspace packages under a local packages/ directory, optional copies in the installed store (~/.maldalang/packages), and import in source. There is no project-hosted public package hub; remote registry commands are optional for private or self-hosted registries.

2.3.1 Workspace Packages (preferred)

Place a library under packages/<name>/ with an entry .malda file (for malda-foo, typically foo.malda, else index.malda / main.malda). From a working directory inside that tree — or with MALDA_PACKAGES_DIR / MALDA_SDK_ROOT set — import without installing:

import malda-demo-math;
import { clamp, VERSION } from malda-demo-math;

Resolution order: installed store first, then workspace roots (env vars, then walk-up looking for packages/). See the OSS demo under packages/malda-demo-math/ and the design note docs/workspace-packages.md.

malda list --workspace
malda Examples/Modules/workspace_package.malda

2.3.2 Offline Package Commands

These commands do not require MALDA_REGISTRY_URL:

List Workspace or Installed Packages

malda list --workspace
malda list

list --workspace shows packages visible from workspace roots. list shows packages already copied into ~/.maldalang/packages.

Install From a Local Path

malda install ./packages/malda-demo-math
malda install ./my-lib/package.json

Copies a local directory, package.json, or .malda entry into the installed store so import can resolve it without a workspace packages/ tree.

Uninstall / Init

malda uninstall mypackage
malda uninstall mypackage@1.2.3
malda init [directory]

init writes a starter package.json in the target directory.

2.3.3 Optional Remote Registry

Remote install <name> and search need MALDA_REGISTRY_URL pointing at your registry API. The OSS project does not operate a public npm-like hub. If the variable is unset, only remote commands fail; workspace import, list, list --workspace, local install <path>, uninstall, and init keep working.

# Optional — only for a private/self-hosted registry
export MALDA_REGISTRY_URL=https://your-registry.example.com

malda install mypackage
malda install mypackage@1.2.3
malda search http

2.3.4 Using Packages in Code

Prefer import (canonical). using remains an alias for package loads:

import mypackage;
import { helper } from mypackage;

var result = helper();

2.3.5 Package Dependencies and Storage

When installing from a remote registry, declared dependencies in package metadata are resolved and installed first. Local path installs copy the selected folder as-is.

The installed store keeps package files, package.json metadata, and versions under ~/.maldalang/packages. Workspace packs under repo packages/ need not be copied there.

2.4 Development Workflow

Here's a typical workflow for developing MALDA applications:

1. Write Code: Create your MALDA source files (e.g., app.malda)
2. Test Interactively: Use the interactive interpreter to test code snippets:

   malda
   > // Test your code here
   > run

3. Run Full Program: Execute your complete program:

   malda app.malda

4. Share Libraries: Put reusable code under packages/<name>/ and import it (or malda install ./path into the local store). Use malda list --workspace to confirm discovery.
5. Compile for Distribution: Create a standalone executable:

   malda compile app.malda -o app.exe --mode transpile

2.5 IDE Integration

MALDA ships more than one editor surface. They are not feature-equivalent:

• Desktop IDE: Native Windows application — the reference IDE (full project workflows, package UI, local models / MCP where available, virtual @malda-section tabs, richer compile). Install it from the win-x64 GitHub Release zip and run MaldaDesktop.bat
• Web IDE: Browser learning playground (Monaco) for edit / run / debug and examples — useful cross-platform, but not Desktop parity
• VS Code / LSP: Cross-platform editing via the language server, plus interpret-mode F5 debugging through vscode-malda (see 2.6.5)

The Desktop IDE provides:

• Syntax highlighting
• Code completion
• Integrated interpreter for running code
• Integrated compiler for creating executables
• Package management UI
• Debugging support
• In-place update from GitHub Releases (Help → Update Installation), for zip installs only

2.6 Language Server (LSP)

MALDA ships with a Language Server Protocol (LSP) implementation so that editors such as VS Code, Cursor, and any other LSP-capable editor can provide rich editing support for .malda files: diagnostics, completion, hover, go to definition, find references, rename, code actions, signature help, formatting, and workspace symbol search.

2.6.1 What the MALDA Language Server Provides

• Document sync: Tracks open, change, and close of .malda files
• Diagnostics: Parser errors and decorator validation (published after a short debounce on edit)
• Completion: Keywords, built-ins, decorators, and symbols (classes, functions, variables, members)
• Hover: Documentation for symbols and decorators
• Document symbols: Outline (classes, functions, actors, prompts and their members)
• Go to definition: Jump to declaration of classes, functions, actors, prompts, and variables (single-file)
• Find references: All references to the symbol at the cursor (single-file)
• Rename: Rename symbol with validation (single-file)
• Code actions: Quick fixes for parser errors (e.g. insert missing brace or semicolon)
• Signature help: Function signature and active parameter at call sites
• Formatting: Indentation by brace nesting (full document or selection)
• Workspace symbol: Search symbols (classes, functions, actors, prompts) across open documents

2.6.2 Setting Up VS Code

1. Install the Extension that adds LSP client support for custom languages (e.g. “LSP” by roguelynn, or use the built-in support if your extension uses it). Alternatively, use a generic “Language Server” or “MALDA” extension if one exists.
2. Configure the MALDA language server in VS Code. For a custom LSP that runs an executable:
   • Open Settings (JSON) and add a client configuration that runs the malda-lsp executable with stdio and language id malda for *.malda files.

Example settings.json snippet (adjust the path to your malda-lsp executable):

{
  "malda-lsp.serverPath": "C:\\path\\to\\malda-lsp.exe",
  "malda-lsp.trace.server": "off"
}

If your setup uses a generic LSP client (e.g. “LSP” extension) with a “server” definition:

{
  "lsp.servers.malda": {
    "command": "C:\\path\\to\\malda-lsp.exe",
    "fileTypes": ["malda"],
    "languageId": "malda"
  }
}

Ensure .malda files are associated with language id malda (e.g. via “Change Language Mode” or an extension that registers the malda language). Interpret-mode F5 debugging is a second process — see 2.6.5 Interpret-mode debug.

2.6.3 Setting Up Cursor

Cursor is based on VS Code and uses the same configuration mechanisms. Use one of the following approaches:

1. Same as VS Code: If you use an LSP client extension in Cursor, add the same MALDA server configuration as in the VS Code example above (e.g. in Cursor’s settings.json or the extension’s config). Point command / serverPath to your malda-lsp executable.
2. Workspace settings: In your project folder, create or edit .vscode/settings.json (Cursor respects this) and add the MALDA LSP server configuration there so that everyone in the repo gets the same setup.

Example .vscode/settings.json in your project:

{
  "lsp.servers.malda": {
    "command": "C:\\path\\to\\malda-lsp.exe",
    "fileTypes": ["malda"],
    "languageId": "malda"
  }
}

Use the full path to your malda-lsp executable.

2.6.4 Other Editors

Any editor that can start a language server via stdio and send LSP requests (e.g. Sublime Text with LSP plugin, Vim/Neovim with LSP client, Emacs with eglot/lsp-mode) can use the MALDA language server. Configure the editor to run malda-lsp.exe (or the path to your malda-lsp executable) as the language server for .malda files and, if required, set the language id to malda.

2.6.5 Interpret-mode debug

malda debug-adapter speaks the Debug Adapter Protocol (DAP) on stdin/stdout. It is a separate process from the language server: do not send DAP on the malda-lsp stdio pipe, and do not print CLI banners on the adapter’s stdout.

The in-repo vscode-malda extension contributes debugger type malda. Press F5 on a .malda file to launch the interpreter under the adapter (malda.cli.path points at a malda executable that understands debug-adapter). Language intelligence stays on malda-lsp.

This path is interpret-only. There is no debugger keyword. Transpile failures and #line mapping stay in docs/debugging-transpile.md. Procedures, breakpoints, and what will not stop are in docs/debugging-interpret.md.

2.6.6 Desktop IDE JavaScript debug

Programs that call browser APIs (dom.*, game.*, three.*) cannot pause in the interpreter. In the Desktop IDE, F5 transpiles the open file to JavaScript, opens it in the Web Preview panel, and binds editor breakpoints to the generated script through the VLQ source map and WebView2's Chromium debugger.

Set a glyph breakpoint on a statement (for example a line in Examples/Games/maldanoid.malda), press F5, and play until that statement runs. Continue / step over / step into / step out / pause use the same Debug toolbar as interpret mode. Locals come from the JavaScript call frame; watch expressions and breakpoint conditions are JavaScript, not MALDA and/or.

Files that include both a client target (@client() / @javascript()) and a host target (@server() / @csharp() or a route decorator such as @GET / @PAGE) are full-stack. Desktop IDE F5 starts both sessions: the interpreter debugs the host partition (client-only functions are skipped so dom.* is not executed there) and Web Preview debugs the JavaScript partition. Continue / step follow whichever side last paused; Pause stops both. Combined output is labeled [server] and [client]. One current-line highlight and inspect panel is shown at a time. @shared() bodies can stop in either runtime.

Ctrl+F5 (Run) on browser-only programs opens Web Preview without the debugger. Ctrl+F5 on full-stack files still offers the Server / Client preview / Full stack run dialog. VS Code F5 remains interpret-only. Browser DevTools still work on compiled .js + .map files. See 28. Browser JavaScript UI Backend.

2.7 Property Testing (Overview)

MALDA provides deterministic, seed-based property testing through malda test. Typical usage in tooling workflows includes:

• Stable replay with --iterations and --seed
• CI-oriented output with --format ci
• Regression artifact generation with --write-regression

malda test --iterations 100 --seed 1337
malda test --format ci --iterations 100 --seed 1337
malda test --write-regression --regression-dir ./artifacts/regressions

For language syntax, capability decorators, runProperty(...), backend eligibility semantics, and full workflows, see Property Testing.

2.8 Writing MALDA with a Coding Agent

MALDA does not appear in the training data of current language models, so an agent asked to write .malda source without context will invent syntax that does not exist. The repository ships a compact language pack that solves this: a few thousand tokens of idioms, grammar and examples that an agent reads before it writes. This is a supported authoring path, not a curiosity — the largest program written in MALDA, the autonomous coding agent in Examples/RalphWiggum/ (about 4,000 lines across eleven files), was produced this way.

2.8.1 The Language Pack

The pack lives in docs/llm/. Each file has a distinct job, so you load only what the task needs:

For deeper questions, point the agent at Examples/, this manual, and the language specification in docs/spec/malda-language-1.0.md. The root llms.txt is a compact index of the documentation for tools that consume one entry point.

2.8.2 The Interpreter Is the Feedback Loop

Generated MALDA should be executed, not reviewed by eye. The interpreter starts fast and reports parse and runtime errors with line and column, which is enough signal for an agent to correct itself without further instruction:

malda path/to/program.malda

From a source checkout, the equivalent is:

dotnet run --project MaldaLang -- path/to/program.malda

Two habits make the loop converge faster. Keep generated programs small enough to run in isolation and compose them with include (see 1.6 Source Composition) rather than generating one large file. And install the language server (2.6 Language Server (LSP)) in the editor the agent runs in, so diagnostics appear on the source as it is written instead of only when it runs.

Programs that read input or use randomness look unverifiable to an agent, which cannot sit at a prompt. They are not. Seed the generator with math.seed(n) so every branch is reachable on purpose, then feed input() a scripted transcript on stdin:

printf '50\n25\n39\n' | malda guess_number.malda

Seed, pipe a transcript, assert on the output. That converts an interactive program from something an agent asserts about into something it can prove. Note that Spectre.Console strips colour when stdout is not a terminal, so piped output carries no escape codes even when the markup is correct.

2.8.3 Known Failure Modes

These are the mistakes an agent makes most often when the pack is not loaded, or is loaded only in part:

• Borrowed keywords. let does not exist — variables are declared with var. fn and def are syntax errors; use function.
• Typed prompt parameters. Prompt declarations take name-only parameters; prompt p(name: string) is not valid. A -> ReturnType on a prompt is informational only.
• Invented built-ins. A plausible name from another language will not resolve. println is the usual casualty; the call is print. Grep docs/llm/malda-builtins.tsv, which is generated from the engine, or read 13. Built-in Functions.
• String interpolation outside a prompt body. "n is {n}" prints literally; it does not raise. Concatenate with + string(n).
• Interpreter-only built-ins in compiled targets. A program that runs interpreted may fail to transpile. Verify with malda compile before promising an executable.
• Type annotations treated as enforcement. Annotations parse and feed the language server. Literal initializer mismatches produce a Warning in the IDE/LSP, but nothing checks hints at runtime, so an agent should not rely on them for validation.