Maka has been sprinting intensively over the past two days, and the most noteworthy feature is out: Autonomous Task Loop v1 is now live.

Previously, Maka would end after running an agent once. Now it’s a persistent loop:
preflight → runtime → SelfCheck → FeedbackObservation → Decision
After each round, the agent performs a self-check, then decides to continue / submit / abort. If continuing, the feedback from the previous round is carried into the next round as instructions. The entire process is written to the ledger, allowing recovery on restart.

An important design decision: SelfCheck is observation, not authority. When the agent says “I’m done,” that doesn’t count — there must be an independent verifier to judge, preventing the agent from rubber-stamping itself.

Budget is a first-class citizen: maximum attempt count, wall‑clock time, token/cost, and tool calls all have guards.

Also merged in are Full Local Memory and History Compact persistence — long sessions are compressed so state is not lost on restart after compression.

Together, these three give Maka a real foundation for running tasks. Next up is subagent (parent agent spawning child agents).

jackwener/maka-agent

Source: https://github.com/jackwener/maka-agent

Maka

Maka is a local‑first desktop AI workbench. It brings model connections, sessions, tool permissions, file I/O, terminal execution, search, bot entry points, and run recovery into a single Electron app — with the goal of letting users run an observable, controllable, and recoverable agent on their own computer.

This repo is under active development. This README serves two groups:

• First‑time users of Maka: understand why you need to configure AI first, where data is stored, and which capabilities are already available.
• Engineers continuing development on Maka: quickly start, verify, and locate key packages and design documents.

What You’ll See

When you first open Maka, if no model connection is available, the welcome screen will guide you through AI configuration instead of showing an empty chat box that can’t send messages. The recommended path is:

1. Open Settings → Models.
2. Select a real model provider, fill in the API key, or complete account login for connected providers.
3. Test the connection and select a default model.
4. Return to the welcome screen and start your first conversation using Quick Input.

Supported model types:

• Overseas APIs: Anthropic, OpenAI, Google Gemini.
• Domestic APIs: DeepSeek, Moonshot, Z.AI Coding Plan, Kimi Coding Plan.
• Local models: Ollama.
• Custom gateways: OpenAI Compatible endpoint.
• Subscription entry points: Claude Subscription, Codex Subscription, Gemini CLI, etc., are listed separately as experimental/available — entries that are not yet connected to the send pipeline will not be disguised as usable.

Current Capabilities

Maka is not a simple chat demo. It already has these core aspects:

• Desktop sessions: create, switch, archive, search, rename, stop, retry, regenerate, branch from a turn.
• Model runtime: built on the Vercel AI SDK provider runtime, supporting model streaming, tool calls, usage logging, error classification, and startup recovery.
• Local tools: Read, Write, Edit, Bash, Glob, Grep — file writes and command execution go through a permission policy.
• First‑run guidance: shows different states based on real connection status: “configure missing connection / select default connection / select default model / start conversation”.
• Settings hub: models, accounts, usage statistics, daily recap, local memory, voice models, open gateway, bot conversations, web search, network proxy, permissions & capabilities, health status, data & about.
• Local memory: MEMORY.md management, manual addition, archive/restore, agent read toggle.
• Web search: Tavily credential configuration, testing, and agent‑tool boundaries.
• Bot entry points: Telegram, Feishu, WeCom, WeChat iLink, Discord, DingTalk, QQ — configuration/test/run‑state framework.
• Open gateway: local HTTP/SSE API, token‑protected external access to session state, events, capabilities, and health summary.
• Office document workflow: enabled after local officecli detection for reading, validation, and per‑use authorization for editing.
• Runtime kernel: AgentRun ledger, RuntimeEvent read model, ToolRuntime, ModelAdapter, RunTrace, and recovery logic.

Local & Privacy Boundaries

By default, Maka stores work data in a workspace directory under Electron’s userData:

/workspaces/default/
  llm-connections.json
  credentials.json
  settings.json
  sessions/

Important boundaries:

