moa-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{moa_cli-0.2.0 → moa_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: moa-cli
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -36,10 +36,37 @@ Or run it once without installing:
 uvx --from moa-cli moa ask "Review this plan."
 ```
 
+> **Requirements.** MOA drives agent CLIs you install separately - it ships no model
+> or API key of its own. You need at least two of `claude` (Claude Code), `codex`,
+> `agy` (Antigravity), and `opencode` on your `PATH` and logged in. Run **`moa doctor`**
+> first to see which ones MOA can find; with only one installed, the "council" collapses
+> to a single answer.
+
 ## 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.
 
+### Example
+
+```text
+$ moa ask "Is Postgres or SQLite better for a desktop app?"
+Asking claude, codex, agy (timeout 180s, read-only)
+
+──────────────── claude (opus) · OK · 3.2s ────────────────
+
+For a single-user desktop app, SQLite is almost always the right call:
+zero-config, serverless, the whole DB is one file you can ship... [trimmed]
+
+─────────────── codex (gpt-5.5) · OK · 4.1s ───────────────
+
+Use SQLite unless you expect concurrent writers or need network access.
+For a desktop app neither is likely, so SQLite wins on simplicity... [trimmed]
+```
+
+The selection note goes to stderr; the attributed answers go to stdout. In a terminal
+each answer gets the rule shown above; when piped or read by another agent, the same
+blocks render as plain `## ...` headings. Add `--json` for machine-readable JSONL.
+
 ## Usage
 
 MOA has three prompt verbs that share the same selection/output options:
@@ -180,13 +207,13 @@ The synthesizer default is persistable too (e.g. `moa config set synthesizer cod
 
 ### Output
 
-- **stdout** carries only content: each agent's answer as a Markdown block (`## claude (opus) - OK - 3.5s`), flushed the instant that agent finishes. `moa distill` then appends the merged block (`## synthesis · via claude - OK - ...`) once the aggregator finishes.
+- **stdout** carries only content. In a terminal, each agent's answer is fronted by a centered box-drawing rule naming it (`──── claude (opus) · OK · 3.5s ────`) with blank lines for separation, flushed the instant that agent finishes. When stdout is **piped or read by an agent** (not a TTY), the same block renders as a plain, low-noise `## claude (opus) · OK · 3.5s` heading instead - no box-drawing. `moa distill` emits only the final merged block.
 - **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; `distill` then adds a `{"type": "synthesis", ...}` record. `debate` instead emits a `{"type": "debate_turn", "round": N, ...}` record per turn plus a final `{"type": "verdict", ...}` record. Ideal when another agent calls MOA and parses the result.
+- `--json` emits one JSON object per line (JSONL): `ask` writes a `{"type": "response", ...}` record per agent as it completes; `distill` writes a single `{"type": "synthesis", ...}` record (only the merged answer); `debate` writes a `{"type": "debate_turn", "round": N, ...}` record per turn plus a final `{"type": "verdict", ...}` record. Ideal when another agent calls MOA and parses the result.
 
 ### `moa distill` (synthesis)
 
-`distill` runs the same council fan-out as `ask`, then one more pass where a strong aggregator merges the collected answers into a single, unified answer. It needs at least two successful proposer answers; with fewer it streams what it has and skips the merge. The aggregator is chosen with `-s/--synthesizer`:
+`distill` runs the same council fan-out as `ask`, then one more pass where a strong aggregator merges the collected answers into a single, unified answer. **It returns only that merged answer** - the individual proposer responses are intermediates and are not printed (each one's arrival is noted on stderr so the wait isn't silent). It needs at least two successful proposer answers; with fewer it skips the merge and says so on stderr. The aggregator is chosen with `-s/--synthesizer`:
 
 - `auto` (default) - the highest-priority agent that ran (deterministic)
 - `random` - pick one of the agents that ran, at random
@@ -204,9 +231,9 @@ The aggregator prompt is adapted from the Mixture-of-Agents "Aggregate-and-Synth
 
 **The loop.** Round 1: debater A answers cold; debater B sees A's answer with an adversarial-stance instruction ("identify errors/weaknesses before giving your own answer; do not agree merely to reach consensus"). Each later round, every debater sees the other's latest answer and responds in the same spirit. If every debater signals it has *no substantive change* (it may open its reply with `NO SUBSTANTIVE CHANGE`), the debate stops early before the cap.
 
-**The judge.** A model that is **not** a debater reads the full transcript - presented **anonymized and order-shuffled** (a model is judging, so brand/position bias is killed, per item 002) - and writes the final answer. Its prompt instructs it to weigh correctness and evidence **above** confidence and fluency. The judge's verdict is the final block (`## verdict · judge <name> ...`).
+**The judge.** A model that is **not** a debater reads the full transcript - presented **anonymized and order-shuffled** (a model is judging, so brand/position bias is killed) - and writes the final answer. Its prompt instructs it to weigh correctness and evidence **above** confidence and fluency. The judge's verdict is the final block (`──── verdict · judge <name> · ... ────`).
 
-**Streaming/output.** Each debater's turn streams as it completes (`## round N · <provider> ...`), then the judge's verdict last. `--json` emits a `{"type": "debate_turn", "round": N, ...}` record per turn plus a final `{"type": "verdict", ...}` record.
+**Streaming/output.** Each debater's turn streams as it completes (`──── round N · <provider> · ... ────`), then the judge's verdict last. `--json` emits a `{"type": "debate_turn", "round": N, ...}` record per turn plus a final `{"type": "verdict", ...}` record.
 
 **Safety.** Debaters and the judge run in the same read-only (or `--yolo`) mode as the other verbs - there is no permission bypass. agy's partial-sandbox caveat (shell only; it can still edit files) applies here too.
 
@@ -231,6 +258,13 @@ Invocations below show the default (read-only) flags; `--yolo` swaps in each too
 
 Adding a new agent is a single entry in the `PROVIDERS` table in `src/moa_cli/cli.py` (executable, default model, command builder, permission flags); it then participates in detection, `-n` selection, and `distill` automatically.
 
+## Agent skill
+
+If you drive MOA from an agent (e.g. Claude Code), there's a ready-made skill at
+[`skills/moa/SKILL.md`](skills/moa/SKILL.md): it tells an agent when to reach for MOA and
+how to use it (verb choice, self-exclusion via `-x <self>`, parsing the JSONL output). It
+supersedes hand-rolling a "peer review" skill.
+
 ## Development
 
 ```bash

{moa_cli-0.2.0 → moa_cli-0.2.2}/README.md

@@ -25,10 +25,37 @@ Or run it once without installing:
 uvx --from moa-cli moa ask "Review this plan."
 ```
 
+> **Requirements.** MOA drives agent CLIs you install separately - it ships no model
+> or API key of its own. You need at least two of `claude` (Claude Code), `codex`,
+> `agy` (Antigravity), and `opencode` on your `PATH` and logged in. Run **`moa doctor`**
+> first to see which ones MOA can find; with only one installed, the "council" collapses
+> to a single answer.
+
 ## 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.
 
+### Example
+
+```text
+$ moa ask "Is Postgres or SQLite better for a desktop app?"
+Asking claude, codex, agy (timeout 180s, read-only)
+
+──────────────── claude (opus) · OK · 3.2s ────────────────
+
+For a single-user desktop app, SQLite is almost always the right call:
+zero-config, serverless, the whole DB is one file you can ship... [trimmed]
+
+─────────────── codex (gpt-5.5) · OK · 4.1s ───────────────
+
+Use SQLite unless you expect concurrent writers or need network access.
+For a desktop app neither is likely, so SQLite wins on simplicity... [trimmed]
+```
+
+The selection note goes to stderr; the attributed answers go to stdout. In a terminal
+each answer gets the rule shown above; when piped or read by another agent, the same
+blocks render as plain `## ...` headings. Add `--json` for machine-readable JSONL.
+
 ## Usage
 
 MOA has three prompt verbs that share the same selection/output options:
@@ -169,13 +196,13 @@ The synthesizer default is persistable too (e.g. `moa config set synthesizer cod
 
 ### Output
 
-- **stdout** carries only content: each agent's answer as a Markdown block (`## claude (opus) - OK - 3.5s`), flushed the instant that agent finishes. `moa distill` then appends the merged block (`## synthesis · via claude - OK - ...`) once the aggregator finishes.
+- **stdout** carries only content. In a terminal, each agent's answer is fronted by a centered box-drawing rule naming it (`──── claude (opus) · OK · 3.5s ────`) with blank lines for separation, flushed the instant that agent finishes. When stdout is **piped or read by an agent** (not a TTY), the same block renders as a plain, low-noise `## claude (opus) · OK · 3.5s` heading instead - no box-drawing. `moa distill` emits only the final merged block.
 - **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; `distill` then adds a `{"type": "synthesis", ...}` record. `debate` instead emits a `{"type": "debate_turn", "round": N, ...}` record per turn plus a final `{"type": "verdict", ...}` record. Ideal when another agent calls MOA and parses the result.
+- `--json` emits one JSON object per line (JSONL): `ask` writes a `{"type": "response", ...}` record per agent as it completes; `distill` writes a single `{"type": "synthesis", ...}` record (only the merged answer); `debate` writes a `{"type": "debate_turn", "round": N, ...}` record per turn plus a final `{"type": "verdict", ...}` record. Ideal when another agent calls MOA and parses the result.
 
 ### `moa distill` (synthesis)
 
-`distill` runs the same council fan-out as `ask`, then one more pass where a strong aggregator merges the collected answers into a single, unified answer. It needs at least two successful proposer answers; with fewer it streams what it has and skips the merge. The aggregator is chosen with `-s/--synthesizer`:
+`distill` runs the same council fan-out as `ask`, then one more pass where a strong aggregator merges the collected answers into a single, unified answer. **It returns only that merged answer** - the individual proposer responses are intermediates and are not printed (each one's arrival is noted on stderr so the wait isn't silent). It needs at least two successful proposer answers; with fewer it skips the merge and says so on stderr. The aggregator is chosen with `-s/--synthesizer`:
 
 - `auto` (default) - the highest-priority agent that ran (deterministic)
 - `random` - pick one of the agents that ran, at random
@@ -193,9 +220,9 @@ The aggregator prompt is adapted from the Mixture-of-Agents "Aggregate-and-Synth
 
 **The loop.** Round 1: debater A answers cold; debater B sees A's answer with an adversarial-stance instruction ("identify errors/weaknesses before giving your own answer; do not agree merely to reach consensus"). Each later round, every debater sees the other's latest answer and responds in the same spirit. If every debater signals it has *no substantive change* (it may open its reply with `NO SUBSTANTIVE CHANGE`), the debate stops early before the cap.
 
-**The judge.** A model that is **not** a debater reads the full transcript - presented **anonymized and order-shuffled** (a model is judging, so brand/position bias is killed, per item 002) - and writes the final answer. Its prompt instructs it to weigh correctness and evidence **above** confidence and fluency. The judge's verdict is the final block (`## verdict · judge <name> ...`).
+**The judge.** A model that is **not** a debater reads the full transcript - presented **anonymized and order-shuffled** (a model is judging, so brand/position bias is killed) - and writes the final answer. Its prompt instructs it to weigh correctness and evidence **above** confidence and fluency. The judge's verdict is the final block (`──── verdict · judge <name> · ... ────`).
 
-**Streaming/output.** Each debater's turn streams as it completes (`## round N · <provider> ...`), then the judge's verdict last. `--json` emits a `{"type": "debate_turn", "round": N, ...}` record per turn plus a final `{"type": "verdict", ...}` record.
+**Streaming/output.** Each debater's turn streams as it completes (`──── round N · <provider> · ... ────`), then the judge's verdict last. `--json` emits a `{"type": "debate_turn", "round": N, ...}` record per turn plus a final `{"type": "verdict", ...}` record.
 
 **Safety.** Debaters and the judge run in the same read-only (or `--yolo`) mode as the other verbs - there is no permission bypass. agy's partial-sandbox caveat (shell only; it can still edit files) applies here too.
 
@@ -220,6 +247,13 @@ Invocations below show the default (read-only) flags; `--yolo` swaps in each too
 
 Adding a new agent is a single entry in the `PROVIDERS` table in `src/moa_cli/cli.py` (executable, default model, command builder, permission flags); it then participates in detection, `-n` selection, and `distill` automatically.
 
+## Agent skill
+
+If you drive MOA from an agent (e.g. Claude Code), there's a ready-made skill at
+[`skills/moa/SKILL.md`](skills/moa/SKILL.md): it tells an agent when to reach for MOA and
+how to use it (verb choice, self-exclusion via `-x <self>`, parsing the JSONL output). It
+supersedes hand-rolling a "peer review" skill.
+
 ## Development
 
 ```bash

{moa_cli-0.2.0 → moa_cli-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moa-cli"
-version = "0.2.0"
+version = "0.2.2"
 description = "Ask one question to multiple local AI coding CLIs in parallel and collect their answers."
 readme = "README.md"
 authors = [

{moa_cli-0.2.0 → moa_cli-0.2.2}/src/moa_cli/__init__.py

@@ -1,3 +1,3 @@
 """MOA CLI package."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{moa_cli-0.2.0 → moa_cli-0.2.2}/src/moa_cli/cli.py

@@ -532,11 +532,27 @@ def build_judge_prompt(
 
 _STATUS_LABELS = {"ok": "OK", "failed": "FAILED", "timeout": "TIMEOUT", "missing": "MISSING"}
 
+# Width of the separator rule that fronts each answer block. Fixed (not terminal-
+# derived) so output is identical whether shown live or piped to a file.
+_RULE_WIDTH = 60
+
 
 def _status_label(status: str) -> str:
     return _STATUS_LABELS.get(status, status.upper())
 
 
+def _rule(label: str) -> str:
+    """A centered, box-drawing separator that names the block, e.g.
+    `──────── claude (opus) · OK · 2.3s ────────`. Falls back to the bare label
+    when it's wider than the rule."""
+    text = f" {label} "
+    if len(text) >= _RULE_WIDTH:
+        return text.strip()
+    pad = _RULE_WIDTH - len(text)
+    left = pad // 2
+    return "─" * left + text + "─" * (pad - left)
+
+
 def _body(result: RunResult) -> list[str]:
     if result.status == "ok":
         return [result.stdout.strip(), ""]
@@ -544,15 +560,36 @@ def _body(result: RunResult) -> list[str]:
     return ["```text", detail[-1200:], "```", ""]
 
 
-def render_block(result: RunResult) -> str:
+def _plain_output() -> bool:
+    """True when stdout is not an interactive terminal - piped, redirected, or
+    read by another agent (the common "an agent shells out to moa" case). There
+    we drop the decorative box-drawing rule and extra blank lines for a plain,
+    low-noise `## label` heading that is cheaper for a model to consume."""
+    return not sys.stdout.isatty()
+
+
+def _render(label: str, result: RunResult, plain: bool) -> str:
+    """One answer block. In a terminal: two leading blank lines and a centered
+    box-drawing rule, for clear visual separation as blocks stream in. When
+    piped: a plain `## label` heading with a single blank line, no box-drawing."""
+    if plain:
+        return "\n".join(["", f"## {label}", "", *_body(result)])
+    return "\n".join(["", "", _rule(label), "", *_body(result)])
+
+
+def render_block(result: RunResult, plain: bool | None = None) -> str:
+    if plain is None:
+        plain = _plain_output()
     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)])
