OpenCLI’s app was completely rebuilt using a component library today—took a long time. For MakeAgent, I also plan to have the Agent completely rebuild the UI; this UI might be the last one. https://t.co/kuSGF0SZDh https://t.co/eUg2zUqwYg

jackwener/maka-agent

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

Maka

Maka is a local‑first desktop AI workbench. It brings together model connections, conversations, tool permissions, file read/write, terminal execution, search, bot channels, and run recovery inside 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 meant for two audiences:

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

What you’ll see

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

1. Open Settings → Model.
2. Select a real model provider, enter an API key, or complete login for an integrated service.
3. Test the connection and choose a default model.
4. Return to the main screen and use the quick input to start your first conversation.

Currently integrated model types include:

• International 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 subscriptions: Claude Subscription, Codex Subscription, Gemini CLI etc. are displayed separately based on their experimental/available status; entries that are not yet connected to the send pipeline will not pretend to be usable.

Current capabilities

Maka is not just a simple chat demo—it already includes these core aspects:

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

Local & privacy boundaries

Maka stores working data by default 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 files are on the local filesystem.
• Sensitive values such as API keys, OAuth tokens, bot tokens, proxy passwords, gateway tokens, and Tavily keys are encrypted using Electron’s safeStorage and written to credentials.json.
• The renderer never accesses plaintext keys; Settings only display masked status and test results.
• File reads, writes, shell commands, and dangerous operations must pass through the permission engine.
• Incognito / privacy context, memory, voice, workspace instructions, and other capabilities are governed by separate contract documents.

Quick start

The repository uses npm workspaces. Although a 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 starts the Electron desktop app.

If you set ELECTRON_SKIP_BINARY_DOWNLOAD=1 during dependency installation, you need to install 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 visual and real‑window validation:

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

Basic 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
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 runtime has been split from a monolithic pipeline into clearer kernel boundaries:

SessionManager → AgentRun → AiSdkBackend → ModelAdapter → ToolRuntime → RunTrace → AgentRunStore

Key principles:

• SessionManager remains the public runtime API exposed to the desktop, bot, and gateway.
• AgentRun manages the durable run state of a single turn and recovery on startup.
• 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 should never affect the user conversation.

For more details see:

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

UI & product quality contract

Maka’s UI is not a random collection of pages—it already has a dedicated design system and test plan:

• docs/design-system.md: color, density, states, animation, Settings IA, copy, and a11y contract.
• docs/ui-quality-plan.md: real‑window, visual screenshots, interaction states, regression verification strategy.
• docs/full-product-test-plan.md: complete QA roadmap covering first run, settings, conversations, tools, search, bot, gateway, and failure paths.

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

1. Run the corresponding surface’s node:test contract.
2. Pass check-console / check-a11y.
3. Add visual fixtures or real‑window smoke tests when needed.

Pre‑contribution checks

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

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

For changes involving the desktop renderer / Settings / IPC, also run the corresponding focused suites, for example:

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 current unreleased changes.
• SECURITY.md: security boundaries and how to report issues.
• 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.