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

> Find Apache Maka source files on GitHub at apache/maka. Explore the monorepo structure, including desktop apps, core packages, runtime, and native Rust components.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/core/src/workhub-action-result.ts), which defines the data model for action outcomes, and [`packages/core/src/workspace-version-authority.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts) file orchestrates tool execution within a turn, while [`packages/runtime/src/web-fetch-tool.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/apps/desktop/src/main/main.ts)** – Bootstraps the Electron main process.
- **[`packages/core/src/workhub-action-result.ts`](https://github.com/apache/maka/blob/main/packages/core/src/workhub-action-result.ts)** – Defines the core data model for action outcomes.
- **[`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)** – Orchestrates execution of tools within a turn.
- **[`packages/runtime-host/src/transport/websocket-transport.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/transport/websocket-transport.ts)** – Implements the WebSocket transport used by Desktop, TUI, and CLI clients.
- **[`docs/ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/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:

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

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

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

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.