How Moa works

The determinism split#

Every workflow separates two kinds of work. The mechanical half — git, gh, the verify-gate, opening and merging PRs — is plain deterministic code. The reasoning half — writing or reviewing code — is the only thing the agent does. The agent never runs git commit, git push, or opens a PR; the orchestrator does, idempotently.

That single rule is what makes Moa safe enough to point at main. A model that can't push can't push to the wrong place. The harness decides what happens to the work; the model only produces it.

The workflow engine#

Each run is a record with a live step timeline, moving through queued → running → succeeded | failed | canceled. A concurrency limit caps how many run at once; each run has a wall-clock timeout and a hard spend cap — cross the ceiling and the run is canceled, so there are no runaway costs. Workflow agents also run under a least-privilege tool denylist that blocks network tools.

The git worktree model

Concurrency is the hard part of doing this safely. Each repo gets one shared base clone; every run does its work in an isolated worktree, one per run, so concurrent runs never collide. Two invariants hold it together:

• Repo setup is serialized per repo, so clones and fetches can't race.
• The base clone stays on a detached HEAD — never a feature branch — so adding a worktree for a branch can never wedge on “already checked out.”

The verify-gate#

Before any writing workflow can open or update a PR, the change has to pass a local gate — typecheck and lint, not just tests — and green CI before merge. If the gate fails, the run stops before a PR is opened. You never get handed a red branch.

Oracles#

An oracle is a read-only knowledge base. Before the agent writes a line, a <domain>-oracle — a separate read-only agent scoped to that KB — can answer questions only from its sources and cite them, so the agent follows your stack's real patterns instead of guessing. If the KB doesn't cover something, the oracle says so rather than inventing an answer. Oracles are auto-wired into coding tasks; you consult them directly with moa oracle consult.

The memory graph#

Every workflow event is captured into a persistent memory graph, powered by LocusGraph. That powers natural-language search, an analytics view (CI-fix rate, file hotspots, trends), and recall-before-fix: Moa checks what it learned from past failures before attempting a new one. A fleet of one-shot runs starts behaving like a teammate that remembers your repo — and memory is isolated per org.

Multi-tenant by design#

Orgs sign in with GitHub, invite members, connect repos, and bring their own Claude key (or use a metered Moa key). Each org is isolated to its own logical database, and tasks are sandboxed so one org's run can't read another's workspace. Secrets — GitHub tokens, per-org keys — are encrypted at rest.