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

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

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

Build all workspaces in the monorepo:

npm run build

Run the complete test suite to verify your environment:

npm test

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

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:

npm run lint
npm run format:check
npm run typecheck

For UI-specific contributions, additionally run:

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.

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

// 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 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.

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

// 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 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.

Where can I find detailed architectural documentation for Apache Maka?

The 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. Implementation details for specific layers are found in packages/core, packages/runtime, and packages/runtime-host.

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