apache/maka instruction manual

1. What Apache Maka is, its status, and its relationship to Claude Code

Apache Maka (Incubating) is a local-first AI-agent workspace written primarily in TypeScript. It can inspect a project, call tools behind a sandbox boundary, and save model messages, tool calls, tool results, permission decisions, and termination events as an append-only, recoverable execution record. The Desktop, terminal interfaces, and evaluation system all execute Maka agents through one Runtime Host.

Maka has three user-facing surfaces:

• **Desktop:** Electron and React workspace for conversations, files, artifacts, model configuration, permissions, session branching, search, and recovery.
• **TUI/CLI:** interactive terminal use with `maka`, or one non-interactive turn with `maka run`.
• **Eval:** declarative experiments with `maka eval run <spec> --out <directory>`.

**Claude Code classification:** `standalone_application`, `external_cli_library`, and `tool_surface`; install mode: `runs_alongside`; setup effort: medium. Maka is a separate desktop/CLI agent runtime with its own model connections and model-visible tools. Its runtime package also documents public integration seams. The supplied first-party files do not document a Claude Code plugin, hook, skill, MCP server for Claude, or context injection into Claude Code. It should therefore be treated as an alternative or companion that runs alongside Claude Code, not as a native Claude Code extension.

The project is still incubating and under active development. No Apache release has been made. Desktop Nightly builds are developer/tester artifacts from `main`, not ASF releases and not intended for production. Commands and local data formats may change. Desktop targets Apple Silicon macOS; Windows is an unsigned preview, while Intel macOS and Linux Desktop are not currently supported. The CLI has a broader validated platform matrix.

2. Install and start Maka Desktop or the packaged CLI

For a source checkout, install Node.js 22.19 or newer, npm, Git, and `ripgrep`. CI uses Node.js 24, and the repository currently identifies npm 11 as its package manager. Clone and start the Desktop development environment with hot module replacement:

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

To build every workspace before Electron starts, use:

npm run dev:full

Direct Peer and Peer Mesh development additionally needs Rust stable 1.98 or newer and a platform linker: Xcode Command Line Tools on macOS or MSVC Build Tools on Windows. The documented peer-enabled launchers build the native addon first:

npm run dev:peer       # HMR
npm run dev:full:peer  # full build

If dependencies were installed with `ELECTRON_SKIP_BINARY_DOWNLOAD=1`, fetch Electron’s platform binary before launch:

node node_modules/electron/install.js

For the packaged beta CLI, install the explicit `next` release line. The similarly named npm package `maka` is unrelated:

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

A one-off invocation may use `npx --yes --package maka-agent@next maka`. Start the TUI from the directory the agent should work in:

cd path/to/project
maka

On first run, configure a model. Desktop users open **Settings → Models**, add an API, local-model, or supported account connection, test it, and choose a default. TUI users follow the provider setup flow; current first-run CLI setup supports API-key providers. Later, `/setup` changes providers and `/model` switches models. Maka supplies no shared model account.

3. Agent work, tools, sessions, permissions, Graph, and recovery

The runtime supports multiple model connections, streaming text and thinking, usage reporting, and provider-error classification. Its built-in tools are `Read`, `Write`, `Edit`, `Bash`, `Glob`, and `Grep`. Computer Use and catalog skills are optional and disabled by default. File writes, shell execution, and other operations that cross the sandbox boundary require approval; a run can be aborted. In packaged CLI use, `maka run --yolo` grants full file and network access to the task, so use it only in an environment you are willing to let the task modify.

Desktop session functions include creating, archiving, searching, renaming, retrying, regenerating, and branching a session from a turn. It also presents artifact lists and previews, workspace instructions, model settings, sandbox settings, and—when configured—local memory and web search. Experimental IM bots are documented separately.

Run one non-interactive turn with:

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

From a source checkout, build first and then use the development CLI:

npm run build
npm run cli:dev
npm run cli:dev -- run "Summarize this repository and identify its most important risk"
npm run cli:dev -- run --graph "Implement two independent slices, integrate them, then review the result"
npm run cli:dev -- --help

Graph mode coordinates durable work. The TUI accepts `/graph on`, `/graph off`, and `/graph <task>`. Non-interactive `--graph` waits for the durable Graph to finish and prints the final supervisor output. Graph implementation operators use isolated Git worktrees, so the source project must be a clean Git worktree.

Maka preserves the event record even when old tool output is omitted from a later prompt. Interrupted-turn resume is off by default. Setting `MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1` enables Desktop Safe resume, CLI `/resume`, and startup auto-resume; each can call the model and consume tokens.

4. Local data, profiles, updates, remote Runtime Host, and removal

