@jakevin7: DeepSeek cache hit rate 95%, feels great. Maka's performance under the latest round of long-context tasks with the Deepseek model is outstanding. Total runtime close to 18 hours, nearly 400 million tokens, cost 33 bucks. The Make builders are amazing…

DeepSeek cache hit rate 95%, feels great. Maka’s performance on the latest long-context task with the Deepseek model has been outstanding. Full run took close to 18 hours, nearly 400 million tokens, cost just $33. The Make builders are amazing. https://t.co/33yiShOGpA https://t.co/KWEPxviz9t — # maka-agent/maka-agent Source: https://github.com/maka-agent/maka-agent # Maka Maka is a local-first desktop AI workbench. It brings model connections, conversations, tool permissions, file reading/writing, terminal execution, search, bot entry points, and run recovery into a single Electron app. The goal is to let you run an observable, controllable, and resumable agent on your own computer. This repo is under active development. This README serves two audiences: - Users opening Maka for the first time: understand why you need to configure AI first, where data lives, and what capabilities are already available. - Engineers continuing Maka development: quickly start, verify, locate key packages, and design documents. ## What you’ll see On first launch, if no model connection is available, the home screen guides you through AI configuration instead of showing an empty, unusable chat box. The recommended path is: 1. Open Settings -> Models. 2. Pick a real model provider, enter your API key or log in with an integrated account. 3. Test the connection and select a default model. 4. Go back to the home screen and start your first conversation using the quick input. Supported 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. - Subscription entry points: Claude Subscription, Codex Subscription, Gemini CLI, etc., are shown separately as experimental/available; entries not connected to the send pipeline are not disguised as usable. ## Current capabilities Maka is not a simple chat demo. It already has these core features: - Desktop sessions: create, switch, archive, search, rename, stop, retry, regenerate, branch from a turn. - Model runtime: based on Vercel AI SDK’s provider runtime, supports streaming, tool calls, usage tracking, error classification, and startup recovery. - Local tools: Read, Write, Edit, Bash, Glob, Grep — file writes and command execution go through permission policies. - First-run guide: shows different states (configure / select default connection / select default model / start conversation) based on actual connection status. - Settings center: models, accounts, usage stats, 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 add, archive/restore, agent read toggle. - Web search: Tavily credentials configuration, testing, and agent tool boundary. - Bot entry points: Telegram, Feishu, WeCom, WeChat iLink, Discord, DingTalk, QQ — configuration/testing/running state framework. - Open gateway: local HTTP/SSE API, protected by tokens, for external reading of 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 and privacy boundaries By default, Maka stores working data in a workspace directory under Electron’s userData: text /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 are encrypted via Electron’s safeStorage and written to credentials.json. - The renderer never receives plaintext secrets; Settings only show masked status and test results. - File reads/writes, shell, and dangerous operations go through the permission engine. - Incognito/privacy context, memory, voice, workspace instructions, etc., have separate contract documents. ## Quick start The repo uses npm workspaces. Although pnpm-workspace.yaml exists, current scripts and lockfile use npm. sh 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 download the Electron platform binary before starting: sh node node_modules/electron/install.js Common development commands: sh 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: sh 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: sh npm run check:release ## Optional environment variables These only affect local development or specific features: | Variable | Purpose | | — | — | | ANTHROPIC_API_KEY | Can bootstrap an Anthropic connection on first launch. | | OPENAI_API_KEY | Can bootstrap an OpenAI connection on first launch. | | TAVILY_API_KEY / MAKA_TAVILY_API_KEY | Source of Tavily credentials for web search. | | MAKA_RIVE_BIN / RIVE_BIN | Specify the rive CLI used by Rive workflows. | | MAKA_VISUAL_SMOKE_FIXTURE | Enable deterministic visual fixture, dev/test builds only. | ## Project structure text 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 refactored from a single large flow into clearer kernel boundaries: text SessionManager -> AgentRun -> AiSdkBackend -> ModelAdapter -> ToolRuntime -> RunTrace -> AgentRunStore Key principles: - SessionManager remains the public runtime API exposed to desktop, bots, and gateway. - AgentRun is responsible for the durable run facts and startup recovery of 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 in: - docs/runtime-kernel.md - docs/runtime-v2-architecture-evolution.md - docs/runtime-v2-implementation-notes.md ## UI and product quality contract Maka’s UI is not thrown together — it has a dedicated design system and test plan: - docs/design-system.md: color, density, states, motion, 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: full QA route from first run, settings, sessions, tools, search, bots, gateway to failure paths. Don’t just run TypeScript when changing UI. At minimum, you must: 1. Include node:test contract for the relevant surface. 2. Pass check-console / check-a11y. 3. Add visual fixture or real window smoke tests when necessary. ## Pre-contribution check For typical code changes, at least run: sh npm run typecheck --workspaces --if-present npm run build git diff --check For changes involving desktop renderer / Settings / IPC, run the corresponding focused suite, e.g.: sh npm --workspace @maka/desktop run test -- settings-form-a11y-contract visible-copy-hygiene-contract For changes involving runtime / storage, run the corresponding workspace tests: sh 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 method. - 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.