moa-cli 0.1.0__py3-none-any.whl

moa_cli/__init__.py

@@ -0,0 +1,3 @@
+"""MOA CLI package."""
+
+__version__ = "0.1.0"

moa_cli/cli.py

@@ -0,0 +1,543 @@
+"""moa - ask one question to multiple local AI coding CLIs in parallel.
+
+Everything lives in this one module on purpose: the tool is small, and a single
+file is easier to read end to end than five files that each do one small thing.
+The sections below (providers / runner / synthesis / render / cli) are the seams
+to split on if it ever genuinely outgrows one file.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import random
+import shutil
+import signal
+import sys
+import tempfile
+import time
+from collections.abc import AsyncIterator, Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, Literal
+
+import typer
+
+# --------------------------------------------------------------------------- #
+# Providers: each agent CLI we know how to drive.
+# --------------------------------------------------------------------------- #
+
+# A command builder turns (prompt, model, output_file) into an argv list.
+# output_file is a path the CLI may be told to write its final answer to; it is
+# None for providers that answer cleanly on stdout. Only codex uses it.
+CommandBuilder = Callable[[str, str, str | None], list[str]]
+
+
+@dataclass(frozen=True)
+class Provider:
+    name: str
+    executable: str
+    default_model: str
+    build: CommandBuilder
+    # Env keys to drop before spawning. claude refuses to run nested inside
+    # Claude Code unless CLAUDECODE is cleared, so moa can call it from an agent.
+    unset_env: tuple[str, ...] = ()
+    # codex's stdout is session chrome; its real answer goes to an output file.
+    uses_output_file: bool = False
+
+    def env(self) -> dict[str, str]:
+        env = dict(os.environ)
+        env.setdefault("NO_COLOR", "1")
+        env.setdefault("TERM", "dumb")
+        for key in self.unset_env:
+            env.pop(key, None)
+        return env
+
+
+def _claude(prompt: str, model: str, _out: str | None) -> list[str]:
+    return ["claude", "--model", model, "-p", prompt]
+
+
+def _codex(prompt: str, model: str, out: str | None) -> list[str]:
+    cmd = ["codex", "exec", "-m", model, "--skip-git-repo-check", "--color", "never"]
+    if out:
+        cmd += ["-o", out]
+    cmd.append(prompt)
+    return cmd
+
+
+def _agy(prompt: str, model: str, _out: str | None) -> list[str]:
+    # agy also hosts Claude/GPT-OSS models, so we pin a Gemini model explicitly
+    # to keep the panel diverse. Without --model it defaults to Gemini Flash.
+    return ["agy", "--model", model, "-p", prompt]
+
+
+def _opencode(prompt: str, model: str, _out: str | None) -> list[str]:
+    # opencode has no universal default model (it depends on which provider the
+    # user has authed), so we omit -m when no model is given and let opencode
+    # pick its own default. The prompt is a positional arg.
+    cmd = ["opencode", "run"]
+    if model:
+        cmd += ["-m", model]
+    cmd.append(prompt)
+    return cmd
+
+
+PROVIDERS: dict[str, Provider] = {
+    "claude": Provider("claude", "claude", "opus", _claude, unset_env=("CLAUDECODE",)),
+    "codex": Provider("codex", "codex", "gpt-5.5", _codex, uses_output_file=True),
+    "agy": Provider("agy", "agy", "Gemini 3.1 Pro (High)", _agy),
+    "opencode": Provider("opencode", "opencode", "", _opencode),
+}
+
+# Auto-selection order, roughly by popularity. -n/--num walks this list and
+# takes the first N that are actually installed.
+PRIORITY: tuple[str, ...] = ("claude", "codex", "agy", "opencode")
+
+
+def _installed(name: str) -> bool:
+    return shutil.which(PROVIDERS[name].executable) is not None
+
+
+def available_provider_names() -> list[str]:
+    return [name for name in PRIORITY if _installed(name)]
+
+
+def missing_provider_names() -> list[str]:
+    return [name for name in PRIORITY if not _installed(name)]
+
+
+def select_for_run(
+    num: int, names: tuple[str, ...] | None, exclude: tuple[str, ...] = ()
+) -> tuple[list[Provider], list[str]]:
+    """Pick providers to run, returning (to_run, skipped_because_not_installed).
+
+    With an explicit `names` list we honour it in order, skipping any not
+    installed. Otherwise we take the first `num` installed providers from
+    PRIORITY. Excluded providers are dropped before either path takes effect, so
+    `-n` counts only non-excluded installs and `-p` pins drop excluded names too.
+    """
+    unknown = [name for name in (*(names or ()), *exclude) if name not in PROVIDERS]
+    if unknown:
+        raise ValueError(f"Unknown provider(s): {', '.join(unknown)}")
+    excluded = set(exclude)
+    if names:
+        chosen = [PROVIDERS[name] for name in names if name not in excluded and _installed(name)]
+        skipped = [name for name in names if name not in excluded and not _installed(name)]
+        return chosen, skipped
+    available = [name for name in available_provider_names() if name not in excluded]
+    return [PROVIDERS[name] for name in available[:num]], []
+
+
+# --------------------------------------------------------------------------- #
+# Runner: spawn each CLI as a parallel subprocess and collect its answer.
+# --------------------------------------------------------------------------- #
+
+Status = Literal["ok", "failed", "timeout", "missing"]
+
+
+@dataclass(frozen=True)
+class RunResult:
+    provider: str
+    model: str
+    status: Status
+    stdout: str
+    stderr: str
+    elapsed: float
+    returncode: int | None
+
+
+def _decode(data: bytes | None) -> str:
+    return (data or b"").decode(errors="replace").strip()
+
+
+async def _terminate(process: asyncio.subprocess.Process) -> None:
+    """Kill the whole process group (SIGTERM, then SIGKILL) on timeout."""
+    if process.returncode is not None:
+        return
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    except Exception:
+        process.terminate()
+    try:
+        await asyncio.wait_for(process.wait(), timeout=2)
+        return
+    except asyncio.TimeoutError:
+        pass
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        return
+    except Exception:
+        process.kill()
+    await process.wait()
+
+
+async def run_provider(provider: Provider, prompt: str, timeout: float, model: str | None = None) -> RunResult:
+    model = model or provider.default_model
+    out_file: str | None = None
+    if provider.uses_output_file:
+        handle, out_file = tempfile.mkstemp(prefix="moa-", suffix=".txt")
+        os.close(handle)
+
+    start = time.monotonic()
+    try:
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *provider.build(prompt, model, out_file),
+                # DEVNULL is essential: codex and agy block forever on an
+                # inherited TTY stdin, burning the entire timeout otherwise.
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env=provider.env(),
+                start_new_session=True,  # own process group, so _terminate can killpg
+            )
+        except FileNotFoundError:
+            return RunResult(provider.name, model, "missing", "", f"{provider.executable} is not installed.", time.monotonic() - start, None)
+
+        try:
+            stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)
+        except asyncio.TimeoutError:
+            await _terminate(process)
+            return RunResult(provider.name, model, "timeout", "", f"Timed out after {timeout:g}s.", time.monotonic() - start, None)
+
+        elapsed = time.monotonic() - start
+        error = _decode(stderr)
+        # For output-file providers the file is authoritative; stdout is noise,
+        # so an empty file means failure rather than reporting that noise.
+        if out_file:
+            answer = Path(out_file).read_text(encoding="utf-8", errors="replace").strip()
+        else:
+            answer = _decode(stdout)
+        status: Status = "ok" if process.returncode == 0 and answer else "failed"
+        return RunResult(provider.name, model, status, answer, error, elapsed, process.returncode)
+    finally:
+        if out_file:
+            try:
+                os.unlink(out_file)
+            except OSError:
+                pass
+
+
+async def stream(
+    providers: list[Provider], prompt: str, timeout: float, models: dict[str, str] | None = None
+) -> AsyncIterator[RunResult]:
+    """Run every provider in parallel, yielding each result as it finishes."""
+    models = models or {}
+    tasks = [
+        asyncio.create_task(run_provider(p, prompt, timeout, models.get(p.name))) for p in providers
+    ]
+    for completed in asyncio.as_completed(tasks):
+        yield await completed
+
+
+# --------------------------------------------------------------------------- #
+# Synthesis: merge the collected answers into one unified answer.
+# --------------------------------------------------------------------------- #
+
+SYNTHESIZER_PROMPT = """You are the synthesizer in a mixture-of-agents system. You are given a \
+user's question and several independent answers produced by different AI assistants. Produce a \
+single, unified answer that is more accurate, complete, and useful than any individual response.
+
+Guidelines:
+- Identify where the answers agree, where they complement each other, and where they conflict.
+- Resolve conflicts by the quality of reasoning and evidence; use agreement as a tiebreaker.
+- Keep what is correct and valuable; drop what is wrong, redundant, or unsupported.
+- Write a clear, well-structured, self-contained answer. Do not refer to "Response A", the other \
+answers, or the fact that you are synthesizing. Just give the best possible answer.
+- Do not invent information that none of the responses support."""
+
+
+def choose_synthesizer(choice: str, candidates: list[str], rng: random.Random | None = None) -> str:
+    """Resolve --synthesizer against the providers that actually ran.
+
+    "auto"/"first" takes the highest-priority candidate, "random" picks one at
+    random, anything else must name a known provider.
+    """
+    if not candidates:
+        raise ValueError("No candidate providers available to synthesize.")
+    if choice in ("auto", "first"):
+        return candidates[0]
+    if choice == "random":
+        return (rng or random).choice(candidates)
+    if choice in PROVIDERS:
+        return choice
+    raise ValueError(f"Unknown synthesizer: {choice}")
+
+
+def build_synthesis_prompt(
+    question: str,
+    results: list[RunResult],
+    blind: bool,
+    rng: random.Random | None = None,
+) -> tuple[str, dict[str, str]]:
+    """Build the synthesizer prompt and return (prompt, label_map).
+
+    In blind mode the answers are shuffled and shown as "Response A/B/C" with no
+    provider names, so the synthesizer can't favour a brand. The label_map
+    (A -> claude, ...) lets the caller reveal attribution afterwards.
+    """
+    answers = [r for r in results if r.status == "ok"]
+    sections: list[str] = []
+    label_map: dict[str, str] = {}
+
+    if blind:
+        shuffled = list(answers)
+        (rng or random).shuffle(shuffled)
+        for offset, result in enumerate(shuffled):
+            tag = chr(ord("A") + offset)
+            sections.append(f"### Response {tag}\n\n{result.stdout.strip()}")
+            label_map[tag] = result.provider
+    else:
+        for result in answers:
+            sections.append(f"### {result.provider}\n\n{result.stdout.strip()}")
+            label_map[result.provider] = result.provider
+
+    prompt = (
+        f"{SYNTHESIZER_PROMPT}\n\n"
+        f"## User question\n\n{question}\n\n"
+        f"## Responses to synthesize\n\n" + "\n\n".join(sections) + "\n\n## Your synthesized answer\n"
+    )
+    return prompt, label_map
+
+
+# --------------------------------------------------------------------------- #
+# Render: stdout carries content (Markdown or JSONL); stderr carries progress.
+# --------------------------------------------------------------------------- #
+
+_STATUS_LABELS = {"ok": "OK", "failed": "FAILED", "timeout": "TIMEOUT", "missing": "MISSING"}
+
+
+def _status_label(status: str) -> str:
+    return _STATUS_LABELS.get(status, status.upper())
+
+
+def _body(result: RunResult) -> list[str]:
+    if result.status == "ok":
+        return [result.stdout.strip(), ""]
+    detail = result.stderr or f"Process exited with return code {result.returncode}."
+    return ["```text", detail[-1200:], "```", ""]
+
+
+def render_block(result: RunResult) -> str:
+    model = f" ({result.model})" if result.model else ""
+    heading = f"## {result.provider}{model} - {_status_label(result.status)} - {result.elapsed:.1f}s"
+    return "\n".join([heading, "", *_body(result)])
+
+
+def render_synthesis_block(result: RunResult, synthesizer: str) -> str:
+    heading = f"## synthesis · via {synthesizer} - {_status_label(result.status)} - {result.elapsed:.1f}s"
+    return "\n".join([heading, "", *_body(result)])
+
+
+def result_record(result: RunResult) -> dict:
+    return {
+        "type": "response",
+        "provider": result.provider,
+        "model": result.model,
+        "status": result.status,
+        "elapsed": round(result.elapsed, 3),
+        "returncode": result.returncode,
+        "text": result.stdout,
+        "stderr": result.stderr,
+    }
+
+
+def synthesis_record(result: RunResult, synthesizer: str) -> dict:
+    return {
+        "type": "synthesis",
+        "synthesizer": synthesizer,
+        "status": result.status,
+        "elapsed": round(result.elapsed, 3),
+        "text": result.stdout,
+        "stderr": result.stderr,
+    }
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+
+app = typer.Typer(
+    name="moa",
+    help="Ask one question to multiple local AI coding CLIs in parallel and collect their answers.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def parse_model_overrides(entries: list[str] | None) -> dict[str, str]:
+    """Parse repeated `-m provider=model` flags into a {provider: model} dict.
+
+    Each entry must contain `=` and name a known provider. The model string is
+    passed through verbatim (formats differ per tool); the underlying CLI
+    validates it. Bad format or unknown provider raises BadParameter.
+    """
+    models: dict[str, str] = {}
+    for entry in entries or []:
+        if "=" not in entry:
+            raise typer.BadParameter(f"--model expects PROVIDER=MODEL, got: {entry!r}")
+        provider, model = entry.split("=", 1)
+        provider = provider.strip()
+        if provider not in PROVIDERS:
+            raise typer.BadParameter(
+                f"Unknown provider in --model: {provider!r}. Known: {', '.join(PROVIDERS)}."
+            )
+        models[provider] = model
+    return models
+
+
+def _read_prompt(prompt: str | None, file: Path | None) -> str:
+    if file is not None:
+        if str(file) == "-":
+            return sys.stdin.read().strip()
+        return file.read_text(encoding="utf-8").strip()
+    if prompt == "-":
+        return sys.stdin.read().strip()
+    if prompt:
+        return prompt.strip()
+    if not sys.stdin.isatty():
+        return sys.stdin.read().strip()
+    raise typer.BadParameter("Provide a prompt, --file, or pipe prompt text on stdin.")
+
+
+def _note(message: str) -> None:
+    """Progress and selection notes go to stderr so stdout stays pure content."""
+    typer.echo(message, err=True)
+
+
+def _emit(text: str) -> None:
+    sys.stdout.write(text.rstrip("\n") + "\n")
+    sys.stdout.flush()
+
+
+async def _collect(
+    providers: list[Provider],
+    prompt: str,
+    timeout: float,
+    json_output: bool,
+    models: dict[str, str] | None = None,
+) -> list[RunResult]:
+    results: list[RunResult] = []
+    async for result in stream(providers, prompt, timeout, models):
+        results.append(result)
+        _emit(json.dumps(result_record(result)) if json_output else render_block(result))
+    return results
+
+
+@app.command()
+def ask(
+    prompt: Annotated[str | None, typer.Argument(help="Prompt to send to each agent. Use '-' for stdin.")] = None,
+    num: Annotated[int, typer.Option("--num", "-n", help="How many agents to ask, taken in priority order.")] = 3,
+    provider: Annotated[
+        list[str] | None,
+        typer.Option("--provider", "-p", help="Pin specific agent(s). Repeatable. Overrides --num."),
+    ] = None,
+    exclude: Annotated[
+        list[str] | None,
+        typer.Option("--exclude", "-x", help="Drop agent(s) from the run. Repeatable."),
+    ] = None,
+    model: Annotated[
+        list[str] | None,
+        typer.Option("--model", "-m", help="Override a tool's model: PROVIDER=MODEL. Repeatable."),
+    ] = None,
+    file: Annotated[Path | None, typer.Option("--file", "-f", help="Read the prompt from a file or '-' for stdin.")] = None,
+    timeout: Annotated[float, typer.Option("--timeout", "-t", help="Per-agent timeout in seconds.")] = 180,
+    synth: Annotated[bool, typer.Option("--synth", help="Also synthesize the answers into one unified answer.")] = False,
+    synthesizer: Annotated[
+        str,
+        typer.Option("--synthesizer", help="Who synthesizes: auto | random | a provider name."),
+    ] = "auto",
+    json_output: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSONL.")] = False,
+) -> None:
+    """Ask multiple agents in parallel; answers stream back as each one finishes."""
+    prompt_text = _read_prompt(prompt, file)
+    if not prompt_text:
+        raise typer.BadParameter("Prompt cannot be empty.")
+    if num < 1:
+        raise typer.BadParameter("--num must be at least 1.")
+
+    models = parse_model_overrides(model)
+
+    try:
+        selected, skipped = select_for_run(
+            num, tuple(provider) if provider else None, tuple(exclude) if exclude else ()
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    if not selected:
+        _note("No agents available. Run `moa doctor` to see which CLIs are installed.")
+        raise typer.Exit(code=1)
+
+    note = f"Asking {', '.join(p.name for p in selected)} (timeout {timeout:g}s)"
+    if skipped:
+        note += f"; skipped (not installed): {', '.join(skipped)}"
+    if exclude:
+        note += f"; excluded: {', '.join(exclude)}"
+    _note(note)
+
+    results = asyncio.run(_collect(selected, prompt_text, timeout, json_output, models))
+    successes = [r for r in results if r.status == "ok"]
+
+    if synth:
+        _run_synthesis(prompt_text, results, successes, selected, synthesizer, timeout, json_output, models)
+
+    if not successes:
+        raise typer.Exit(code=1)
+
+
+def _run_synthesis(
+    prompt_text: str,
+    results: list[RunResult],
+    successes: list[RunResult],
+    selected: list[Provider],
+    synthesizer: str,
+    timeout: float,
+    json_output: bool,
+    models: dict[str, str] | None = None,
+) -> None:
+    if len(successes) < 2:
+        _note("Synthesis skipped: need at least 2 successful responses.")
+        return
+
+    candidates = [p.name for p in selected]
+    try:
+        synth_name = choose_synthesizer(synthesizer, candidates)
+    except ValueError as exc:
+        _note(f"Synthesis skipped: {exc}")
+        return
+
+    # Synthesis always anonymizes + shuffles its input so the synthesizer can't
+    # favour a brand. The A/B/C labels stay internal; the human already sees real
+    # names on the response blocks above.
+    synth_prompt, _label_map = build_synthesis_prompt(prompt_text, results, blind=True)
+    _note(f"Synthesizing with {synth_name}...")
+    synth_model = (models or {}).get(synth_name)
+    synth_result = asyncio.run(run_provider(PROVIDERS[synth_name], synth_prompt, timeout, synth_model))
+
+    if json_output:
+        _emit(json.dumps(synthesis_record(synth_result, synth_name)))
+    else:
+        _emit(render_synthesis_block(synth_result, synth_name))
+
+
+@app.command()
+def doctor() -> None:
+    """Show which agent CLIs are installed."""
+    available = available_provider_names()
+    missing = missing_provider_names()
+
+    def fmt(names: list[str]) -> str:
+        return ", ".join(f"{name} ({PROVIDERS[name].executable})" for name in names) or "none"
+
+    typer.echo("Available agents: " + fmt(available))
+    typer.echo("Missing agents:   " + fmt(missing))
+
+
+def main() -> None:
+    app()

moa_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.3
+Name: moa-cli
+Version: 0.1.0
+Summary: Ask one question to multiple local AI coding CLIs in parallel and collect their answers.
+Keywords: llm,agents,cli,claude,codex,agy,opencode,peer-review
+Author: Paul-Louis Pröve
+Author-email: Paul-Louis Pröve <plp@workgenius.com>
+Requires-Dist: typer>=0.25.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo-full.png" alt="moa - mixture of agents" width="360">
+</p>
+
+<p align="center">
+  <a href="https://github.com/pietz/moa-cli/actions/workflows/ci.yml"><img src="https://github.com/pietz/moa-cli/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+</p>
+
+# MOA - Mixture of Agents
+
+Ask one question to multiple local AI coding CLIs **in parallel** and collect their answers. MOA detects which agent CLIs you have installed (Claude Code, Codex, agy, opencode), fans your prompt out to them, and streams each answer back the moment that agent finishes. Optionally, it can synthesize the answers into a single unified response.
+
+It's a drop-in, batteries-included replacement for hand-rolling parallel `claude -p` / `codex exec` / `opencode run` calls (or a "peer review" agent skill): one command, clean attributed output, made to be called by a human **or** by another agent.
+
+The package is named `moa-cli` but installs the command `moa`.
+
+```bash
+uv tool install moa-cli
+moa ask "Is Postgres or SQLite better for a desktop app?"
+```
+
+Or run it once without installing:
+
+```bash
+uvx --from moa-cli moa ask "Review this plan."
+```
+
+## Why
+
+A single model gives you one perspective. Asking three frontier models the same question - and seeing where they agree, diverge, or contradict - is a fast, cheap way to pressure-test an answer. MOA makes that a one-liner using the CLIs you already pay for, with no API keys of its own.
+
+## Usage
+
+```bash
+moa doctor                                  # show which agent CLIs are installed
+moa ask "Should this feature use SQLite?"   # ask the top 3 installed agents
+moa ask -n 2 "..."                          # ask only the top 2 (priority order)
+moa ask -p claude -p agy "..."              # pin specific agents
+moa ask -x claude "..."                     # drop an agent (e.g. exclude the caller's own model)
+moa ask -m claude=sonnet "..."              # override which model a tool uses
+moa ask --synth "..."                       # also merge the answers into one
+moa ask --json "..."                        # machine-readable JSONL (for agents/pipes)
+git diff | moa ask -f - "Review this diff." # read the prompt from stdin
+```
+
+### How agents are selected
+
+`-n/--num` (default 3) picks the first N **installed** agents from a popularity-ordered priority list:
+
+```
+claude  ->  codex  ->  agy  ->  opencode
+```
+
+So `moa ask -n 3` on a machine with all four installed asks Claude, Codex, and agy. Use `-p/--provider` (repeatable) to pin an exact set and ignore `-n`.
+
+Use `-x/--exclude` (repeatable) to drop one or more agents from the run. Exclusion is applied *before* `-n` takes the first N, and it also drops excluded names from an explicit `-p` set. It is off by default. The motivating case: an agent (e.g. Claude Code) calls `moa` for *other* opinions; `moa ask -x claude` makes sure one "peer" isn't just the caller's own model. So `moa ask -n 3 -x claude` asks Codex, agy, and opencode.
+
+### Choosing models
+
+Each tool ships with a reasonable default model, but you can override which model any tool uses with `-m/--model PROVIDER=MODEL` (repeatable). Only the providers you name change; the rest keep their defaults.
+
+```bash
+moa ask -m claude=sonnet -m agy="Gemini 3.1 Pro (Low)" "..."
+```
+
+The model-string format differs per tool and is passed through verbatim (the tool's own CLI validates it):
+
+| Provider   | Default                 | `-m` format                                            |
+| ---------- | ----------------------- | ------------------------------------------------------ |
+| `claude`   | `opus`                  | short id, e.g. `claude=sonnet`                         |
+| `codex`    | `gpt-5.5`               | model id, e.g. `codex=gpt-5.5`                         |
+| `agy`      | `Gemini 3.1 Pro (High)` | exact display name, e.g. `agy="Gemini 3.1 Pro (Low)"`  |
+| `opencode` | (tool's authed default) | `provider/model` slug, e.g. `opencode=anthropic/claude-sonnet-4` |
+
+`opencode` has no built-in default; without an override it omits `-m` and lets opencode pick. Pass `-m opencode=provider/model` to pin one.
+
+### Output
+
+- **stdout** carries only content: each agent's answer as a Markdown block (`## claude (opus) - OK - 3.5s`), flushed the instant that agent finishes, then the synthesis block if `--synth` is set.
+- **stderr** carries progress and selection notes (`Asking claude, codex ...`), so piping stdout stays clean.
+- `--json` emits one JSON object per line (JSONL): a `{"type": "response", ...}` record per agent as it completes, then a `{"type": "synthesis", ...}` record. Ideal when another agent calls MOA and parses the result.
+
+### Synthesis
+
+`--synth` runs one more pass that merges the collected answers into a single, unified answer. The synthesizer is chosen with `--synthesizer`:
+
+- `auto` (default) - the highest-priority agent that ran (deterministic)
+- `random` - pick one of the agents that ran, at random
+- a provider name (`claude`, `codex`, `agy`, `opencode`)
+
+### Attribution policy
+
+The human (or agent) reading MOA's output **always gets correct attribution**: every response block shows the real provider name. There is no human-facing anonymization toggle.
+
+The synthesizer is a different story. To stop it picking favourites by brand, it **always** receives the proposer answers anonymized as "Response A / B / C" and order-shuffled. This is always-on internal behaviour, not a flag. The synthesized answer itself is brand-agnostic prose, and the A/B/C labels never leak into stdout, stderr, or the JSON.
+
+## Supported agents
+
+| Provider    | CLI        | Invocation                                          |
+| ----------- | ---------- | --------------------------------------------------- |
+| `claude`    | `claude`   | `claude --model opus -p PROMPT`                     |
+| `codex`     | `codex`    | `codex exec -m gpt-5.5 --skip-git-repo-check PROMPT`|
+| `agy`       | `agy`      | `agy --model "Gemini 3.1 Pro (High)" -p PROMPT`     |
+| `opencode`  | `opencode` | `opencode run PROMPT`                               |
+
+Adding a new agent is a single entry in the `PROVIDERS` table in `src/moa_cli/cli.py` (executable, default model, command builder); it then participates in detection, `-n` selection, and synthesis automatically.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests
+```
+
+MIT licensed.

moa_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+moa_cli/__init__.py,sha256=FFvRNhGlaMi7lSjgh-MfCNjM55tL7_EjHs-YN6riD7c,46
+moa_cli/cli.py,sha256=KIRtAbL0q0Vi3N1CMlcQltLK5emmMJMk4BQIHXBQ2wo,20223
+moa_cli-0.1.0.dist-info/WHEEL,sha256=oBsDExVIEya4llboy9Ce1l6on8xt3GrtT29y6pYVypw,81
+moa_cli-0.1.0.dist-info/entry_points.txt,sha256=Rh5jxj3Y12DjL1FboVenVOWzBPJN7V-AtAn2-rdIVuA,42
+moa_cli-0.1.0.dist-info/METADATA,sha256=NiTcmPDpWKxzBQjEkA1zyuQD6H_MjlN9GJVY3NCPEDg,6770
+moa_cli-0.1.0.dist-info/RECORD,,

moa_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.23
+Root-Is-Purelib: true
+Tag: py3-none-any

moa_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+moa = moa_cli.cli:main
+