+    label = f"{result.provider}{model} · {_status_label(result.status)} · {result.elapsed:.1f}s"
+    return _render(label, result, plain)
 
 
-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 render_synthesis_block(result: RunResult, synthesizer: str, plain: bool | None = None) -> str:
+    if plain is None:
+        plain = _plain_output()
+    label = f"synthesis · via {synthesizer} · {_status_label(result.status)} · {result.elapsed:.1f}s"
+    return _render(label, result, plain)
 
 
 def result_record(result: RunResult) -> dict:
@@ -579,18 +616,22 @@ def synthesis_record(result: RunResult, synthesizer: str) -> dict:
     }
 
 
-def render_debate_turn_block(result: RunResult, round_num: int) -> str:
+def render_debate_turn_block(result: RunResult, round_num: int, plain: bool | None = None) -> str:
+    if plain is None:
+        plain = _plain_output()
     model = f" ({result.model})" if result.model else ""
-    heading = (
-        f"## round {round_num} · {result.provider}{model} - "
-        f"{_status_label(result.status)} - {result.elapsed:.1f}s"
+    label = (
+        f"round {round_num} · {result.provider}{model} · "
+        f"{_status_label(result.status)} · {result.elapsed:.1f}s"
     )
-    return "\n".join([heading, "", *_body(result)])
+    return _render(label, result, plain)
 
 
-def render_judge_block(result: RunResult, judge: str) -> str:
-    heading = f"## verdict · judge {judge} - {_status_label(result.status)} - {result.elapsed:.1f}s"
-    return "\n".join([heading, "", *_body(result)])
+def render_judge_block(result: RunResult, judge: str, plain: bool | None = None) -> str:
+    if plain is None:
+        plain = _plain_output()
+    label = f"verdict · judge {judge} · {_status_label(result.status)} · {result.elapsed:.1f}s"
+    return _render(label, result, plain)
 
 
 def debate_turn_record(result: RunResult, round_num: int) -> dict:
@@ -855,11 +896,20 @@ async def _collect(
     json_output: bool,
     models: dict[str, str] | None = None,
     yolo: bool = False,
+    emit_blocks: bool = True,
 ) -> list[RunResult]:
+    """Gather every agent's result. With emit_blocks (ask), each complete answer
+    is flushed to stdout the instant it arrives. Without it (distill), the
+    individual answers are intermediates the user shouldn't see - only the final
+    distilled block is content - so we keep stdout clean and just heartbeat each
+    arrival to stderr so a multi-agent run doesn't look frozen while it waits."""
     results: list[RunResult] = []
     async for result in stream(providers, prompt, timeout, models, yolo):
         results.append(result)
-        _emit(json.dumps(result_record(result)) if json_output else render_block(result))
+        if emit_blocks:
+            _emit(json.dumps(result_record(result)) if json_output else render_block(result))
+        else:
+            _note(f"  {result.provider} responded ({_status_label(result.status)}, {result.elapsed:.1f}s)")
     return results
 
 
@@ -1029,8 +1079,13 @@ def distill(
     # it merges through the same precedence: CLI flag > config file > built-in.
     synthesizer = resolve_option(synthesizer, "synthesizer", _read_config_or_empty(), "auto")
 
+    # distill returns only the merged answer, so the proposer responses are
+    # intermediates: collect them without printing each to stdout.
     results = asyncio.run(
-        _collect(cfg.selected, cfg.prompt, cfg.timeout, cfg.json_output, cfg.models, cfg.yolo)
+        _collect(
+            cfg.selected, cfg.prompt, cfg.timeout, cfg.json_output, cfg.models, cfg.yolo,
+            emit_blocks=False,
+        )
     )
     successes = [r for r in results if r.status == "ok"]