Apache Maka Monorepo: Complete Guide to the Main Packages in the Repository

The Apache Maka repository organizes its functionality into ten first-party npm packages under the packages/ directory, providing modular React components, runtime engines, storage abstractions, and CLI tooling.

Apache Maka is an open-source framework for building AI-powered desktop applications, structured as a monorepo that separates concerns into discrete, reusable npm packages. Understanding the main packages in the Maka repository is essential for developers extending the platform or consuming specific modules. Each package maintains its own package.json and source directory, exposing functionality through scoped @maka/* imports or the global maka CLI.

UI Components and Frontend Infrastructure

The @maka/ui package provides reusable React components, Storybook stories, and UI utilities that power the desktop client. According to packages/ui/package.json, the library exports components like the Toast notification system from packages/ui/src/toast.tsx.

import { Toast } from '@maka/ui';

// Show a toast notification from anywhere in the app
Toast.show({ message: 'Hello from Maka!', type: 'info' });

The @maka/website package handles static site generation for documentation, Storybook hosting, and release notes. While not part of the core runtime, it supports the website/ directory and manages the project's documentation build pipeline as defined in website/package.json.

Runtime Engine and Execution Host

The execution layer splits responsibilities between the runtime engine and its sandboxed host process. The @maka/runtime package, defined in packages/runtime/package.json, contains the core runtime engine that orchestrates tool execution, transcript handling, and skill management. It works in conjunction with @maka/core, located in packages/core/, which provides low-level utilities, type definitions, and the ToolRegistry used across all packages.

import { Runtime } from '@maka/runtime';
import { ToolRegistry } from '@maka/core';

// Register a simple echo tool
ToolRegistry.register('echo', {
  async run(input) {
    return `Echo: ${input}`;
  },
});

const runtime = new Runtime();
runtime.executeTool('echo', 'test input')
  .then(console.log); // → "Echo: test input"

The @maka/runtime-host package in packages/runtime-host/ implements the host process responsible for running the runtime in a sandboxed environment. According to packages/runtime-host/package.json, it manages IPC channels, WebSocket transport layers, and peer-to-peer streams, isolating tool execution from the main application process.

Control Plane and Data Persistence

The @maka/mcp (Maka Control Plane) package, specified in packages/mcp/package.json, provides central control-plane services including authentication, policy enforcement, and multi-session coordination. This package acts as the security and orchestration backbone for the desktop application.

For data management, the @maka/storage package in packages/storage/ offers abstractions for persisting user data, session history, and configuration files. The Apache Maka source code indicates this layer ensures durable state management across application restarts.

Evaluation Framework and Computer-Use Abstractions

Testing and agent capabilities reside in two specialized packages. The @maka/eval package in packages/eval/ contains the evaluation framework used for testing toolchains, policies, and sandbox behaviors, providing utilities for automated validation of runtime configurations.

The @maka/computer-use package in packages/computer-use/ delivers high-level abstractions that model "computer-use" actions such as mouse clicks and keyboard input for tool agents. This package bridges AI agent logic with system-level interaction primitives.

Command Line Interface

The maka-agent package, exposed as the maka CLI, lives in packages/cli/ and serves as the primary command-line interface. Defined in packages/cli/package.json, it boots the desktop client, bundles the runtime, and provides developer utilities. The entry point is implemented in packages/cli/src/cli.ts and referenced in the package's bin field.

# Install the CLI globally (or use npx)

npm i -g maka-agent

# Launch the desktop client

maka start --workspace my-workspace

The desktop application (apps/desktop) consumes these packages through the monorepo's Yarn/PNPM workspace configuration, while external developers can install individual @maka/* packages directly from npm.

Summary

The Apache Maka monorepo divides functionality into logical, reusable modules:

• @maka/ui: React component library and UI utilities located in packages/ui/
• @maka/runtime: Core engine for tool execution and skill management in packages/runtime/
• @maka/runtime-host: Sandboxed host process for secure execution in packages/runtime-host/
• @maka/mcp: Control-plane services for authentication and policy enforcement in packages/mcp/
• @maka/storage: Persistence layer for user data and configuration in packages/storage/
• @maka/core: Shared utilities and type definitions in packages/core/
• @maka/eval: Testing framework for toolchains and policies in packages/eval/
• @maka/computer-use: Abstractions for AI agent system interactions in packages/computer-use/
• maka-agent: Command-line interface and desktop launcher in packages/cli/
• @maka/website: Documentation and static site generation in website/

Each package maintains strict boundaries defined by its package.json, allowing selective consumption of Maka's capabilities without importing the entire framework.

Frequently Asked Questions

What is the difference between @maka/runtime and @maka/runtime-host?

The @maka/runtime package contains the orchestration logic for executing tools and managing transcripts, while @maka/runtime-host runs the runtime in a sandboxed environment handling IPC and WebSocket transport. The runtime-host isolates execution for security, whereas the runtime manages the business logic of tool invocation according to packages/runtime/package.json and packages/runtime-host/package.json.

How do I use individual Maka packages without installing the full desktop application?

External consumers can install specific scoped packages directly from npm using commands like npm install @maka/ui or npm install @maka/core. The monorepo structure allows you to import only the functionality you need, though the maka-agent CLI requires the full runtime environment to boot the desktop client.

Which package contains the type definitions shared across Maka?

The @maka/core package in packages/core/ serves as the foundation for all other modules, exporting TypeScript definitions, the ToolRegistry class, and low-level utilities. It is a peer dependency for most other packages in the repository and ensures type consistency across the framework as specified in packages/core/package.json.

Where is the source code for the maka CLI command located?

The CLI implementation resides in packages/cli/src/cli.ts with its package configuration defined in packages/cli/package.json. The executable is published to npm as maka-agent but exposes the binary name maka for command-line usage, as specified in the package's bin field.

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