# How to Contribute to Apache Maka: A Complete Guide for Developers

> Contribute to Apache Maka easily. Clone the repo, install dependencies, build the project, and submit your PRs following our contribution guide.

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

---

**To contribute to Apache Maka, clone the repository, install Node.js 22.19.0 or higher, run `npm install` and `npm run build`, then claim an issue by commenting "take" and submit a PR following the Conventional Commits branch naming convention.**

Apache Maka is a modular, multi-client system for building AI-driven agents that operate across desktop, TUI, CLI, and bot environments. The project welcomes contributions ranging from bug fixes and new model providers to UI improvements and evaluation framework extensions. This guide walks you through the complete workflow based on the official source code in the `apache/maka` repository.

## Understand the Apache Maka Architecture

Before you contribute to Apache Maka, familiarize yourself with its layered architecture to identify where your changes should live. The system centers on a **Runtime Host** that serves as the sole execution authority, managing sessions, tools, and the event log while exposing a public client protocol.

According to [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) (lines 26-39 and 65-73), the architecture consists of these key layers:

- **Core** (`packages/core`): Handles sessions, the Runtime Event Log, AgentRun, and permission contracts
- **Storage** (`packages/storage`): Manages interactive runtime state and the SQLite control plane
- **Runtime** (`packages/runtime`): Contains SessionManager, model adapters, tools, context recovery, and graph reconciliation
- **Runtime-Host** (`packages/runtime-host`): The central authority coordinating all client types through a single source of truth
- **Eval** (`packages/eval`): Provides benchmark experiment semantics including cells, attempts, results, and budgets
- **CLI** (`packages/cli`): Delivers the TUI, `maka run`, and `maka eval` command-line interfaces
- **Desktop App** (`apps/desktop/src/main`): Electron-based composition layer and product-entry adapters

All client implementations—whether Desktop, TUI, CLI, or bots—communicate through the Runtime Host rather than creating duplicate runtimes. This ensures consistent state management and provenance tracking across all interfaces.

## Set Up Your Development Environment

To build and test Apache Maka locally, ensure you have **Node.js ≥ 22.19.0** and **npm ≥ 11.19.0** installed.

Clone the repository and install dependencies:

```bash
git clone https://github.com/apache/maka.git
cd maka
npm install

```

Build all workspaces in the monorepo:

```bash
npm run build

```

Run the complete test suite to verify your environment:

```bash
npm test

```

For workspace-specific testing, use the `--workspace` flag:

```bash
npm --workspace @maka/core run test:dist

```

Start the development servers based on your contribution focus:

- **Desktop app with hot-module replacement**: `npm run dev`
- **CLI/TUI development mode**: `npm run cli:dev`

Before committing changes, validate code quality:

```bash
npm run lint
npm run format:check
npm run typecheck

```

For UI-specific contributions, additionally run:

```bash
npx knip --workspace apps/desktop
npx knip --workspace packages/ui

```

