maka README

The project's README from github.com/apache/maka. As one markdown file: README.md.

Maka Apache Maka (Incubating)

Apache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.

Website · Documentation · Download · 中文文档

GitHub stars License: Apache 2.0 Platforms: macOS, Windows preview, Linux preview

One turn of RuntimeEvents: the model speaks, runs a command, asks permission, you approve, it gets the result, edits a file, the turn ends.

What Maka is

An agent harness exists to finish tasks. We hold it to one measure: how many it completes and at what cost. We publish every run: same model, same official verifier, full per-task record.

The website walks through one turn of the log and links the published runs. ARCHITECTURE.md has the system map.

Get Maka

Apache Releases: Maka has not made an Apache release yet. When one exists, the signed source archive will be the official release; packages distributed elsewhere are convenience artifacts. See the downloads page and .github/ASF_SOURCE_RELEASE.md for candidate criteria, signing procedures, and verification steps.

Desktop Nightly: Built daily from main for developers and testers, for macOS on Apple Silicon and Intel, Windows x64 and Linux x64 and arm64; the Windows and Linux builds are unsigned previews. It is not an ASF release and is not intended for production use. The downloads page has the installers and the platform status.

Build from source: To compile and run Desktop, the TUI, or the CLI directly from a source checkout, see the Build from source section below.

Build from source

Requirements

Start Desktop

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

npm run dev starts the Desktop development environment with HMR. To build every workspace before starting Electron, use:

npm run dev:full

Direct Peer and Peer Mesh development additionally requires Rust stable 1.98 or newer and the platform linker (Xcode Command Line Tools on macOS, MSVC Build Tools on Windows). Use the peer-enabled entry point so the native addon is built before Desktop starts:

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

If dependencies were installed with ELECTRON_SKIP_BINARY_DOWNLOAD=1, install the Electron platform binary before starting:

node node_modules/electron/install.js

First run

Maka does not bundle a shared model account. On first launch:

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

The app distinguishes configured, send-ready, and experimental connection states. An account flow that is not wired into Runtime is not presented as a usable model.

Terminal entry points

For the public npm package, see the CLI installation and usage guide. The commands below run the development CLI from a source checkout.

Build the workspaces first:

npm run build

Then start the TUI or run one Turn:

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

The TUI also accepts /graph on, /graph off, and /graph <task>. Non-interactive --graph runs wait for the durable Graph to finish before printing the final supervisor output. Graph implementation operators use isolated Git worktrees, so the source project must be a clean Git worktree.

The repository CLI uses the same Maka Dev profile as a development Desktop build. The released maka binary continues to use the Maka profile; the two profiles are not copied or synchronized automatically. Evaluation specs and adapters live in packages/eval.

Architecture

The backend spine is:

Desktop / TUI / CLI → Runtime Host → SessionManager → AgentRun
                                             ↓
                         Model + Tool Runtime → Runtime Event Log
                                             ↓
                              Context / Session / UI projections

Experiment → Cells → Attempts → Results
                    ↓
       Runtime Host executes Maka subjects

Start with ARCHITECTURE.md. It provides the system map, code boundaries, problem-oriented reading paths, and links to the deep dives under docs/architecture/.

Repository layout

apps/desktop/          Electron main / preload / React renderer

packages/core/         Pure contracts for Sessions, Events, Permissions, and Connections
packages/storage/      SQLite operational state, configuration, and payload stores
packages/mcp/          Provider-neutral Model Context Protocol client integration
packages/runtime/      AgentRun, model adapters, tools, context, and recovery
packages/runtime-host/ Single-owner Runtime Host lifecycle, protocol, and client bootstrap
packages/eval/         Experiment cells, attempts, results, and executor/subject adapters
packages/computer-use/ Computer-use backend selection, host lifecycle, and protocol adapters
packages/cli/          TUI and non-interactive CLI
packages/ui/           Shared conversation, Markdown, Artifact, and UI primitives
native/                Rust: the direct-peer addon for Runtime Host and the gitoxide helper
website/               Astro source for maka.apache.org

docs/                  Architecture, product, security, privacy, and test contracts
scripts/               Build hygiene, visual checks, smoke tests, and release helpers
skills/                Agent skills shipped with the repository
patches/               Patches applied to npm dependencies at install
experiments/           Platform experiments, currently the Windows sandbox smoke scripts

Local data and recovery

Workspace data lives under Electron userData by default:

<Electron userData>/workspaces/default/
  runtime.sqlite
  connection-catalog.json
  credential-vault.json
  settings.json
  artifacts/

