What Is Apache Maka? A Local-First, Agent-Driven Workspace Explained

Apache Maka (Incubating) is a local-first, agent-driven workspace that lets users run AI-augmented tools on their own machine through a unified Runtime Host that coordinates Desktop UI, terminal, and bot clients.

Apache Maka is an Apache Incubator project designed as a privacy-preserving platform for AI-assisted software development. Unlike cloud-dependent alternatives, Maka keeps all execution, data, and model interactions on the user's machine through a centralized Runtime Host architecture. This design ensures that every tool invocation, model call, and session transition operates under a single, auditable execution authority as documented in the project's ARCHITECTURE.md.

Core Architecture of Apache Maka

The Runtime Host and Execution Authority

The Runtime Host serves as the central nervous system of Apache Maka. According to the source code in packages/runtime/, it functions as the sole execution authority that owns session identity, tool lifecycles, permissions, and event logging. All clients—including the Electron Desktop UI, terminal-based TUI/CLI, bots, and evaluation clients—must request work from this host rather than executing independently. This design prevents fragmentation of state or permission grants across different entry points.

SessionManager and AgentRun Lifecycle

Session and turn management happens through the SessionManager and AgentRun classes located in packages/runtime/. The SessionManager handles the lifecycle of a session (a persistent workspace), while AgentRun coordinates a turn (a single model interaction). The AgentRun component manages model adapters and invokes the Tool Runtime during execution. This separation allows precise control over admission policies, tool provisioning, and state transitions for each interaction.

Tool Runtime and Built-in Capabilities

Maka provides a built-in Tool Runtime with essential file system and shell operations: Read, Write, Bash, Glob, and Grep. These tools are available by default to agents operating within the workspace. Optional "computer-use" and catalog skills are plug-in-able but disabled by default, allowing users to strictly control the agent's capabilities. All tool executions are logged to the Runtime Event Log for auditability.

Runtime Event Log and Recovery

Durability is guaranteed by the Runtime Event Log, a SQLite-backed immutable record stored in runtime.sqlite within the Electron userData directory. As implemented in packages/storage/, this log captures every model message, tool call, tool result, and termination fact. It serves as the canonical source for crash recovery and context pruning, ensuring that interrupted sessions can resume from their exact prior state.

Agent Graph for Multi-Agent Pipelines

For complex workflows, the Agent Graph scheduling layer creates child sessions for dependent work. This enables multi-agent pipelines—where one agent's output becomes another's input—while maintaining the architectural invariant that all activity routes through the Runtime Host. Graph mode can be enabled via CLI flags for reproducible experiment tracking and workflow visualization.

Repository Structure and Source Organization

The Apache Maka codebase is organized as a monorepo that reflects its architectural layers:

• apps/desktop/ — Electron main process, preload scripts, and React-based Desktop UI
• packages/core/ — Pure TypeScript contracts for sessions, events, and permissions used by all other packages
• packages/runtime/ — Implementation of the Runtime Host, SessionManager, AgentRun, recovery logic, and tool execution
• packages/storage/ — SQLite stores and configuration handling, including connection-catalog.json management
• packages/eval/ — The @maka/eval subsystem for benchmark experiments and result aggregation
• packages/cli/ — Terminal UI (TUI) implementation and non-interactive CLI commands
• packages/ui/ — Shared React primitives for conversation views, markdown rendering, and artifact display

Getting Started with Apache Maka

Setting Up the Development Environment

To build and run the Desktop UI from source, clone the repository and install dependencies:

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

For a full build before launching Electron, use npm run dev:full instead.

Running Interactive and Non-Interactive Sessions

Execute a single, non-interactive turn via the CLI entry point documented in packages/cli/:

# Build the workspace first

npm run build

# Run a single turn

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

Enabling Graph Mode for Reproducible Experiments

To record agent graph execution for complex, multi-step tasks:

# Enable graph recording

npm run cli:dev -- run --graph "Implement two independent slices, integrate them, then review"

# Disable graph mode

npm run cli:dev -- run /graph off

Evaluation and Testing

The Eval Subsystem (@maka/eval)

Located in packages/eval/, the evaluation subsystem is architecturally separate from the core runtime. It defines experiments composed of cells (task × repetition × subject) and owns benchmark semantics. Crucially, it delegates all execution to the Runtime Host, ensuring that evaluation runs use the same tool runtime and permissions as production sessions.

End-to-End Testing

Run the desktop UI's smoke tests using the workspace commands defined in apps/desktop/:

npm --workspace @maka/desktop run e2e
npm --workspace @maka/desktop run smoke:real-window

Storage and Configuration

Apache Maka persists state through a Storage Layer utilizing SQLite. Key files include runtime.sqlite (the event log) and connection-catalog.json (configuration metadata), both stored under the Electron userData directory. The packages/storage/ module abstracts all database operations, ensuring that the Runtime Host and Agent Graph layers remain agnostic to persistence details.

Summary

• Apache Maka provides a local-first, agent-driven workspace that keeps AI execution entirely on the user's machine
• The Runtime Host in packages/runtime/ serves as the sole execution authority, coordinating all Desktop, CLI, and bot clients
• SessionManager and AgentRun manage the lifecycle of workspaces and individual model turns, routing all tool calls through the Runtime
• The Runtime Event Log provides durable, SQLite-backed state in runtime.sqlite for crash recovery and audit trails
• Agent Graph enables sophisticated multi-agent workflows while maintaining centralized control through the Runtime Host
• The @maka/eval package supports reproducible benchmarking without bypassing the core runtime security model

Frequently Asked Questions

Is Apache Maka a cloud-based AI service?

No. Apache Maka is explicitly designed as a local-first workspace. All model inference, tool execution, and data storage occur on the user's local machine. The Runtime Host architecture ensures that sensitive code and data never leave the local environment unless explicitly configured to do so.

What programming languages and tools does Apache Maka support?

The built-in Tool Runtime provides universal file system and shell access through Read, Write, Bash, Glob, and Grep tools. This allows the agent to interact with any codebase regardless of language. The Maka platform itself is implemented in TypeScript (Node.js/Electron) with SQLite for persistence, as seen in packages/runtime/ and packages/storage/.

How does Apache Maka handle session recovery after crashes?

The platform uses the Runtime Event Log, an immutable SQLite-backed log stored in runtime.sqlite. According to the source documentation, this log records every model message, tool call, and termination fact, serving as the canonical source for crash recovery and context pruning. If the application terminates unexpectedly, the next session initialization reads this log to restore the exact prior state.

Can Apache Maka run automated evaluations or benchmarks?

Yes. The @maka/eval package in packages/eval/ provides a complete experiment framework that defines tasks, repetitions, and subjects. It separates benchmark semantics from execution infrastructure, routing all evaluation work through the Runtime Host to ensure that measurements reflect real-world tool runtime performance and permissions.

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