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.

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.11
You can enter multiline code - the interpreter will continue reading until you type 'run', 'compile', or 'transpile'
Type 'exit' to quit, 'run' to execute, 'compile' or 'transpile' to build executable, 'help' for help
(c) 2026 - Andrea Maldini
> 

In interactive mode, you can:

• Enter code: Type MALDA code line by line. The interpreter will continue reading until you enter a command.
• run: Execute the entered code
• compile: Compile the entered code to an executable (interpreter mode)
• transpile: Compile the entered 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; }
> print(add(x, y));
> run
30
> 

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 --eval "<code>"

Executes the provided code string directly.

Execute from Standard Input

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

Reads and executes code from standard input.

Validate Syntax Only

malda --check "<code>"

Validates the syntax of the provided code without executing it. Useful for syntax checking in CI/CD pipelines.

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)
• 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

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 26. 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.