moxie

Mixture of Experts in Engineering — spec-driven multi-agent development with quorum convergence.

moxie runs multiple AI coding agents through a structured pipeline — RFC, audit, fix, plan, build — where every phase requires unanimous agreement before moving on. Agents independently verify each other's work, catching errors that single-agent workflows miss.

Why

A single AI agent reviewing its own work is self-evaluation. moxie forces cross-model verification: different models from different providers check each other's reasoning. When Claude and GPT-5.4 independently agree on an RFC, it's more trustworthy than either alone.

Install

npm install -g @zachjxyz/moxie

Requires Node.js >= 14, Python 3, and at least 2 agent CLIs or a Vercel AI Gateway API key.

Quick start

cd your-project
moxie init

moxie scans for installed agent CLIs and shows available AI Gateway models. Select at least 2:

Select agents (at least 2). CLI agents pre-selected, gateway models available below:

    --- Detected CLI agents ---
  > [x] Claude Code    (2.1.91)
    [x] Codex          (0.118.0)
    --- Vercel AI Gateway ---
    [ ] Claude Opus 4.6       (anthropic/claude-opus-4-6)
    [ ] GPT-5.4               (openai/gpt-5.4)
    [ ] Qwen 3.6 Plus         (qwen/qwen3.6-plus)
    [ ] GLM 5.1               (zai/glm-5.1)
    [ ] Kimi 2.5              (moonshotai/kimi-k2.5)
    ---------------------------------------------------------
    Submit (2 selected)

  arrow keys navigate | space/enter toggle | enter submit (min 2)

If you have a spec or RFC already, pass it in:

moxie init --spec ./my-spec.md

Then verify and start:

moxie doctor
moxie start

moxie doctor

Dependencies:
  [OK] python3
  [OK] caffeinate
  [OK] timeout

Agents (from .moxie/config.toml):
  [OK] claude — 2.1.91 (Claude Code)
  [OK] gpt-gw — openai/gpt-5.4 (AI Gateway, key stored)

Project:
  [OK] .moxie/ directory found
  [OK] spec.md present (720 lines)
  [OK] All phase ledgers and prompts present

All checks passed. Ready to run.

Starting moxie pipeline in background...
  Log: .moxie/moxie.log
  Monitor: moxie status
  Stop: moxie stop

Pipeline started (PID 48291).
Tail the log: tail -f .moxie/moxie.log

Supported agents

CLI agents (detected on PATH)

| Agent | Binary | Install | |-------|--------|---------| | Claude Code | claude | claude.ai/download | | Codex | codex | github.com/openai/codex | | Qwen Code | qwen | github.com/QwenLM/qwen-code | | Aider | aider | pip install aider-chat | | Goose | goose | brew install goose | | Amp | amp | ampcode.com | | Cline | cline | npm install -g cline | | Roo Code | roo | docs.roocode.com |

AI Gateway models (via Vercel AI Gateway)

No CLI install needed — moxie calls the API directly with full tool use. Every Vercel account gets $5/month in free credits with access to all models. Pay-as-you-go after that with zero markup.

| Model | Provider string | |-------|----------------| | Claude Opus 4.6 | anthropic/claude-opus-4-6 | | GPT-5.4 | openai/gpt-5.4 | | Qwen 3.6 Plus | qwen/qwen3.6-plus | | GLM 5.1 | zai/glm-5.1 | | Kimi 2.5 | moonshotai/kimi-k2.5 |

When you select a gateway model during moxie init, you'll be prompted to securely store your API key (macOS Keychain, encrypted file on Linux).

Pipeline

Every project goes through 5 phases, each requiring unanimous quorum:

RFC  ->  Audit  ->  Fix  ->  Plan  ->  Build

1. RFC — Agents analyze the codebase and converge on a comprehensive specification
2. Audit — Agents audit the RFC against the actual source code
3. Fix — Agents fix discrepancies found during audit
4. Plan — Agents produce an implementation plan from the finalized spec
5. Build — Agents implement the plan, taking turns writing and reviewing code

Each phase uses round-robin rotation with randomized order. Agents independently review each other's work and must all sign off before the phase advances.

════════════════════════════════════════════════════════════
  PHASE 1/5: RFC
════════════════════════════════════════════════════════════

╔══════════════════════════════════════════════════╗
║  moxie: RFC phase                                ║
║  Round-robin quorum convergence                 ║
║  Max rounds: 15                                 ║
║  Timeout/turn: 900s                             ║
╚══════════════════════════════════════════════════╝

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Turn 1/15 — claude
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Log: claude-041126-142611.log
  Tokens: 178,108