Desktop workspace data defaults to `<Electron userData>/workspaces/default/`, containing `runtime.sqlite`, connection and settings JSON, a credential vault, and artifacts. `runtime.sqlite` is the live execution record. Older JSONL transcripts and Electron `safeStorage` credentials are not imported, so an upgraded workspace may show empty threads and require credentials to be entered again.

Credentials are stored in a local plaintext `credential-vault.json`, protected by the operating-system account boundary; POSIX installations enforce owner-only modes. It is not an OS keychain, although the renderer does not receive plaintext secrets. Released CLI and Desktop data remains in `~/Library/Application Support/Maka` on macOS, `$XDG_CONFIG_HOME/Maka` or `~/.config/Maka` on Linux, and `%APPDATA%\Maka` on Windows. Development and released profiles are separate and are not automatically synchronized.

Update the beta while keeping the prerelease channel explicit:

maka update --target next
maka --version

The updater stages and verifies the selected release and refuses to interrupt active or durable work by default. The documented `--allow-interrupt-active-tasks` override should be used only after deciding interruption is safe.

On Linux or macOS, set up a persistent remote Runtime Host from an exact package with:

npx --yes --package maka-agent@next maka runtime-host setup \
  --principal my-client \
  --preset terminal-client

Check, but do not install, a service update with `maka runtime-host service check-update --target next --json`. Update policy and one-shot reconciliation are supported; reconciliation installs no scheduler and never interrupts active work.

Remove a managed service before uninstalling the global CLI:

npx --yes --package maka-agent@next maka runtime-host service uninstall
npm uninstall --global maka-agent

Neither command deletes sessions, credentials, model connections, or artifacts. Back up and remove the applicable profile directory separately only when intentionally deleting all data, after closing CLI and Desktop.

5. Run and understand declarative evaluations

Eval expands one strict experiment specification into `task × repetition × subject` cells. A repetition is a fresh sample; infrastructure replacement appends another immutable attempt to the same cell. Result selection uses the earliest valid attempt. The compact result kernel records score, normalized usage, attributable cost, duration, status or failure reason, and artifacts.

Run an experiment through the main CLI—there is no separate Eval binary:

maka eval run experiment.json --out .maka-eval/run-001

Use `--cell <cell-id>` to replace one failed or indeterminate cell. The output directory contains frozen `experiment.json` plus append-only attempt records, not a second mutable results file. If `.writer.lock` remains after a crash, remove it only after proving no writer still owns that experiment.

A `maka.eval.v1` spec contains an ID; benchmark and executor objects; optional `execution.maxConcurrentTaskGroups`; one or more subjects; one or more tasks; a positive repetition count; and budget and verifier objects. Subjects are `maka` or `external`. Unknown top-level keys are rejected, and the parsed spec is deep-frozen. Maka subjects execute through Runtime Host; external subjects use declared commands, arguments, credential bindings, and result contracts.

The npm package includes Eval runtime, relay, wrapper, and container-policy assets, but not external executor software or benchmark data. Before trials begin, preflight checks machine paths, relay files, exact Harbor/Pier Python versions, subject toolchains, and Docker availability when required. Missing prerequisites stop the run before any cell executes.

Docker Harbor/Pier evaluations need a reachable Docker CLI and daemon, distinct Python environments at the versions named by the spec, writable trial storage, Pier task storage, and all declared machine-path and credential variables. The documentation validates Harbor 0.20.0 and datacurve-pier 0.3.0 in separate Python 3.12 virtual environments. Do not share one environment between them because their dependency and trial contracts differ.

Eval supports custom executors through `ExperimentExecutor.runAttempt` plus optional `validate`, and custom subjects through `SubjectAdapter.execute` plus optional `validate`, `prepare`, and `canReuse`. Applications replace default wiring through `runMakaEvalCli` dependencies.

6. Architecture and supported extension seams

The execution spine is Desktop/TUI/CLI → Runtime Host → `SessionManager` → `AgentRun`, with the model/tool runtime writing a Runtime Event Log that feeds context, session, and UI projections. Eval owns experiment semantics and scores; it does not construct runtime objects or execute Maka directly.

`@maka/runtime` is the pure-Node agent runtime. Its documented public seams are:

• `SessionManager` for sessions and turns.
• `BackendRegistry` and `AgentBackend` for selecting or adding model backends.
• `AiSdkBackend` as the shipped backend implementation.
• Session execution-boundary APIs for managed sandbox expansion and explicit bypass.
• `buildBuiltinTools()` and workspace-executor interfaces for tool composition.
• `RuntimeKernel`, runtime events, projections, and recovery helpers for lifecycle handling.

`FakeBackend` is test-only and omitted from release packaging. Add backend behavior behind `AgentBackend`; add tools through composition seams and keep filesystem/shell effects behind `WorkspaceExecutor`. Shared pure contracts belong in `packages/core`, interactive state in `packages/storage`, and credentials/Electron IPC outside runtime. Only root-barrel and declared package subpath exports are supported APIs.

