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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: moa-cli
-Version: 0.2.1
+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 is fronted by a centered separator rule naming it (`──── claude (opus) · OK · 3.5s ────`) with blank lines around it for clear separation, 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,7 +231,7 @@ 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.
 
@@ -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.1 → 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 is fronted by a centered separator rule naming it (`──── claude (opus) · OK · 3.5s ────`) with blank lines around it for clear separation, 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,7 +220,7 @@ 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.
 
@@ -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.1 → moa_cli-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moa-cli"
-version = "0.2.1"
+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.1 → moa_cli-0.2.2}/src/moa_cli/__init__.py

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

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

@@ -560,21 +560,36 @@ def _body(result: RunResult) -> list[str]:
     return ["```text", detail[-1200:], "```", ""]
 
 
-def _render(label: str, result: RunResult) -> str:
-    """A block: two leading blank lines, the named rule, a blank line, the body.
-    The leading blanks give each answer clear breathing room as blocks stream."""
+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) -> str:
+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 ""
     label = f"{result.provider}{model} · {_status_label(result.status)} · {result.elapsed:.1f}s"
-    return _render(label, result)
+    return _render(label, result, plain)
 
 
-def render_synthesis_block(result: RunResult, synthesizer: str) -> str:
+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)
+    return _render(label, result, plain)
 
 
 def result_record(result: RunResult) -> dict:
@@ -601,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 ""
     label = (
         f"round {round_num} · {result.provider}{model} · "
         f"{_status_label(result.status)} · {result.elapsed:.1f}s"
     )
-    return _render(label, result)
+    return _render(label, result, plain)
 
 
-def render_judge_block(result: RunResult, judge: str) -> str:
+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)
+    return _render(label, result, plain)
 
 
 def debate_turn_record(result: RunResult, round_num: int) -> dict:
@@ -877,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
 
 
@@ -1051,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"]