Getting Started

Mutka is a community-driven, modular file explorer for macOS, built with Tauri 2 (Rust backend + native WebView), React 18 + TypeScript, and the macOS Liquid Glass design language.

The design goal: ship a minimal, rock-solid core and let the community build everything else as modules. Even built-in features — copy/paste, file creation, navigation — are modules. The core provides infrastructure only.

Install Mutka

One-line install (recommended)

Downloads the latest release into /Applications and adds the mutka CLI to your PATH. Re-run it any time to update to the newest release:

curl -fsSL https://mutka.app/install/latest.sh | bash

That URL redirects to scripts/install.sh in the repo, so you can read exactly what it runs first.

Manual install (.dmg)

1. Download Mutka_<version>_universal.dmg from the latest release.

2. Open the .dmg and drag Mutka into your Applications folder.

3. (Optional) add the terminal CLI:

   bash <(curl -fsSL https://raw.githubusercontent.com/ilianAZZ/mutka/main/scripts/install-cli.sh)

Using the CLI

mutka --help           # list all available commands
mutka <path>           # open a directory in Mutka
mutka --picker         # pick a file/folder (path printed to stdout)
mutka --run <action>   # run a module action
mutka --list-actions   # list all available actions

Build from source

Building from source is for contributors and module authors who want the dev server with hot-reload. End users should use the install options above.

Prerequisites

xcode-select --install   # if not already installed

Run it

git clone https://github.com/ilianAZZ/mutka.git
cd mutka
npm install
npm run tauri dev        # opens the app window with hot-reload

Production build

npm run tauri build      # outputs a signed .app in src-tauri/target/release/bundle/

The big idea

A module — built-in or community — is the same shape:

export default defineModule({ id, name, version, permissions, commands, openHandlers, setup });

It imports nothing from the core. Inside setup(host) it receives a host object — its only way to reach the system. Every privileged call (host.fs.*, host.nav.*, host.dialog.*, …) is checked against the module's declared permissions.

• Built-in modules run in-process (trusted).
• Community modules run isolated in a Web Worker — a denied permission is not just refused, it is physically unreachable.

Installing modules

Open the Modules overlay inside the app to browse the community catalog (backed by GitHub — any public repo named mutka-module-* is discovered automatically), review the permissions a module declares, and install it with one click. Modules can be enabled, disabled, and uninstalled live — no restart. See Publishing a module for how the catalog works.

Building your own

Authors write modules in typed TypeScript against the published npm package @mutka-explorer/module, and scaffold a ready-to-build project with one command:

npm create @mutka-explorer@latest my-module

Continue with the Architecture overview, or jump straight to Writing a module.