Quorum after claude's turn:
  claude       pending  .moxie/phases/rfc/claude-041126-142611.md
  gpt-gw       pending  -
  ── 0/2 agents reached quorum

How quorum works

• Agents take turns in a randomized rotation
• After each turn, the agent marks whether it agrees with the current state (reached: true)
• If any agent finds issues, it resets all agents to reached: false
• A phase completes when all healthy agents simultaneously agree
• Agents are told how many turns remain — as the countdown decreases, they prioritize substantive issues over minor nitpicks

╔════════════════════════════════════════════════════════════╗
║  RFC phase complete — quorum reached                      ║
║  Final: RFC-FINAL-041126-220315.md                        ║
║  2/2 agents signed off                                    ║
╚════════════════════════════════════════════════════════════╝

Safeguards

Turn pressure — Every agent prompt includes the current turn count and how many remain. As rounds run low, agents naturally triage harder — accepting minor incompletes rather than resetting quorum over stylistic concerns.

Dead agent detection — If an agent fails 2 consecutive turns (timeout, empty output, quota exhaustion), it's automatically removed from rotation. Quorum adjusts to the remaining healthy agents.

  [DEGRADED] qwen failed 2 consecutive turns — removing from rotation
             (possible quota exhaustion, auth failure, or CLI crash)

Convergence stall detection — If agents argue about the same findings for 3 consecutive rotations without progress, moxie detects the loop and force-accepts the best available draft.

  [convergence] Findings unchanged for 3 rotation(s) (3 triggers force-accept)

╔════════════════════════════════════════════════════════════╗
║  RFC — force-accepting (convergence stall)                ║
║  Findings stabilized for 3 rotations.                     ║
║  Accepting best available draft as FINAL.                  ║
╚════════════════════════════════════════════════════════════╝

Minimum 2 agents — Single-agent mode is not supported. moxie requires at least 2 healthy agents for cross-model verification.

Commands

moxie init [--spec FILE]    Scaffold .moxie/ with agent selection and config
moxie start [--phase NAME]  Run pipeline in background
moxie stop                  Stop a running pipeline
moxie run [--phase NAME]    Run pipeline in foreground
moxie status                Show phase progress and quorum state
moxie cost                  Token usage and gateway cost breakdown
moxie logs [PHASE]          View logs for a phase
moxie agents                List configured agents
moxie doctor                Check dependencies, agents, and project health

Cost tracking

moxie cost shows token usage per phase and agent:

Token usage by phase:

  RFC:
    claude-gw        950,980 tokens
    gpt-gw           505,430 tokens
    qwen-gw          271,317 tokens
    TOTAL          1,727,727 tokens

Grand total:
  1,727,727 tokens

For gateway agents, moxie also pulls actual USD costs from the Vercel AI Gateway Custom Reporting API (requires Pro or Enterprise plan, currently in beta):

Gateway cost (via Vercel AI Gateway):
  claude-gw            $    5.38  (1,121,678 input + 26,964 output tokens)
  gpt-gw               $    0.17  (32,021 input + 457 output tokens)
  qwen-gw              $    1.27  (349,598 input + 12,723 output tokens)
  TOTAL                $    6.82

  Dashboard: https://vercel.com/~/ai

Each moxie init generates a unique run ID. All gateway requests are tagged with the run ID plus project:moxie, phase:<name>, and agent:<name>, so costs are scoped to the exact session — no date range issues for overnight or multi-day runs.

If the reporting API is unavailable, moxie cost shows token counts only — you can always check your spend in the AI Gateway dashboard directly.

Config

After moxie init, your .moxie/config.toml looks like:

[spec]
path = "spec.md"

[gateway]
endpoint = "https://ai-gateway.vercel.sh"
run_id = "run-20260411-204514-93675"

[agents.claude]
command = "claude --dangerously-skip-permissions --effort max --output-format json -p"
order = 1

[agents.gpt-gw]
type = "gateway"
model = "openai/gpt-5.4"
order = 2

[settings]
max_rounds = 15
max_rounds_build = 50
turn_timeout = 900

Edit this file to change agents, adjust timeouts, or add custom agent commands.

Platform support

| Platform | Status | |----------|--------| | macOS | Fully supported | | Linux | Fully supported | | Windows | WSL required |

License

MIT