Desktop has three layers: Electron main owns windows, OS services, client settings, IPC projection, and the Runtime Host connection; preload exposes the sole `window.maka` bridge; React renderer supplies the UI and must not directly use Node APIs. IPC uses request/response, safe main-to-renderer push with unsubscribe functions, or renderer-to-main fire-and-forget. New IPC must register a focused handler, expose it in preload, type it in `global.d.ts`, and follow `<domain>:<action>` naming.

`@maka/ui` re-exports generic Astryx components and supplies Maka-specific primitives, product compositions, feature components, and pure helpers. Consumers may import the barrel or documented subpaths. New code should use Astryx for generic controls, keep irreducible product controls small, and promote symbols to the package barrel only for a cross-package consumer or explicit public API need.

7. Development, verification, model metadata, macOS permissions, and performance probes

The documented repository checks are:

npm run build
npm run typecheck
npm test
npm run check:release

Focused workspace tests include:

npm --workspace @maka/runtime run test:dist
npm --workspace @maka/eval run test:dist
npm --workspace @maka/desktop run test:dist

Desktop real-window checks are `npm --workspace @maka/desktop run e2e` and `npm --workspace @maka/desktop run smoke:real-window`. Before submitting a change, run typecheck, build, focused tests proportionate to the change, and `git diff --check`.

Refresh the committed models.dev catalog and regenerate derived TypeScript with:

npm run refresh:model-metadata
npm --workspace @maka/core run test:dist

Refresh fails closed if a committed model, capability, provider override, or pricing field disappears. After reviewing an intentional upstream removal, the documented acknowledgement is `npm run refresh:model-metadata -- --accept-upstream-removals`. `sync:model-metadata` only regenerates from the committed snapshot and stays offline. Keep access-path overrides in `model-metadata.ts`; do not edit generated files manually.

On macOS, Accessibility or Screen Recording development needs the generated ad-hoc-signed Maka Dev app because TCC does not retain grants for plain unsigned Electron launched from a terminal:

MAKA_DEV_TCC=1 npm run dev

Quit that detached app with Cmd-Q; Ctrl-C stops the launcher and Vite server, not the app. Grant permissions to **Maka Dev**. The generated identity is worktree-specific, and rebuilding after an Electron change or repository move requires granting permission again.

Renderer performance scripts are ad-hoc probes, not benchmarks. Start one debugger-enabled app, populate roughly 30 sidebar rows, and run:

npm run dev -w @maka/desktop -- --remote-debugging-port=9334
node scripts/perf/session-switch-commits.mjs before
node scripts/perf/session-switch-busy-js.mjs

Never compare separate app launches. Perform alternating A/B repetitions inside one instance and read both commit counts and median busy-JS results.

8. Security boundaries, known limitations, troubleshooting, and documentation authority

Local-first means sessions, settings, and records stay local by default, not that every operation is offline. Cloud models, configured web search, remote hosts, or Eval providers can transmit data. Review model/provider policies before using sensitive material. Tools are sandbox-controlled, but approval or `--yolo` can expand impact. The credential vault is plaintext under the user-account boundary.

Maka carries dependency patches for documented upstream blockers: Electron-compatible Sigstore/TUF signature verification, safer Unix `node-pty` write lifecycles, gateway tool-call association, and several Astryx UI state/accessibility seams. These patches are applied during root postinstall and show that packaged behavior currently depends on local fixes. The source also warns that Desktop, commands, formats, experimental IM, Computer Use, and catalog skills are evolving.

Eval’s egress policy blocks known benchmark and public-solution contamination surfaces, not every deliberately invented lookup path. Shell networking remains enabled within the documented proxy policy. Multi-arm results require care: if one arm loses its cell, the surviving observation remains, so comparisons should re-pair by task and discard unmatched observations rather than average all survivors.

For basic diagnosis, record versions first:

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

If `maka` is missing, add npm’s global executable directory to `PATH`. If no model is available, start the TUI and run `/setup`. Eval reports the missing environment variable, framework version, machine path, or Docker failure and does not silently install substitutes. Remove credentials from complete error output before filing an issue at `https://github.com/apache/maka/issues`.

Treat current code and contract tests as final authority. Root/package READMEs describe stable entry points; active `docs/` files describe cross-cutting contracts; issues and pull requests hold time-sensitive plans. `docs/archive/` is historical context only and must not be treated as current implementation guidance. Start further reading with `ARCHITECTURE.md`, `DESIGN.md`, `CONTRIBUTING.md`, `SECURITY.md`, and `docs/README.md`. The repository uses Apache License 2.0; third-party components keep their own licenses and notices.