@jakevin7: Open-sourced my previous agent: maka, still under intensive development: https://github.com/jackwener/maka-agent… With so many open-source agents already out there, why build another one? - First, maka is a...

I’ve open-sourced the previously built agent: maka, which is still under heavy development: https://github.com/jackwener/maka-agent… With so many open-source agents already available, why build another one? - maka is first and foremost a desktop agent; a headless mode may appear in the future. maka is not a TUI, but a local-first agent. - We’ve introduced a workflow mechanism into maka, using DAG to enable long-running execution by AI instead of mere looping. - We aim to create a good plugin capability, allowing everyone to customize and add their own features. - Embedded browser with integrated powerful browser automation capabilities. - … maka is currently under intense development. We have a small core team that collaborates using slock & our own agent. — # 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 reading/writing, terminal execution, search, bot entry points, and run recovery into one Electron application. The goal is to let users run an observable, controllable, and recoverable agent on their own computer. This repository is under active development. This README primarily serves two groups: - Users opening Maka for the first time: understand why AI configuration is needed first, where data is stored, and which capabilities are already available. - Engineers continuing to develop Maka: can quickly start, verify, locate key packages, and design documents. ## What You’ll See When you first enter Maka, if no available model connection exists, the initial screen will guide you through AI configuration instead of showing an empty chat box that cannot send messages. The recommended path is: 1. Open Settings -> Models. 2. Select a real model provider, fill in the API key, or complete login for integrated accounts. 3. Test the connection and select the default model. 4. Return to the home screen and start the first conversation using the quick input. Currently integrated model types include: - 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. - Account subscription entry points: Claude Subscription, Codex Subscription, Gemini CLI, etc., are presented separately based on experimental/available status; entry points 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 aspects: - Desktop conversations: create, switch, archive, search, rename, stop, retry, regenerate, branch from a turn. - Model runtime: provider runtime based on Vercel AI SDK, supporting model streaming output, tool calls, usage recording, error classification, and startup recovery. - Local tools: Read, Write, Edit, Bash, Glob, Grep; writing files and executing commands are subject to permission policies. - First-run guidance: displays different states (missing configuration / select default connection / select default model / start conversation) based on actual connection status. - Settings center: models, accounts, usage statistics, daily review, local memory, voice models, open gateways, bot conversations, web search, network proxy, permissions & capabilities, health status, data & about. - Local memory: manage MEMORY.md, manual addition, archive/restore, agent reading toggle. - Web search: configure Tavily credentials, test, and agent tool boundaries. - Bot entry points: framework for configuration/testing/running status of Telegram, Feishu, WeCom, WeChat iLink, Discord, DingTalk, QQ. - Open gateway: local HTTP/SSE API, protected by token, to expose session state, events, capabilities, and health summary externally. - Office document workflow: after local officecli detection, enables reading, validation, and per-use authorization for editing. - Runtime kernel: AgentRun ledger, RuntimeEvent read model, ToolRuntime, ModelAdapter, RunTrace, and recovery logic. ## Local & Privacy Boundaries Maka stores its working data by default in a workspace directory under Electron 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 such as API keys, OAuth tokens, bot tokens, proxy passwords, gateway tokens, and Tavily keys are encrypted via Electron safeStorage and written to credentials.json. - The renderer does not directly access plaintext keys; Settings only displays masked status and test results. - File read/write, shell, and dangerous operations must pass through the permission engine. - Incognito / privacy context, memory, voice, workspace instructions, and other capabilities have separate contract documents defining constraints. ## Quick Start This repository uses npm workspaces. Although a pnpm-workspace.yaml exists, current scripts and lockfile are based on npm. sh npm install npm run dev npm run dev first builds all workspaces, then launches the Electron desktop app. If ELECTRON_SKIP_BINARY_DOWNLOAD=1 was set 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 For 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 variables only affect local development or specific capabilities: | Variable | Purpose | | — | — | | ANTHROPIC_API_KEY | Can be used on first launch to bootstrap an Anthropic connection. | | OPENAI_API_KEY | Can be used on first launch to bootstrap an OpenAI connection. | | TAVILY_API_KEY / MAKA_TAVILY_API_KEY | Source for Tavily credentials used in web search. | | MAKA_RIVE_BIN / RIVE_BIN | Specifies the rive CLI used by Rive workflow. | | MAKA_VISUAL_SMOKE_FIXTURE | Enables deterministic visual fixtures; only for dev/test builds. | ## 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 current runtime has been refactored from one large flow into clearer kernel boundaries: text SessionManager -> AgentRun -> AiSdkBackend -> ModelAdapter -> ToolRuntime -> RunTrace -> AgentRunStore Key principles: - SessionManager remains the public runtime API exposed to the desktop, bots, and gateways. - AgentRun handles durable run facts for a single turn and startup recovery. - 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. 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 thrown together; there is a separate design system and test plan: - docs/design-system.md: color, density, states, animation, Settings IA, copy, and a11y contracts. - docs/ui-quality-plan.md: real windows, visual screenshots, interaction states, regression verification strategy. - docs/full-product-test-plan.md: complete QA roadmap from first run, settings, conversations, tools, search, bot, gateway to failure paths. When modifying UI, do not only run TypeScript. At least accompany with: 1. Corresponding node:test contract for the surface. 2. Passing check-console / check-a11y. 3. Visual fixtures or real window smoke tests when necessary. ## Pre-Contribution Checklist For regular code changes, it is recommended to at least run: sh npm run typecheck --workspaces --if-present npm run build git diff --check For changes involving the desktop renderer / Settings / IPC, additionally run focused suites, e.g.: sh npm --workspace @maka/desktop run test -- settings-form-a11y-contract visible-copy-hygiene-contract For changes involving runtime / storage, additionally run corresponding workspace tests: sh npm --workspace @maka/runtime run test npm --workspace @maka/storage run test ## Related Documents - CHANGELOG.md: summary of currently unpublished changes. - SECURITY.md: security boundaries and reporting procedures. - 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.