Where to Find Apache Maka Source Files: A Complete Monorepo Guide

Apache Maka source files are hosted on GitHub at https://github.com/apache/maka and organized as a multi-package monorepo with top-level directories for the desktop application (apps/desktop), core contracts (packages/core), runtime engine (packages/runtime), and native Rust components (native/).

If you are looking to explore or contribute to the Apache Maka source files, you will find a modular architecture that separates concerns by functional area. The repository uses a monorepo structure where TypeScript packages handle the application logic, while Rust code manages performance-critical native operations.

Repository Structure Overview

The Apache Maka codebase divides functionality into distinct top-level directories. Each area contains source files that you can navigate based on the component you need to modify or understand.

Desktop Application (apps/desktop)

The Electron-based client that runs on macOS, Windows, and Linux lives here. This directory contains the main process bootstrap, preload scripts, and the React renderer. The primary entry point for the main process is located at apps/desktop/src/main/main.ts.

Core Contracts (packages/core)

This package defines framework-agnostic TypeScript interfaces for sessions, events, permissions, and model connections. Key files include packages/core/src/workhub-action-result.ts, which defines the data model for action outcomes, and packages/core/src/workspace-version-authority.ts, which manages workspace schema versions.

Runtime Engine (packages/runtime)

The heart of the agent workspace implements the execution engine, tool implementations, and model adapters. The packages/runtime/src/tool-runtime.ts file orchestrates tool execution within a turn, while packages/runtime/src/web-fetch-tool.ts provides the built-in web fetching capability.

Runtime Host (packages/runtime-host)

This single-owner host boots the runtime, manages peer connections, and handles protocol plumbing for the Desktop, TUI, and CLI clients. The WebSocket transport implementation resides in packages/runtime-host/src/transport/websocket-transport.ts.

Storage Layer (packages/storage)

Manages the SQLite persistence layer for operational state, configuration, and artifact payloads. This package handles the on-disk database and schema migrations for the runtime event log.

Command-Line Interface (packages/cli)

Contains the non-graphical command-line interface and text UI. This package provides the maka commands for scripting and automation, with its entry point typically found in the packages/cli/src/ directory.

UI Components (packages/ui)

Shared React components, Markdown rendering, and transcript handling primitives live here. Files like packages/ui/src/transcript-viewport-navigation.ts provide reusable UI elements for rendering session transcripts across different front-ends.

Native Components (native/)

Low-level performance-critical components written in Rust, including the direct-peer addon and git-oxide helper. The Rust source is organized under native/ with build configurations for platform-specific compilation.

Evaluation Suite (packages/eval)

Supports the experiment framework used for benchmarking, including cells, attempts, and results tracking. This package is essential for running the evaluation suite shipped with the repository.

Computer Use Backend (packages/computer-use)

Implements the backend for executing commands on the host machine, providing safe sandboxed execution of tools.

Documentation and Website (docs/ and website/)

The docs/ directory contains architecture diagrams, design notes, and ARCHITECTURE.md, which offers a high-level system map. The website/ directory houses the Astro-based static site that powers the official documentation at maka.apache.org.

Key Entry Points in the Apache Maka Source

When navigating the Apache Maka source files for the first time, start with these specific files to understand the system architecture:

• apps/desktop/src/main/main.ts – Bootstraps the Electron main process.
• packages/core/src/workhub-action-result.ts – Defines the core data model for action outcomes.
• packages/runtime/src/tool-runtime.ts – Orchestrates execution of tools within a turn.
• packages/runtime-host/src/transport/websocket-transport.ts – Implements the WebSocket transport used by Desktop, TUI, and CLI clients.
• docs/ARCHITECTURE.md – Provides the high-level system map and component interaction diagrams.

Working with Apache Maka Source Code: Practical Examples

Below are concrete examples demonstrating how to import and use components from the Apache Maka source files in your own code.

Starting a Runtime Session

To programmatically start a session using the runtime host, import the WorkspaceVersionAuthority and RuntimeHost classes:

import { WorkspaceVersionAuthority } from '@maka/core/src/workspace-version-authority';
import { RuntimeHost } from '@maka/runtime-host/src/transport/websocket-transport';

// Create a host (WebSocket transport is the default for Desktop/TUI)
const host = new RuntimeHost();

// Load a workspace version (the authority decides which schema/version to use)
const version = await WorkspaceVersionAuthority.load('default');

// Start the session
const session = await host.startSession({ workspaceVersion: version });

console.log('Session started with ID:', session.id);

Using the Web Fetch Tool

The runtime includes built-in tools that you can instantiate directly. Here is how to use the web fetch tool:

import { WebFetchTool } from '@maka/runtime/src/web-fetch-tool';

async function fetchPage(url: string) {
  const tool = new WebFetchTool();
  const result = await tool.run({ url });
  console.log('Fetched', result.content.length, 'bytes');
}
fetchPage('https://example.com');

Rendering a Transcript Component

For UI development, you can import shared React components from the UI package:

import { TranscriptViewportNavigation } from '@maka/ui/src/transcript-viewport-navigation';

// Inside a React component
return (
  <TranscriptViewportNavigation
    transcriptId="session-123"
    initialPage={0}
  />
);

Running CLI Commands Programmatically

You can invoke the CLI from Node.js scripts using child process execution:

import { execSync } from 'child_process';

// Run a single turn from a script
execSync('npm run cli:dev -- run "Summarize this repository"', { stdio: 'inherit' });

Summary

• Apache Maka source files are located at https://github.com/apache/maka and organized as a TypeScript/Rust monorepo.
• apps/desktop/ contains the Electron client source, with apps/desktop/src/main/main.ts as the main process entry point.
• packages/core/ defines the shared TypeScript contracts and domain models.
• packages/runtime/ houses the agent execution engine and tool implementations like WebFetchTool.
• packages/runtime-host/ manages the transport layer and session bootstrapping.
• native/ contains performance-critical Rust components for direct-peer communication.
• docs/ARCHITECTURE.md provides the definitive high-level architecture documentation.

Frequently Asked Questions

What is the main entry point for the Apache Maka desktop application?

The main entry point for the desktop application is apps/desktop/src/main/main.ts, which bootstraps the Electron main process. This file initializes the application window, sets up the preload scripts, and establishes communication with the renderer process.

Where are the TypeScript interface definitions located in Apache Maka?

All framework-agnostic TypeScript interfaces, including session definitions, event types, and permission models, are located in the packages/core/src/ directory. Files like packages/core/src/workhub-action-result.ts define the data structures used across the entire system.

How is the runtime event log persisted in Apache Maka?

The runtime event log is persisted to a SQLite database managed by the packages/storage module. This package handles schema migrations and operational state storage, writing immutable RuntimeEvent records to a file typically named runtime.sqlite.

Where can I find the Rust components in the Apache Maka repository?

Rust source files for performance-critical components are located in the native/ directory at the repository root. This includes the direct-peer addon and git-oxide helper, which provide low-level system integrations that TypeScript cannot handle efficiently.

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