Key Packages in Apache Maka: Monorepo Architecture Guide

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 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 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 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 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 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 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 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:

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.
• Persistence: @maka/storage handles all SQLite operations via 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, 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 module.
• Workspace Structure: All packages are npm workspaces defined in the root 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. 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. 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, 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 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.

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