Contributing

Contributing

Build malac from source, run the tests, and work on the web UI, the VS Code extension and these docs.

malac is MIT licensed and developed on GitHub. It is opinionated and follows its author's workflow, so it is shared as is rather than run as a community project: issues and ideas are welcome, but changes that pull it in a different direction may not be merged. Forking is encouraged. This page is for anyone who wants to build it, change it for themselves or see how it works.

Build and test

You need Rust 1.86 or newer.

git clone https://github.com/lobirus/malac && cd malac
cargo test
cargo clippy --all-targets
cargo run -p malac -- --help

On Linux, malac-control needs the X11 and D-Bus headers:

sudo apt-get install -y libxcb1-dev libxrandr-dev libdbus-1-dev pkg-config

To install your checkout:

cargo install --path crates/malac && cargo install --path crates/malac-control
# or, through the install script:
MALAC_SOURCE=. sh install.sh

What CI checks

Every push to main and every pull request runs, on macOS and Ubuntu:

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

The VS Code extension is type-checked as well. Run the same commands before opening a pull request.

Where things are

Path	Contents
crates/malac-core	Runtime, agent loop, tools, providers, permissions, memory, sessions, updates
crates/malac	CLI, terminal UI and renderer, REPL, web server
crates/malac-control	Computer and browser control service
crates/malac-mcp	MCP client and server
crates/malac-core/prompts	System prompts
web/	The web UI: static files compiled into the binary
editors/vscode	The VS Code extension
docs/	Configuration, architecture and release notes for developers
examples/	An example configuration and agent type

Architecture explains how the pieces fit together.

Working on the web UI

The UI's files are compiled into the binary, so changes normally need a rebuild. MALAC_WEB_DIR serves them from disk instead:

MALAC_WEB_DIR=$PWD/web cargo run -p malac -- web --open

Reload the page to see changes.

Working on the VS Code extension

Open editors/vscode in VS Code and press F5, or:

cd editors/vscode && npm install && npx tsc -p . \
  && code --extensionDevelopmentPath="$PWD" /path/to/project

Debugging

MALAC_LOG=debug malac --plain your prompt     # malac logs on stderr
RUST_LOG=debug malac-control stdio            # the control service

Session transcripts in ~/.malac/sessions record exactly what was sent and received; malac sessions show <id> prints one readably.

These docs

This site is built with Astro and Starlight from a separate repository. Report mistakes in the docs as issues on the malac repository.