Details: SECURITY.md, privacy, resume.

Development and verification

Before sending a change, read CONTRIBUTING.md.

Common repository-level commands:

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

Run one workspace in isolation:

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

Use refresh:model-metadata to fetch the current catalog from models.dev, update the committed snapshot, and regenerate the derived TypeScript files. A refresh fails closed when any committed model, capability, provider override, or pricing field disappears; after reviewing an intentional upstream removal, acknowledge it with npm run refresh:model-metadata -- --accept-upstream-removals. sync:model-metadata is intentionally offline: it only regenerates those files from the committed snapshot. Keep access-path-specific overrides in model-metadata.ts; do not edit the generated files by hand.

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

Desktop real-window and visual verification:

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

Before submitting code, run typecheck, build, and focused tests proportionate to the change, followed by git diff --check.

Documentation

License

Maka is licensed under the Apache License 2.0. See NOTICE for attribution information. Third-party components remain subject to their respective licenses and notices.

Apache Maka, Maka, Apache, the Apache feather, and the Apache Maka project logo are either registered trademarks or trademarks of The Apache Software Foundation.

[!NOTE] Apache Maka (Incubating) is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision-making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF. DISCLAIMER-WIP records the issues the project is currently aware of.

[!IMPORTANT] Maka is under active development. Data formats, CLI commands, and experimental capabilities may still change.

maka (apache/maka)

Searching Database…

5.8K ·GitHub
Maka
Что это такое?Apache Maka (Incubating) — высокопроизводительное рабочее пространство для агентов, которое фиксирует все свои действия в журнале событий, куда записи только добавляются. Работать с ним можно через десктопное приложение, терминальный TUI или CLI.
Это десктопное приложение, CLI или что-то другое?Есть три клиента: десктопное приложение на Electron, терминальный TUI и CLI, а также инструмент Eval. Все они — тонкие клиенты одного общего Runtime Host, который отвечает за выполнение.
Как начать пользоваться Maka?Скачайте сборку Desktop Nightly со страницы загрузок (или соберите из исходного кода командой npm run dev), затем при первом запуске откройте Settings -> Models и добавьте подключение к модели перед запуском задачи.
Есть ли уже официальный стабильный релиз?Официального релиза Apache пока нет. Доступная сборка Desktop Nightly собирается каждый день из ветки main, а сборки для Windows и Linux — это неподписанные превью, которые явно не предназначены для продакшена.
Для каких платформ доступна Desktop Nightly?macOS на Apple Silicon и Intel, Windows x64 и Linux x64/arm64. При этом сборки Nightly для Windows и Linux — это неподписанные превью.
Где хранятся мои API-ключи и данные сессий?Всё находится в локальной папке Electron userData. API-ключи лежат в локальном файле credential-vault.json в открытом виде (без шифрования) и доступны для чтения только учётной записи вашей ОС. Процесс renderer их никогда не видит.
Какую модель нужно запустить, чтобы работать с Maka?Модель не входит в комплект — вы подключаете свою: через облачный API-ключ, локальную модель или совместимый шлюз. Настройка выполняется в Settings -> Models.
Чем подход Maka отличается от других агентных обвязок?Журнал событий RuntimeEvent, куда записи только добавляются, здесь и есть настоящая среда выполнения: интерфейс, следующий запрос и восстановление после сбоя — всё это проекции этого журнала. Запуски открыто сравниваются с другими обвязками, с результатами по каждой задаче.
Можно ли возобновить прерванный ход агента?Возобновление по умолчанию отключено, поскольку оно обращается к модели и расходует токены. Установка MAKARUNTIMESAFEBOUNDARYRESUME=1 включает Desktop Safe resume, команду CLI /resume и автовозобновление при запуске.
Что делает режим /graph в TUI?Он запускает постоянный Graph из операторов реализации в изолированных Git worktree и ждёт завершения графа, прежде чем вывести итоговый результат супервизора. В качестве исходного проекта требуется чистый Git worktree.
What are similar projects?EvoTrace, holaOS, ZCode, codex-host, munder-difflin, DeepSeek-Reasonix, qwen-code, OpenAgentCore
Which topics is it in?agent-runtime, tool-use, event-sourcing, apache, agent-harness, harness, electron, agents, local-first, benchmark, desktop, ai-agent
Creator
apache
Size
179.8 MB
Stars
5.8K
Updated
CommitOct 16
Age
4mo
Commits · 90 Days