# Key Packages in Apache Maka: Monorepo Architecture Guide > Explore Apache Maka's key packages, from core contracts to desktop apps. Discover how its monorepo architecture separates layers for composable development. - Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka) - Tags: architecture - Published: 2026-09-11 --- **Apache Maka organizes its codebase into ten focused npm workspaces—ranging from `@maka/core` for type contracts to `apps/desktop` for the Electron GUI—that separate persistence, model integration, runtime execution, and user interfaces into distinct, composable layers.** Apache Maka is structured as a monorepo using npm workspaces to separate concerns across the AI agent stack. The **key packages in Apache Maka** reside under `packages/` for library code and `apps/` for the desktop application, each defined in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json) workspaces array. This architecture enables independent versioning while maintaining strict contractual guarantees between storage, runtime, and interface layers. ## Core Infrastructure Packages The foundation of Apache Maka rests on three packages that define contracts, persistence, and model integration. ### @maka/core **`@maka/core`** provides pure TypeScript contracts and utilities shared across the entire system. Located in `packages/core/`, it exports universal data structures including `runtime-event`, `session`, `permission`, `workspace-version-authority`, and `model-metadata`. The source file [`packages/core/src/workspace-version-authority.ts`](https://github.com/apache/maka/blob/main/packages/core/src/workspace-version-authority.ts) defines the version control abstractions that enforce consistency across workspace states. This package contains no implementation-specific logic—only interfaces and type guards—ensuring that downstream packages like `@maka/storage` and `@maka/runtime` speak the same language when handling events or permission checks. ### @maka/storage **`@maka/storage`** implements SQLite-backed persistence for all runtime state. Residing in `packages/storage/`, it exposes stores such as `workspace-root`, `session-store`, `credential-store`, and `runtime-event-persistence` through the main `sqlite-runtime-store` interface. The [`packages/storage/src/workspace-root.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/workspace-root.ts) file manages the root directory configuration and database connection lifecycle. This package translates the abstract contracts from `@maka/core` into durable records, handling migrations, encryption at rest for credentials, and long-term memory archival without exposing SQLite specifics to the runtime layer. ### @maka/mcp **`@maka/mcp`** implements the Model Context Protocol client. This provider-neutral layer handles model catalog refresh, capability negotiation, and connection management to external model providers. While its exports are compiled into `dist/` from TypeScript sources in `packages/mcp/src/`, the package serves as the bridge between external AI models and Maka's internal representations. It transforms provider-specific metadata into the standard `model-metadata` format defined in `@maka/core`, enabling the runtime to remain agnostic about whether it is talking to Claude, GPT, or local models. ## Execution and Runtime Layer The agent execution engine splits responsibility between the raw runtime and the host orchestrator. ### @maka/runtime **`@maka/runtime`** implements the core **AgentRun** abstraction—the heart of Apache Maka's execution model. Located in `packages/runtime/`, this package adapts model prompts to executable actions, manages the tool registry, and archives results. Key modules include `tool-runtime`, `tool-result-archive`, `unified-diff`, and `workspace-executor`. The file [`packages/runtime/src/workspace-executor.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/workspace-executor.ts) coordinates file operations across the workspace, while `web-fetch-tool` and similar modules implement specific capabilities. Every action generates a `RuntimeEvent` (defined in `@maka/core`) that gets recorded in the event log for debugging and replay. ### @maka/runtime-host **`@maka/runtime-host`** serves as the "single-owner" controller that bootstraps and mediates agent sessions. Found in `packages/runtime-host/`, it exposes a stable API for the Desktop, TUI, and CLI clients through modules like `runtime-host-cli` and `runtime-host-service-manager`. The [`packages/runtime-host/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/runtime-host-cli.ts) entry point handles command-line initialization, while `runtime-host-update-policy-store` manages version compatibility between the host and runtime components. This package also includes peer-mesh support for distributed execution scenarios, ensuring that only one host owns a given session at a time. ## User Interfaces and Computer Control The presentation layer separates UI primitives from specific host implementations. ### @maka/computer-use **`@maka/computer-use`** determines the appropriate backend for executing computer-use actions—whether through the desktop application, TUI, or remote protocols. Located in `packages/computer-use/`, it translates high-level actions like "edit file" or "run shell command" into concrete tool invocations. This package acts as a router, selecting between local execution (via Electron APIs) and remote execution (via SSH or Docker) based on the current session configuration defined in the `session` contract from `@maka/core`. ### @maka/cli **`@maka/cli`** provides the non-interactive command-line interface and the TUI (Text User Interface) front-end. Located in `packages/cli/`, it offers `runtime-host-cli` integration, `session-driver` for turn-based execution, and `pi-tui` utilities for terminal-based interaction. Developers use this package to run single turns, inspect session logs, or launch the full desktop UI. It imports the runtime host API to bootstrap sessions while rendering markdown and artifacts using primitives from `@maka/ui`. ### @maka/ui **`@maka/ui`** supplies shared visual components used across the Desktop, TUI, and web documentation. Located in `packages/ui/`, it exports `ui-locale` for internationalization, `skill-invocation` components, `artifact` renderers, and `markdown` processors. This package ensures consistent display of code blocks, diff views, and model outputs regardless of whether the user is in the Electron app or a terminal browser. ### apps/desktop **`apps/desktop`** is the Electron-based graphical application that brings the entire stack together. Located at the repository root under `apps/desktop/`, it integrates the runtime host, renders UI primitives from `@maka/ui`, and provides native system integration. The entry point [`apps/desktop/main.ts`](https://github.com/apache/maka/blob/main/apps/desktop/main.ts) initializes the Electron main process, loads preload scripts for secure IPC, and spins up the React renderer. This package is the only workspace under `apps/` rather than `packages/`, distinguishing end-user applications from reusable libraries. ## Evaluation and Experimentation ### @maka/eval **`@maka/eval`** implements the experiment framework for benchmarking and research. Located in `packages/eval/`, it runs "cells"—individual attempts against a subject—collects results, and scores them using modules like `runner`, `spec`, and `metering-checkpoint`. The [`packages/eval/src/runner.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/runner.ts) file orchestrates the execution loop, storing attempts and results in a structured form compatible with the storage layer. This package depends on `@maka/runtime-host` to execute reproducible experiments while adding statistical aggregation and report generation capabilities. ## Package Integration Architecture The **key packages in Apache Maka** form a strict dependency chain enforced by the workspace configuration in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json): 1. **`@maka/core`** defines universal contracts (events, sessions, permissions) that every other package imports. 2. **`@maka/storage`** implements durable persistence for those contracts, exposing stores that the runtime host can read and write. 3. **`@maka/mcp`** pulls model catalogs and negotiates capabilities, feeding the runtime with standardized metadata. 4. **`@maka/runtime`** executes the AgentRun by interpreting prompts, invoking tools, and recording each step as a `RuntimeEvent`. 5. **`@maka/runtime-host`** orchestrates session lifecycle, bootstraps the runtime, and provides a stable API for UI clients. 6. **`@maka/eval`** builds atop the runtime host to run reproducible experiments, storing attempts in the SQLite backend. 7. **`@maka/computer-use`** routes high-level actions to the appropriate host implementation (desktop, TUI, or remote). 8. **`@maka/cli`** offers the command-line and TUI front-end that drives the runtime host directly. 9. **`@maka/ui`** supplies reusable visual components for rendering markdown and artifacts across contexts. 10. **`apps/desktop`** brings all layers together in an Electron shell, providing the native GUI experience. This architecture ensures that changes to storage implementations never affect UI components, and that model protocol changes in `@maka/mcp` propagate predictably through the runtime layer without breaking the eval framework. ## Summary - **Contract Layer**: `@maka/core` enforces type safety across the monorepo through files like [`workspace-version-authority.ts`](https://github.com/apache/maka/blob/main/workspace-version-authority.ts). - **Persistence**: `@maka/storage` handles all SQLite operations via [`workspace-root.ts`](https://github.com/apache/maka/blob/main/workspace-root.ts) and related stores. - **Model Integration**: `@maka/mcp` abstracts provider-specific protocols into standardized metadata. - **Execution**: `@maka/runtime` runs AgentRuns with [`workspace-executor.ts`](https://github.com/apache/maka/blob/main/workspace-executor.ts), while `@maka/runtime-host` manages session lifecycle. - **Interfaces**: `@maka/cli` and `apps/desktop` provide command-line and graphical entry points, both consuming `@maka/ui` primitives. - **Evaluation**: `@maka/eval` enables benchmarking through the [`runner.ts`](https://github.com/apache/maka/blob/main/runner.ts) module. - **Workspace Structure**: All packages are npm workspaces defined in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json), enabling independent builds with shared TypeScript configuration. ## Frequently Asked Questions ### What is the difference between @maka/runtime and @maka/runtime-host? **`@maka/runtime`** contains the execution engine that interprets model prompts and invokes tools like `web-fetch-tool` or `unified-diff`, generating `RuntimeEvent` logs. **`@maka/runtime-host`** acts as the controller that boots the runtime, manages session state transitions, and exposes a stable API for CLI and Desktop clients through [`runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/runtime-host-cli.ts). The runtime performs the work; the host manages the lifecycle and ownership of that work. ### How does @maka/core enforce contracts across the monorepo? `@maka/core` exports pure TypeScript interfaces and types—such as `session`, `permission`, and `runtime-event`—from files like [`packages/core/src/workspace-version-authority.ts`](https://github.com/apache/maka/blob/main/packages/core/src/workspace-version-authority.ts). Downstream packages import these types rather than defining their own, ensuring that storage, runtime, and UI layers agree on data shapes. Because it has no external dependencies and contains no implementation logic, it serves as the universal source of truth for cross-package communication. ### Where is the desktop application code located in Apache Maka? The desktop application resides in `apps/desktop/` rather than `packages/`, distinguishing it as an end-user application rather than a reusable library. The entry point is [`apps/desktop/main.ts`](https://github.com/apache/maka/blob/main/apps/desktop/main.ts), which initializes the Electron main process and integrates the runtime host from `@maka/runtime-host` with UI primitives from `@maka/ui`. This workspace is listed alongside the library packages in the root [`package.json`](https://github.com/apache/maka/blob/main/package.json) workspaces array. ### Which package handles Model Context Protocol (MCP) integration? `**@maka/mcp**` manages all MCP client functionality, including model catalog refresh, capability negotiation, and connection management. It transforms provider-specific metadata into the standard formats defined in `@maka/core`, allowing the runtime to remain provider-agnostic. The source lives in `packages/mcp/src/`, with compiled exports available in the package's `dist/` directory.