• Provider connection metadata and session JSONL are on the local filesystem.
• Sensitive values like API keys, OAuth tokens, bot tokens, proxy passwords, gateway tokens, Tavily keys, etc., are encrypted with Electron’s safeStorage before being written to credentials.json.
• The renderer does not have access to plaintext secrets; Settings only shows masked status and test results.
• File I/O, shell operations, and dangerous actions must pass through the permission engine.
• Capabilities like incognito/privacy context, memory, voice, and workspace instructions have separate contract documents specifying their constraints.

Quick Start

The repo uses npm workspaces. Although a pnpm-workspace.yaml exists, the current scripts and lockfile are based on npm.

npm install
npm run dev

npm run dev will first build all workspaces, then launch the Electron desktop app.

If you set ELECTRON_SKIP_BINARY_DOWNLOAD=1 during dependency installation, you need to download the Electron platform binary before launching:

node node_modules/electron/install.js

Common development commands:

npm run build
npm run typecheck
npm --workspace @maka/desktop run test
npm --workspace @maka/runtime run test
npm --workspace @maka/core run test

Desktop visuals and real‑window verification:

npm --workspace @maka/desktop run screenshots
npm --workspace @maka/desktop run screenshots:diff:stable
npm --workspace @maka/desktop run smoke:real-window

Pre‑release basic checks:

npm run check:release

Optional Environment Variables

These variables only affect local development or specific capabilities:

Project Structure

apps/desktop/
  src/main/          Electron main process, IPC, settings, OAuth, bot, gateway
  src/preload/       window.maka preload bridge
  src/renderer/      React desktop UI and Settings surfaces
packages/core/       Pure contracts: sessions, events, settings, permissions, model connections
packages/storage/    File‑backed session, settings, connection, run‑ledger stores
packages/runtime/    SessionManager, AgentRun, AI SDK runtime, tools, bots, telemetry
packages/ui/         Shared rendering components, markdown, artifacts, redaction helpers
docs/                Product, runtime, design‑system, privacy and test‑plan contracts
scripts/             Build hygiene, screenshot, smoke and release helpers

Runtime Architecture

The current runtime has been refactored from a single large flow into clearer kernel boundaries:

SessionManager -> AgentRun -> AiSdkBackend -> ModelAdapter -> ToolRuntime -> RunTrace -> AgentRunStore

Key principles:

• SessionManager remains the public runtime API exposed to desktop, bots, and gateways.
• AgentRun is responsible for durable run facts and startup recovery for a single turn.
• ToolRuntime handles tool input validation, permissions, watchdog, abort, telemetry, artifact candidates, and error classification.
• ModelAdapter isolates provider stream / error / usage normalization.
• RunTrace is best‑effort – a trace write failure must never affect the user conversation.

More details in:

• docs/runtime-kernel.md
• docs/runtime-v2-architecture-evolution.md
• docs/runtime-v2-implementation-notes.md

UI & Product Quality Contracts

Maka’s UI is not assembled ad‑hoc; there are separate design systems and test plans:

• docs/design-system.md: color, density, states, motion, Settings IA, copy, and a11y contracts.
• docs/ui-quality-plan.md: real‑window, visual screenshots, interaction states, regression verification strategy.
• docs/full-product-test-plan.md: full QA route from first run, settings, sessions, tools, search, bots, gateway to failure paths.

When changing UI, don’t just run TypeScript. At minimum, also run:

1. node:test contracts for the corresponding surface.
2. check-console / check-a11y passes.
3. If necessary, add visual fixtures or real‑window smoke tests.

Pre‑contribution Checklist

For routine code changes, it is recommended to at least run:

npm run typecheck --workspaces --if-present
npm run build
git diff --check

For changes involving desktop renderer / Settings / IPC, also run the relevant focused suites, e.g.:

npm --workspace @maka/desktop run test -- settings-form-a11y-contract visible-copy-hygiene-contract

For changes involving runtime / storage, also run the relevant workspace tests:

npm --workspace @maka/runtime run test
npm --workspace @maka/storage run test

Related Documents

• CHANGELOG.md: summary of unreleased changes.
• SECURITY.md: security boundaries and reporting methods.
• docs/workspace-privacy-context.md: workspace privacy context.
• docs/search-service-threat-model.md: search service threat model.
• docs/memory-threat-model.md: local memory threat model.
• docs/voice-threat-model.md: voice capability boundaries.
• docs/maka-capability-audit-v1.md: capability maturity audit and roadmap.