apache/maka installation guide

Install Apache Maka on macOS Tahoe (Apple silicon)

What Maka is—and how it relates to Claude Code

Apache Maka (Incubating) is a **local-first AI-agent workspace** with a desktop app, terminal interface, non-interactive CLI, and evaluation tooling. It can connect to cloud APIs, local models, or compatible gateways. Its built-in agent tools include reading, writing, editing, shell execution, file globbing, and text search. Sessions, model messages, tool calls, results, permissions, and termination events are recorded locally.

**Claude Code classification:** **standalone application; runs alongside Claude Code.** The supplied first-party files do not document a Claude Code plugin, hook, skill, MCP server for Claude Code, or any other native Claude Code integration. Maka has its own agent runtime and interfaces, so it is best understood as an alternative or companion rather than a Claude Code extension.

This guide covers three supported routes:

1. **Desktop Nightly** — simplest graphical route.
2. **Published CLI beta** — simplest terminal route.
3. **Source checkout** — for development and testing.

Maka is still incubating and under active development. The current Desktop Nightly and npm beta are not Apache Software Foundation releases and are not intended as stable production releases. Commands and local-data formats may change.

Compatibility with your Mac

The project currently targets **Apple silicon (`arm64`) Macs**. Its CLI release gate validates macOS arm64 with Node.js 24. The minimum documented Node.js version is 22.19.0.

The supplied files do not name macOS Tahoe specifically or provide a Tahoe-specific compatibility guarantee. They do establish current macOS Apple-silicon support. Intel Macs are not supported for Desktop.

Before you begin

Choose only the prerequisites needed for your route:

• **Desktop Nightly:** an Apple-silicon Mac and a model connection you can configure after launch.
• **Published CLI:** Node.js 22.19.0 or newer, npm, and an interactive terminal for the TUI. Node.js 24 is the specifically validated macOS arm64 combination.
• **Source checkout:** Node.js 22.19 or newer, npm, Git, and `ripgrep`. The repository currently uses npm 11, and CI uses Node.js 24.

The supplied documentation does not provide Homebrew, Node installer, Git installer, or `ripgrep` installation commands. Install missing prerequisites from their first-party distributions; do not paste an undocumented package-manager command from this guide.

If you plan to work specifically on Direct Peer or Peer Mesh development, you additionally need Rust stable 1.98 or newer and Xcode Command Line Tools. These are not required for the normal Desktop development command.

Route 1: Install Desktop Nightly

This is the easiest route if you want a graphical application.

1. Open the repository’s Releases page: <https://github.com/apache/maka/releases>.
2. Choose the newest prerelease named **Maka Desktop Nightly**.
3. Select the Apple-silicon/macOS artifact.

The repository says the installed app automatically updates on the Nightly channel. It does not document the exact downloaded filename, installer screens, or any Gatekeeper-bypass procedure. Therefore, this guide does not provide terminal commands for those steps. Do not use unofficial quarantine-removal or signature-bypass commands.

After launching Maka for the first time:

1. Open **Settings → Models**.
2. Add an API, local-model, or supported-account connection.
3. Test the connection.
4. Choose a default model.
5. Return to the workspace and start a task.

Maka does not include a shared model account, so a usable model connection is required for agent turns.

Route 2: Install the published CLI beta

Open **Terminal** on your Mac. Install the beta explicitly from the documented `next` distribution tag:

npm install --global maka-agent@next
maka --version
maka --help

The command is `maka`; the unrelated npm package named only `maka` is not this project.

To launch Maka, first move into the project folder where you want the agent to work. The repository gives this form:

cd path/to/project
maka

Replace `path/to/project` with your actual project path before running it. If no model is configured, the terminal interface opens provider setup. Select a provider, enter its API key, choose enabled models, and save. Later, `/setup` adds or updates a provider, while `/model` switches models.

For a single non-interactive task, use:

maka run "Summarize this project and identify its highest-risk area"
maka run --help

Maka asks before privileged tool operations by default. The documentation also describes a `--yolo` mode, but it grants full file and network access. It is unnecessary for initial installation and is intentionally not recommended here.

Update the beta

Keep the prerelease channel explicit:

maka update --target next
maka --version

Do not use a bare `npm update --global maka-agent`; the project warns that it follows `latest` and could select another release line.

Check installed versions when troubleshooting

node --version
npm --version
maka --version

If `maka` is not found after installation, the project says to ensure npm’s global executable directory is on your `PATH`. No source-supported command for changing `PATH` was supplied, so consult npm’s first-party instructions for your installation method.

Route 3: Run Desktop from a source checkout

Use this route if you want the current source development environment rather than the packaged Nightly.

In Terminal, run the documented sequence:

git clone https://github.com/apache/maka.git
cd maka
npm ci
npm run dev

`npm ci` installs the exact dependency tree represented by the repository lockfile. The root post-install process applies repository-maintained dependency patches. `npm run dev` starts the Electron Desktop development environment with hot-module replacement.

If you want every workspace built before Electron starts, stop the current process and run:

npm run dev:full

If dependencies were installed with `ELECTRON_SKIP_BINARY_DOWNLOAD=1`, install the Electron platform binary with the repository-documented command before starting Desktop:

node node_modules/electron/install.js

For ordinary development, use the plain launch. Only if you are developing Accessibility or Screen Recording behavior should you use the opt-in signed development-app path:

MAKA_DEV_TCC=1 npm run dev

In that workflow, macOS permissions should be granted to **Maka Dev**, not to a generic Electron entry. Screen Recording changes require restarting the development app. The generated development app has a separate lifecycle: pressing Control-C stops the launcher and development server but does not quit the app opened through LaunchServices; quit that app with Command-Q.

Optional source-checkout CLI

Build the workspaces first:

npm run build

Then start the development terminal interface or display its help:

npm run cli:dev
npm run cli:dev -- --help

You can also run one documented example task:

npm run cli:dev -- run "Summarize this repository and identify its most important risk"

The source-development profile is named **Maka Dev**, while released builds use **Maka**. The supplied documentation warns that profiles are not automatically copied or synchronized.

Local data and security notes

On macOS, the released CLI and Desktop profile is stored under:

~/Library/Application Support/Maka

Development Desktop defaults to:

~/Library/Application Support/Maka Dev

Maka stores workspace state, sessions, settings, artifacts, and model credentials locally by default. The credential vault is a local plaintext file protected by your operating-system account permissions; it is **not** the macOS Keychain. Keep your macOS account and disk access secure, and do not share the profile directory.

Tools that write files or run shell commands must pass Maka’s sandbox boundary, and privileged operations require approval by default. Review permission prompts rather than approving them automatically.

Uninstall the published CLI

If you installed only the global CLI, remove it with:

npm uninstall --global maka-agent

This does not delete model connections, credentials, sessions, or artifacts. Those remain in the Maka profile. The supplied files say to back up and remove that directory separately only when you intentionally want to erase all local Maka data, but they provide no deletion command; accordingly, none is included here.

For help, report problems at <https://github.com/apache/maka/issues>. Include your operating system and architecture, the command used, the complete error with credentials removed, and the three version outputs shown above.