How to Build Apache Maka from Source: A Complete Development Guide

Build Apache Maka by installing Node 22+ and npm 11, cloning the repository, running npm ci to bootstrap the monorepo, and executing npm run dev to launch the Desktop application or npm run cli:dev for the terminal interface.

Apache Maka is a multi-workspace agent platform comprising a Desktop UI (Electron + React), a TUI/CLI, and a pure-Node Runtime Host that executes model-driven tasks. Building the project from source requires setting up a modern JavaScript toolchain and understanding the monorepo structure defined in the top-level package.json. This guide walks through the exact commands and file locations needed to compile and run every component of the system.

Prerequisites

Before cloning the repository, ensure your environment meets the following requirements defined in README.md:

• Node.js ≥ 22.19 (the CI pipeline currently uses Node 24)
• npm 11 (required for the lockfile format)
• Git for version control
• ripgrep (rg) for the Runtime Host's Grep tool functionality
• Rust ≥ 1.98 and a platform linker (only required when building the peer-enabled entry point with native addons)

You can verify your Node version with node --version and install ripgrep via your system's package manager (e.g., brew install ripgrep on macOS or apt-get install ripgrep on Ubuntu).

Clone and Bootstrap the Monorepo

Apache Maka uses npm workspaces to manage dependencies across packages/ and apps/desktop. Begin by cloning the repository and performing a clean install:

git clone https://github.com/apache/maka.git
cd maka
npm ci

The npm ci command reads the top-level package-lock.json and installs every workspace dependency deterministically. This process sets up the shared Runtime Host (packages/runtime-host), the UI primitives (packages/ui), and the desktop application shell.

If you previously set ELECTRON_SKIP_BINARY_DOWNLOAD=1 to avoid downloading pre-built Electron binaries, manually install the platform binary before launching the desktop app:

node node_modules/electron/install.js

Development Workflows

The repository provides distinct development modes for the Desktop GUI, CLI/TUI, and peer-enabled builds. All commands are defined in the root package.json and delegate to individual workspaces.

Desktop Application (Electron)

To start the Desktop application with hot-module-replacement (HMR) for the React renderer:

npm run dev

For a full build of all workspaces before starting the Desktop (useful after pulling updates):

npm run dev:full

The Desktop entry point resides in apps/desktop/ and communicates with the Runtime Host via inter-process communication.

CLI and TUI

To run the command-line interface or terminal UI, first compile the workspaces, then launch the development CLI:

npm run build
npm run cli:dev

Execute one-shot tasks by passing arguments after the double dash:

npm run cli:dev -- run "Summarize this repository and identify architectural risks"

Use the --graph flag to request a durable graph execution in non-interactive mode.

Peer-Enabled Builds (Rust Native Addon)

If you intend to build the peer-enabled version that compiles Rust native add-ons for direct-peer functionality:

npm run dev:peer       # HMR with native addon built on-the-fly

npm run dev:full:peer  # Full build of all workspaces + native addon

These commands invoke the Rust toolchain to compile platform-specific binaries. Ensure cargo is available in your PATH before running.

Production Builds

To generate distributable artifacts like .dmg (macOS), .exe (Windows), or .AppImage (Linux):

npm run build
npm --workspace @maka/desktop run dist

The npm run build command compiles all TypeScript workspaces and bundles Electron assets. The distribution step uses electron-builder configured in apps/desktop/electron-builder.config.mjs, outputting installers to apps/desktop/dist/.

Run end-to-end tests against the production build:

npm --workspace @maka/desktop run e2e
npm --workspace @maka/desktop run smoke:real-window

Architecture Overview

Understanding the build structure helps debug compilation issues. Apache Maka uses a directed execution chain:

Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun
                                         ↓
                          Model + Tool Runtime → RuntimeEvent Log

All front-ends communicate with a single Runtime Host (packages/runtime-host) that owns the execution loop. The host records every model message, tool call, and permission decision as an append-only RuntimeEvent log. The UI layer (packages/ui) merely renders projections of this immutable log, while the Desktop shell (apps/desktop) provides the Electron container.

Summary

• Install Node 22+ and npm 11 before attempting to build; Rust 1.98+ is only needed for peer-enabled features.
• Bootstrap with npm ci in the repository root to install all workspace dependencies deterministically.
• Start development using npm run dev for Desktop hot-reloading or npm run cli:dev for the terminal interface.
• Build production artifacts with npm run build followed by the workspace-specific dist command.
• Locate key configurations in package.json (workspaces), apps/desktop/electron-builder.config.mjs (packaging), and packages/runtime-host/ (execution engine).

Frequently Asked Questions

What are the minimum system requirements for building Apache Maka?

You need Node.js version 22.19 or higher and npm 11 to match the lockfile format. The build also requires Git and ripgrep (rg) because the Runtime Host's Grep tool depends on it for file searching. Rust is only necessary if you are compiling the peer-enabled native addon.

How do I build the peer-enabled version with Rust support?

Run npm run dev:peer for development with hot-reload or npm run dev:full:peer for a complete production-like build. These commands trigger the Rust compiler for the native addon in addition to the standard TypeScript build. Ensure Rust 1.98+ and a platform linker are installed before executing these commands.

Can I run Apache Maka without the Desktop application?

Yes. After running npm run build to compile the workspaces, use npm run cli:dev to launch the terminal interface. This provides full access to the Runtime Host and agent execution capabilities without Electron dependencies, though you lose the graphical React-based UI.

Why does the build require ripgrep?

The Runtime Host includes a Grep tool that delegates to the rg binary for high-performance file searching. During the build process, the presence of ripgrep is assumed for both the tool's runtime functionality and certain development scripts. Install it via your system's package manager before running npm ci.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}