These steps are documented in the "Quick start" and "Developing Maka" sections of [`CONTRIBUTING.md`](https://github.com/apache/maka/blob/main/CONTRIBUTING.md).

## Find and Claim Your First Issue

The Apache Maka project uses GitHub labels to organize contribution opportunities. Look for issues tagged **"help wanted"** or **"good first issue"** to identify accessible entry points.

To claim an issue, comment with the exact word `take`. If you need to release the issue, comment `untake`. This workflow prevents duplicate work and signals to maintainers that you are actively working on the problem.

- **Help wanted issues**: https://github.com/apache/maka/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22
- **Good first issues**: https://github.com/apache/maka/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22

## Submit Your First Pull Request

Once you have completed your changes, follow the structured PR process defined in [`CONTRIBUTING.md`](https://github.com/apache/maka/blob/main/CONTRIBUTING.md) (lines 81-86).

### Branch Naming and Commits

Create branches following the **Conventional Commits** specification with the format `<type>/<description>`. Examples include `feat/add-anthropic-provider` or `fix/session-memory-leak`.

Make incremental commits during development. The repository uses squash-merge, meaning your PR title becomes the final commit message, so ensure it clearly describes the change.

### PR Requirements

Open a PR using the pre-filled template from [`.github/pull_request_template.md`](https://github.com/apache/maka/blob/main/.github/pull_request_template.md). You must obtain an **approving review** from a committer other than yourself and ensure all CI checks pass, including lint, format, build, and typecheck.

For UI changes in `apps/desktop` or `packages/ui`, include screenshots in your PR description to demonstrate visual modifications.

## Common Contribution Patterns

Depending on your expertise, contributions to Apache Maka typically fall into three categories: extending model providers, enhancing the desktop UI, or building evaluation benchmarks.

### Adding a New Model Provider

Model providers live in `packages/core/src/model/providers/`. To add support for a new AI provider, implement the `ModelProvider` interface:

```typescript
// packages/core/src/model/providers/myProvider.ts
import { ModelProvider } from "./ModelProvider";

export class MyProvider implements ModelProvider {
  async generate(prompt: string): Promise<string> {
    // Call the external API here
    const resp = await fetch("https://api.myprovider.com/v1/completions", {
      method: "POST",
      headers: { "Authorization": `Bearer ${process.env.MY_PROVIDER_KEY}` },
      body: JSON.stringify({ prompt })
    });
    const data = await resp.json();
    return data.text;
  }
}

```

Register your provider in [`packages/core/src/model/index.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model/index.ts) and add corresponding unit tests under `packages/core/tests`.

### Extending the Desktop UI

The desktop application is built with Electron and located in `apps/desktop/src/main/`. UI components are shared through `packages/ui`.

```tsx
// apps/desktop/src/main/ui/SettingsPanel.tsx
import { Switch } from "@maka/ui";

export function SettingsPanel() {
  return (
    <div className="settings">
      <h2>Preferences</h2>
      <Switch label="Enable auto-run" />
    </div>
  );
}

```

Include screenshots with your PR when modifying UI components. Run `npx knip` on the relevant workspace to check for unused dependencies.

### Writing an Evaluation Benchmark

Evaluation benchmarks define experiment semantics for testing agent performance. Create benchmarks in `packages/eval/src/benchmarks/`:

```typescript
// packages/eval/src/benchmarks/myBenchmark.ts
import { Benchmark } from "./Benchmark";

export const myBenchmark: Benchmark = {
  name: "My Benchmark",
  subjects: ["gpt-4", "claude-2"],
  tasks: [{ prompt: "Summarize the following text…" }],
  repetitions: 3,
};

```

Export the benchmark from [`packages/eval/src/index.ts`](https://github.com/apache/maka/blob/main/packages/eval/src/index.ts) and add tests verifying cell generation and attempt handling.

## Summary

- **Apache Maka** uses a Runtime Host architecture where all clients communicate through a central execution authority in `packages/runtime-host`
- **Setup requirements**: Node.js ≥ 22.19.0, npm ≥ 11.19.0, and standard npm workflow commands (`npm install`, `npm run build`, `npm test`)
- **Issue workflow**: Comment `take` to claim issues labeled "help wanted" or "good first issue"
- **PR standards**: Use Conventional Commits branch naming (`<type>/<description>`), ensure CI passes (lint, format, typecheck), and obtain committer review
- **Key contribution areas**: Model providers in `packages/core`, Desktop UI in `apps/desktop`, and evaluation benchmarks in `packages/eval`

## Frequently Asked Questions

### What are the system requirements for contributing to Apache Maka?

You need Node.js version 22.19.0 or higher and npm version 11.19.0 or higher. The project is organized as a monorepo using npm workspaces, so all dependencies are managed at the root level with `npm install`.

### How do I claim an issue to work on in Apache Maka?

Navigate to the GitHub Issues page and find issues labeled "help wanted" or "good first issue". Comment the exact word `take` on the issue you want to work on. To release an issue you can no longer complete, comment `untake`.

### What should I include in my first pull request to Apache Maka?

Create a branch named using the Conventional Commits format (e.g., `fix/typo-in-readme` or `feat/add-new-provider`). Ensure your PR passes all CI checks including `npm run lint`, `npm run format:check`, and `npm run typecheck`. Include screenshots for any UI changes and follow the pre-filled template from [`.github/pull_request_template.md`](https://github.com/apache/maka/blob/main/.github/pull_request_template.md).

### Where can I find detailed architectural documentation for Apache Maka?

The [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) file in the repository root describes the high-level design, including the Runtime Host authority and package boundaries. For Runtime Host specifics, see [`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md). Implementation details for specific layers are found in `packages/core`, `packages/runtime`, and `packages/runtime-host`.