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

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

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

Build all workspaces and verify the installation:

npm run build
npm test

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

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:

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 (lines 81-86).

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

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.

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

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

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

// 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 and add tests verifying cell generation.

Key Files and Packages to Know

Reference these critical paths when navigating the codebase:

• CONTRIBUTING.md: Primary contribution workflow, issue claiming, and build instructions
• 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: 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. 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.

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