fix(runtime): add gateway to InvocationSource #1587 sets runtimeSource to gateway for cloud activation, but the INVOCATION_SOURCES union never included it, so typecheck and unit build of packages/cli failed after merge with main.
A local-first Agent workspace built for real work.
Maka does more than answer questions. With controlled permissions, it can inspect projects, execute tools, produce artifacts, and preserve model messages, tool calls, and durable-task progress as recoverable execution facts. The same Runtime is available through the desktop app, terminal TUI, non-interactive CLI, and Headless runner.
[!IMPORTANT] Maka is under active development. The macOS Apple Silicon desktop build is an early public release; data formats, CLI commands, and experimental capabilities may still change.
Read Maka Backend Architecture for the complete design.
| Entry point | Best for | Current capability |
|---|---|---|
| Desktop | Daily interaction, file and Artifact workflows, model and permission setup | Electron + React with streaming sessions, tool timelines, branching, search, and recovery |
| TUI / CLI | Using Maka in the current project directory or running one non-interactive Turn | maka, maka run; shares workspace and model connections with Desktop |
| Headless | Durable tasks, recoverable TaskRuns, experiments, and evaluation | maka eval with task logs, export, resume, and comparison |
Read, Write, Edit, Bash, Glob, and Grep;The signed and notarized Desktop app is available from GitHub Releases for Apple Silicon Macs only (arm64).
Maka-<version>-mac-arm64.dmg;ripgrep with brew install ripgrep to enable Runtime's Grep tool;Settings → Models.Computer Use is not included in this first public build. Intel Macs, Windows, and Linux packages are not supported yet.
packageManager is npm 11);ripgrep, used by Runtime's Grep tool.git clone https://github.com/Maka-Agent/maka-agent.git cd maka-agent npm ci npm run dev
npm run dev starts the Desktop development environment with HMR. To build every workspace before starting Electron, use:
npm run dev:full
If dependencies were installed with ELECTRON_SKIP_BINARY_DOWNLOAD=1, install the Electron platform binary before starting:
node node_modules/electron/install.js
Maka does not bundle a shared model account. On first launch:
Settings → Models;The app distinguishes configured, send-ready, and experimental connection states. An account flow that is not wired into Runtime is not presented as a usable model.
Build the workspaces first:
npm run build
Then start the TUI or run one Turn:
npm --workspace maka-agent exec -- maka npm --workspace maka-agent exec -- maka run "Summarize this repository and identify its most important risk" npm --workspace maka-agent exec -- maka run --graph "Implement two independent slices, integrate them, then review the result" npm --workspace maka-agent exec -- maka --help
The TUI also accepts /graph on, /graph off, and /graph <task>. Non-interactive --graph runs wait for the durable Graph to finish before printing the final supervisor output. Graph implementation operators use isolated Git worktrees, so the source project must be a clean Git worktree.
The CLI reads the same model connections and workspace configuration written by Desktop. See packages/headless/README.md for Headless commands and its trust posture.
The backend spine is:
Desktop / TUI / Headless ↓ SessionManager → AgentRun → Model + Tool Runtime ↓ Runtime Event Log → Context / Session / UI projections ↓ Task Event Log → TaskRun → Self-check / AHE evidence
Start with ARCHITECTURE.md. It provides the system map, code boundaries, problem-oriented reading paths, and six bilingual deep dives.
apps/desktop/ Electron main / preload / React renderer packages/core/ Pure contracts for Sessions, Events, Permissions, and Connections packages/storage/ SQLite operational state, legacy importers, and payload stores packages/runtime/ AgentRun, model adapters, tools, context, and recovery packages/headless/ TaskRun, Autonomous Loop, Self-check, eval, and AHE packages/cli/ TUI and non-interactive CLI packages/ui/ Shared conversation, Markdown, Artifact, and UI primitives docs/ Architecture, product, security, privacy, and test contracts scripts/ Build hygiene, visual checks, smoke tests, and release helpers
Maka stores workspace data under Electron userData by default:
<Electron userData>/workspaces/default/ llm-connections.json credentials.json settings.json sessions/
Current boundaries that matter:
credentials.json, behind the OS account boundary, with POSIX directory mode 0700 and file mode 0600 enforced;credentials.json — the single authority for desktop, TUI, and headless; Electron safeStorage only decrypts pre-existing legacy token files once at desktop startup (#1125);Read SECURITY.md for security reporting and policy, and docs/README.md for current privacy and sandbox contracts.
RuntimeEvent persistence is always canonical in runtime.sqlite. On the first write, Maka batch-idempotently imports legacy RuntimeEvent JSONL without rewriting it. Legacy-only workspaces remain available to read-only inspection until that first write.
Session metadata and Agent Graph control tables now use the same process-local operational database owner and the same runtime.sqlite transaction authority. The first operational open copies a WAL-consistent sessions.sqlite source into runtime.sqlite, validates every source row, and records the source digest and result in cutover_journal. An interrupted copy resumes without partial rows; a legacy database changed after cutover fails closed. The old database is retained as migration evidence but is no longer a production writer. Session transcript bodies remain append-only JSONL.
Core execution state now shares that authority too: AgentRun headers and event ledgers, event projections, root-turn admissions and source proofs, Interactions, Host Epoch message receipts, and ShellRun records are canonical in runtime.sqlite across CLI, Desktop, Runtime Host, and Headless. Each legacy file store is fingerprinted and imported through its own durable cutover_journal entry before the corresponding repository opens. Copy and validation are one SQLite transaction, retries are idempotent, and a changed legacy source after cutover fails closed. The legacy files are retained only as migration evidence; new execution writes do not modify them.
Workflow state is migrating in reviewable slices. Task Ledger events and projections, Plan events and projections, Deep Research events, and Plan Reminder records are now canonical in runtime.sqlite. Desktop and Runtime Host production wiring opens these SQLite repositories; their JSON/JSONL predecessors are read only during a fingerprinted, crash-safe cutover and are never updated by later mutations.
Usage telemetry and pricing authority now use that same operational database. Legacy telemetry.json and pricing.json sources are decoded together and fingerprinted before their rows and pricing revision are committed atomically. After cutover, Desktop and Runtime Host write only runtime.sqlite; the source files remain unchanged as migration evidence.
Artifact metadata and lifecycle state now follow the same rule. Payload bytes remain files, but their records are canonical in runtime.sqlite after a fingerprinted metadata.jsonl cutover. Payload publication keeps its durable staging/link protocol: recovery removes bytes whose metadata transaction did not commit and preserves committed bytes while cleaning staging residue. Purge intent recovery likewise completes against the SQLite metadata authority.
Selected-session bundle export now reads that SQLite authority through a WAL-consistent snapshot, verifies that retained legacy evidence still matches its completed cutover, and writes only the selected Artifact rows into the bundle's runtime.sqlite. Payload bytes are copied under the Artifact writer lock, cross-session rows and payloads are excluded, and bundles no longer emit artifacts/metadata.jsonl.
Full operational backup now uses the shared database owner's online SQLite backup API rather than copying runtime.sqlite or its WAL sidecars. A strict manifest binds the standalone database snapshot to every active session transcript and canonical Artifact payload by size and SHA-256. Restore verifies SQLite integrity, foreign keys, supported schema versions, relational identity sets, transcript decodability, and the exact manifested file tree before atomically publishing a new state root. Interrupted backup or restore staging is removed and can be retried without changing either source.
Headless trajectory hydration now consumes a frozen selected-session export from that SQLite Artifact authority. The cell publishes trajectory-state only when RuntimeEvents reference image Artifacts; Harbor downloads its standalone runtime.sqlite first and then only the payloads referenced by the validated snapshot. It does not copy a live WAL or fall back to artifacts/metadata.jsonl. Missing, corrupt, unsupported, or mismatched evidence fails closed to a summary trajectory instead of mixing authorities.
The remaining storage work is deliberately classified rather than implied complete:
artifacts/metadata.jsonl is accepted only as fingerprinted, read-only cutover evidence, and can be removed after the migration/cutover matrix is complete;Runtime continuation remains opt-in:
MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1 enables the Desktop interrupted-turn Safe resume action, CLI/TUI /resume, and Desktop startup auto-resume. These paths may call the configured model provider and consume tokens. Enable the flag only when that behavior is explicitly desired.Phase 2 provides the durable write-side boundary and fail-closed safe-boundary continuation. Phase 3 reconciliation for indeterminate tool side effects is not implemented yet; ambiguous tool outcomes remain parked rather than retried.
Common repository-level commands:
npm run build npm run typecheck npm test npm run check:release
Run one workspace in isolation:
npm --workspace @maka/runtime test npm --workspace @maka/headless test npm --workspace @maka/desktop test
Use the following commands to update packages/core/src/model-metadata.generated.ts from models.dev and run the focused tests. Keep access-path-specific overrides in model-metadata.ts; do not edit the generated file by hand.
npm run sync:model-metadata npm run test:scripts npm --workspace @maka/core test
Desktop real-window and visual verification:
npm --workspace @maka/desktop run e2e npm --workspace @maka/desktop run smoke:real-window
Before submitting code, run typecheck, build, and focused tests proportionate to the change, followed by git diff --check.
Maka is licensed under the Apache License 2.0. See NOTICE for attribution information. Third-party components remain subject to their respective licenses and notices.