@zachjxyz/moxie 0.2.5 → 0.3.1

package/README.md

@@ -0,0 +1,280 @@
+# moxie
+
+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
+
+```bash
+npm install -g @zachjxyz/moxie
+```
+
+Requires Node.js >= 14, Python 3, and at least 2 agent CLIs or a [Vercel AI Gateway](https://vercel.com/ai-gateway) API key.
+
+## Quick start
+
+```bash
+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:
+
+```bash
+moxie init --spec ./my-spec.md
+```
+
+Then verify and start:
+
+```bash
+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] codex — codex-cli 0.118.0
+
+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](https://claude.ai/download) |
+| Codex | `codex` | [github.com/openai/codex](https://github.com/openai/codex) |
+| Qwen Code | `qwen` | [github.com/QwenLM/qwen-code](https://github.com/QwenLM/qwen-code) |
+| Aider | `aider` | `pip install aider-chat` |
+| Goose | `goose` | `brew install goose` |
+| Amp | `amp` | [ampcode.com](https://ampcode.com) |
+| Cline | `cline` | `npm install -g cline` |
+| Roo Code | `roo` | [docs.roocode.com](https://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](https://vercel.com/docs/ai-gateway/pricing) 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
+  codex        pending  .moxie/phases/rfc/codex-041126-141850.md
+  ── 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
+
+```
+╔════════════════════════════════════════════════════════════╗
+║  RFC phase complete — quorum reached                      ║
+║  Final: RFC-FINAL-041126-220315.md                        ║
+║  2/2 agents signed off                                    ║
+╚════════════════════════════════════════════════════════════╝
+```
+
+### Safeguards
+
+**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
+```
+
+## Config
+
+After `moxie init`, your `.moxie/config.toml` looks like:
+
+```toml
+[spec]
+path = "spec.md"
+
+[gateway]
+endpoint = "https://ai-gateway.vercel.sh"
+
+[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.
+
+## Cost tracking
+
+`moxie cost` shows token usage per phase and agent:
+
+```
+Token usage by phase:
+
+  RFC:
+    claude          12,655,300 tokens (+1 unknown)
+    codex            8,535,058 tokens
+    qwen             2,484,379 tokens (+2 unknown)
+    TOTAL           23,674,737 tokens
+
+Grand total:
+  23,674,737 tokens
+```
+
+For gateway agents, moxie also pulls actual USD costs from the [Vercel AI Gateway Custom Reporting API](https://vercel.com/docs/ai-gateway/capabilities/custom-reporting) (requires Pro or Enterprise plan, currently in beta):
+
+```
+Gateway cost (via Vercel AI Gateway):
+  claude-gw              $4.82  (1,245,890 input + 389,201 output tokens)
+  gpt-gw                 $3.17  (987,654 input + 234,567 output tokens)
+  TOTAL                  $7.99
+
+  Dashboard: https://vercel.com/~/ai
+```
+
+Gateway requests are automatically tagged with `project:moxie`, `phase:<name>`, and `agent:<name>` so you can filter and drill down in the [AI Gateway dashboard](https://vercel.com/docs/ai-gateway).
+
+If you're on the free tier or the reporting API is unavailable, `moxie cost` shows token counts only — you can always check your spend in the AI Gateway dashboard directly.
+
+## Platform support
+
+| Platform | Status |
+|----------|--------|
+| macOS | Fully supported |
+| Linux | Fully supported |
+| Windows | WSL required |
+
+## License
+
+MIT

package/bin/moxie

@@ -16,7 +16,7 @@
 
 set -euo pipefail
 
-MOXIE_VERSION="0.2.5"
+MOXIE_VERSION="0.3.1"
 # Resolve symlinks (npm installs bin as a symlink)
 _self="$0"
 while [ -L "$_self" ]; do
@@ -27,8 +27,10 @@ done
 MOXIE_ROOT="$(cd "$(dirname "$_self")/.." && pwd)"
 MOXIE_LIB="$MOXIE_ROOT/lib"
 
-# Source core library
+# Source core library (platform.sh first — sets MOXIE_PLATFORM for all other libs)
+source "$MOXIE_LIB/platform.sh"
 source "$MOXIE_LIB/core.sh"
+source "$MOXIE_LIB/gateway-keys.sh"
 source "$MOXIE_LIB/agents.sh"
 source "$MOXIE_LIB/phases.sh"
 source "$MOXIE_LIB/tokens.sh"