# How to Contribute to Apache Maka: A Complete Guide for New Contributors

> Contribute to Apache Maka by cloning the repo, installing Node dependencies, building workspaces, and submitting a PR. Your first contribution starts here.

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

---

**To contribute to Apache Maka, clone the repository, install dependencies with Node ≥ 22.19.0, build the workspaces with `npm run build`, 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 run in desktop, TUI, CLI, or bot environments. Whether you want to add new model providers, improve the Electron desktop interface, or extend the evaluation framework, understanding the contribution workflow is essential. This guide walks you through the exact steps documented in [`CONTRIBUTING.md`](https://github.com/apache/maka/blob/main/CONTRIBUTING.md) and [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) to get you started with your first contribution.

## Understand the Apache Maka Architecture

Before writing code, familiarize yourself with the **Runtime Host** architecture. The Runtime Host serves as the central execution authority that coordinates sessions, tools, and the event log, ensuring all client types—Desktop, TUI, CLI, and bots—communicate through a single source of truth.

The project is organized into seven distinct 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`): Acts as the sole execution authority and manages admission and client capabilities
- **Eval** (`packages/eval`): Provides benchmark experiment semantics including cells, attempts, results, and budgets
- **CLI** (`packages/cli`): Implements the TUI and public command-line interface for `maka run` and `maka eval`
- **Desktop App** (`apps/desktop/src/main`): Contains the Electron composition and product-entry adapters

All clients interact with the Runtime Host rather than creating duplicate runtimes, maintaining a single source of truth for state and provenance. The detailed layer descriptions and mermaid diagrams are located in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) (lines 26-39 and 65-73).

## Set Up Your Development Environment

Configure your local environment to build and test changes across the monorepo. You will need **Node ≥ 22.19.0** and **npm ≥ 11.19.0**.

Clone the repository and install dependencies:

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

```

Build all workspaces and verify the installation:

```bash
npm run build
npm test

```

For targeted testing of specific packages, use the workspace flag:

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

```

Run the development servers based on your contribution area:

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

Before committing, validate your changes:

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

```

For UI-specific linting in the desktop or UI packages, run `npx knip --workspace apps/desktop` or `npx knip --workspace packages/ui`.

## Find and Claim Your First Issue

The project uses specific labels to guide contributors. Filter issues by **"help wanted"** or **"good first issue"** to find entry-level tasks.

To claim an issue, comment with the exact word `take`. To release it if you cannot complete the work, comment `untake`. This workflow ensures clear ownership and prevents duplicate work.

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

## Submit Your First Pull Request

Follow the branch naming and commit conventions documented in [`CONTRIBUTING.md`](https://github.com/apache/maka/blob/main/CONTRIBUTING.md) (lines 81-86).

Create a branch using **Conventional Commits** format (`<type>/<description>`):

```bash
git checkout -b feature/add-anthropic-provider

```

Make incremental commits; the final squash-merge will use the PR title as the commit message. Open a PR using the pre-filled template at [`.github/pull_request_template.md`](https://github.com/apache/maka/blob/main/.github/pull_request_template.md).

Requirements for approval:
- Obtain an approving review from a committer other than yourself
- Ensure all CI checks pass (lint, format, build, typecheck)
- Include screenshots for UI changes
- Provide a concise description of the changes

## Common Contribution Patterns

These examples illustrate typical tasks for new contributors.

### Add a New Model Provider

To integrate a new LLM provider, implement the `ModelProvider` interface in `packages/core/src/model/providers/`:

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

export class MyProvider implements ModelProvider {
  async generate(prompt: string): Promise<string> {
    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 the provider in [`packages/core/src/model/index.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model/index.ts) and add unit tests under `packages/core/tests`.

### Extend the Desktop UI

For Electron desktop improvements, modify components in the desktop app or the shared UI package:

```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>
  );
}

```

Remember to include screenshots in your PR when modifying UI components located in `packages/ui` or `apps/desktop/src/main`.

### Write an Evaluation Benchmark

Extend the evaluation framework by defining a new benchmark 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,
};

```

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

## Key Files and Packages to Know

Reference these critical paths when navigating the codebase:

- **[`CONTRIBUTING.md`](https://github.com/apache/maka/blob/main/CONTRIBUTING.md)**: Primary contribution workflow, issue claiming, and build instructions
- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)**: High-level design and runtime layer descriptions
- **`packages/core/`**: Core contracts for sessions, events, and model providers
- **`packages/runtime-host/`**: Runtime Host implementation and execution authority
- **`packages/eval/`**: Evaluation framework for experiments and benchmarks
- **`apps/desktop/`**: Electron application entry point and UI adapters
- **`packages/cli/`**: TUI and command-line interface implementation
- **[`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md)**: Detailed Runtime Host protocol boundaries

## Summary

- Apache Maka uses a **Runtime Host** architecture where all clients interface through a central execution authority
- Development requires **Node ≥ 22.19.0** and uses standard npm scripts (`build`, `test`, `dev`, `cli:dev`)
- Claim issues by commenting `take` and follow **Conventional Commits** for branch names
- Model providers reside in `packages/core/src/model/providers/`, UI components in `apps/desktop/` or `packages/ui/`, and benchmarks in `packages/eval/`
- All PRs require CI checks to pass, one approving review from a committer, and screenshots for UI changes

## Frequently Asked Questions

### What is the fastest way to get started with Apache Maka development?

Install Node ≥ 22.19.0, clone the repository, run `npm install` and `npm run build`, then execute `npm run dev` to launch the desktop app or `npm run cli:dev` for the TUI. Verify your setup by running `npm test` to ensure all existing tests pass before making changes.

### Where should I implement a new AI model provider?

Create a new file in `packages/core/src/model/providers/` implementing the `ModelProvider` interface, then register it in [`packages/core/src/model/index.ts`](https://github.com/apache/maka/blob/main/packages/core/src/model/index.ts). Add corresponding unit tests under `packages/core/tests` to validate the integration with the Runtime Host.

### How do I claim an issue so others know I am working on it?

Navigate to the issue on GitHub and comment with the exact word `take`. This automatically assigns the issue to you. If you cannot complete the work, comment `untake` to release it back to the community. Look for issues labeled "good first issue" or "help wanted" for beginner-friendly tasks.

### What are the requirements for getting a pull request merged?

You must use Conventional Commits for your branch name (e.g., `fix/variable-naming` or `feature/new-provider`), ensure all CI checks pass including lint, format, and typecheck, obtain an approving review from a committer other than yourself, and include screenshots for any UI changes. The repository automatically uses your PR title as the final squash-merge commit message.