I increasingly feel that Maka is a great tool for learning about Agents. For example, a Maka core dev recently opened an issue discussing DeepSeek’s cache optimization. The entire process was transparent: 1 issue + 8 PRs pushed through, from usage normalization → request prefix stabilization → archive history compression https://github.com/jackwener/maka-agent/issues/19… It may sound like just saving token fees, but once you actually do it, you encounter a bunch of real and core Agent runtime problems: how to stabilize the prompt prefix, how to canonicalize tool schemas, how to budget historical context, how to calculate usage/cost correctly, and how to explain cache misses. There was a counterintuitive discovery: trimming history ≠ saving money. Tests showed that removing old turns actually increased cache misses and made total cost higher. We reverted the sliding window trim to opt-in. These are engineering problems you’ll definitely hit when turning an Agent into a product — it’s not just about writing an Agent loop.

jackwener/maka-agent

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

Maka

Maka is a local-first desktop AI workbench. It integrates model connections, conversations, tool permissions, file read/write, terminal execution, search, bot entry points, and run recovery into a single Electron application. The goal is to let users run an observable, controllable, and recoverable agent on their own machine.

This repository is under active development. This README is intended for two types of people:

• Users opening Maka for the first time: understand why AI configuration comes first, where data is stored, and which capabilities are already available.
• Engineers continuing to develop Maka: quickly start, verify, locate key packages and design documents.

What you’ll see

When you first enter Maka without a usable model connection, the initial 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 log in to a connected account.
3. Test the connection and select a default model.
4. Return to the home screen and start the first conversation with quick input.

Connected model types include:

• Overseas APIs: Anthropic, OpenAI, Google Gemini.
• Domestic APIs: DeepSeek, Moonshot, Z.AI Coding Plan, Kimi Coding Plan.
• Local models: Ollama.
• Custom gateway: OpenAI Compatible endpoint.
• Account subscription entries: Claude Subscription, Codex Subscription, Gemini CLI, etc., are displayed separately based on experimental/available status. Entries not yet integrated into the send pipeline do not pretend to be 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: Provider runtime based on Vercel AI SDK, supporting model streaming, tool calls, usage recording, error classification, and startup recovery.
• Local tools: Read, Write, Edit, Bash, Glob, Grep. File writing and command execution follow permission policies.
• First-run guide: Shows different states based on actual connection status (“configure / select default connection / select default model / start conversation”).
• Settings center: Models, accounts, usage statistics, daily review, 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 boundary.
• Bot entry points: Configuration/testing/running status framework for Telegram, Feishu, WeCom, WeChat iLink, Discord, DingTalk, QQ.
• Open gateway: Local HTTP/SSE API, protected by token, allowing external reading of session state, events, capabilities, and health summary.
• Office document workflow: Detects and enables reading, validation, and per-use authorized editing via local officecli.
• Runtime kernel: AgentRun ledger, RuntimeEvent read model, ToolRuntime, ModelAdapter, RunTrace, and recovery logic.

Local and privacy boundaries

By default, Maka stores working 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, and Tavily keys are encrypted via Electron safeStorage before being written to credentials.json.
• The renderer does not directly access plaintext keys; Settings only shows masked status and test results.
• File read/write, shell operations, and dangerous actions require permission engine approval.
• Capabilities like Incognito/privacy context, memory, voice, and workspace instructions have separate contract documents.

Quick start

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

npm install
npm run dev

npm run dev first builds all workspaces, then launches the Electron desktop app.

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

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 visual 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

Basic pre-release 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
  storage/            File-backed session, settings, connection, run-ledger stores
  runtime/            SessionManager, AgentRun, AI SDK runtime, tools, bots, telemetry
  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 the desktop, bots, and gateway.
• AgentRun handles the 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; trace write failures must not affect user conversations.

More details:

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

UI and product quality contracts

Maka’s UI is not thrown together; it has its own design system and test plan:

• docs/design-system.md: Color, density, states, animations, 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: Complete QA route from first-run, settings, sessions, tools, search, bots, gateway, to failure paths.

When modifying UI, do not just run TypeScript. At a minimum, accompany with:

1. A node:test contract for the corresponding surface.
2. Passing check-console / check-a11y.
3. Visual fixtures or real window smoke tests when necessary.

Pre-contribution checks

For routine code changes, 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 corresponding focused suite, e.g.:

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

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

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

Related documentation

• 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 future roadmap.