MomongaCode

Architecture

MomongaCode is an npm workspace of packages under packages/. The momonga command is a client; the work is done by background processes.

  • Client. packages/cli (command line, terminal UI, ACP server). It starts and talks to the daemon.
  • Supervisor. packages/supervisor runs the daemon: it starts, restarts, and stops two child processes, the gateway and the runtime. Each start of the daemon is a generation with its own supervisor; a newer generation takes over new work while an older one finishes what it runs and ends by itself. A settings change applies in place: each child reads the settings per operation, and no child is restarted for it.
  • Runtime. packages/runtime runs sessions, runs, and the model and tool loop. It builds each request with packages/context, applies packages/policy to tool calls, executes tools from packages/tools inside packages/sandbox, and records everything in packages/store.
  • Gateway. packages/gateway is the one place that talks to models. It has adapters for chat-completions, Open Responses, Anthropic, and Ollama, plus routing, retry, admission, and probing. Apple's fm is a managed server: a server program that MomongaCode starts itself and reaches through the chat-completions adapter.
  • Store. packages/store holds runs, events, approvals, memories, rules, and jobs in databases under ~/.momonga/state.
  • Context. packages/context builds the context under a token budget, compacts history, and formats tool output.
  • Memory. packages/memory holds the logic for memory validity, recall order, deduplication, forgetting, and the memory budget share.
  • Tools. packages/tools defines the built-in tools and executes tool calls. packages/skills and packages/agents load skills and custom agents. packages/mcp connects MCP servers.
  • Policy. packages/policy decides whether a tool call is allowed, from the permission rules, the parsed command, and the paths it touches.
  • Sandbox. packages/sandbox runs commands under Seatbelt or bubblewrap.
  • Configuration. packages/config defines the settings schema and merges the user, project, and local layers.
  • Shared. packages/protocol (types, constants, wire formats), packages/foundation (paths, locks, platform code, credentials), packages/observability (traces, cost, OTLP), packages/reliability (reliability reports).
  • Verification and evaluation. packages/verify (rule verification with Z3), packages/eval (datasets, reports, comparison), packages/testkit (fakes for tests).

The formal models of the state machines are TLA+ specifications in specs/tla/, checked with TLC in the test suite.