hashgraph-online/awesome-codex-plugins / plugins/beastlabai/multi-llm-plugin/skills/multi-llm
multi-llm
FlaggedOrchestrate plan reviews, task generation, implementation and code reviews across several LLM CLIs in parallel, or ask every model one free-text question about a plan. Use when the user says: review my plan, multi-llm, run a code review, generate tasks from a plan, implement this plan, ask the models about my plan.
utils/host_shim.py
View on GitHub"""The shim's text: the slots a template carries, rendering, and the header.
:func:`render` fills a ``hosts/<host>/shim.md.tmpl``; :func:`with_header` adds the
``multi_llm_shim`` header that ``--check`` row 4 and the local-edit guard read.
:mod:`utils.host_install` re-exports these names and owns the write.
"""
from __future__ import annotations
import hashlib
import json
import os
import re
from pathlib import Path
from typing import Dict, Optional, Tuple
from . import host_capabilities as caps
from .cli_common import render_instruction_text, skill_dir
from .host_paths import Refused
from .unattended import uv_missing_text
# ---------------------------------------------------------------------------
# Generation, header block and the slots a template carries
# ---------------------------------------------------------------------------
#: The shim **shape** generation, bumped whenever a template's structure changes
#: (a new step, a new slot, a changed command form) — independent of any content
#: hash. One integer for every host, because one renderer produces every shim: a
#: mismatch means "generated by an older multi-llm", which ``--check`` row 4 can
#: report as exactly that instead of as an unexplained shape failure (D7b).
#:
#: It is not the whole of that row, and deliberately not: the header's
#: ``template_sha256`` answers "was this rendered from the template body shipping
#: today" precisely and by itself, which leaves this counter as the signal for
#: what no digest of a template can see — a changed snippet, a changed verb
#: sentence, a changed :func:`render`. Keeping it out of the prose-only cases is
#: what keeps row 4's message specific, because one integer serves every host: a
#: bump invalidates Codex's installed shim for an edit to OpenCode's template.
#: ``tests/test_install_host.py`` pins every shipped template's digest so that a
#: template edit still arrives as a question about this constant rather than as
#: silence: the ``--exec-subagents`` OpenCode's dispatcher line gained shipped
#: with the counter still at 1, and nothing said so.
#:
#: 3: :func:`render` gained a fourth token, ``{NEEDS_HUMAN_RULE}``, so a shim
#: rendered before it carries no exit-3 decision rule at all — a shape change
#: no template digest sees on its own.
#:
#: 4: the poll command gained ``--host <id>``. The wait is clamped under the
#: ceiling that flag names, so a shim rendered before this one polls with a wait
#: clamped against the tightest ceiling on record instead of its own host's —
#: silently, and on every poll. A changed command form, which is exactly what
#: this counter is for, and it moves for the same reason the ``--exec-subagents``
#: case above did.
#: 5: the OpenCode shim's load step gained ``--to-file`` and reads the core from
#: the ``[CORE_FILE]`` path it prints. Another changed command form.
#: 6: the Codex shim's load step gained ``--page`` and reads the core page by
#: page, checking each ``[CORE_PAGE]`` header and ``[CORE_PAGE_END]`` line.
#: Another changed command form.
SHIM_VERSION = 6
#: The key that identifies a file as ours. ``uninstall-host`` removes files by
#: this block and **never** by filename, so a user's own `multi-llm.md` is safe.
HEADER_KEY = "multi_llm_shim"
#: The header line, per shim format. Markdown gets an HTML comment; a TOML-shaped
#: shim (no host ships one today) gets a `#` comment. Driven off the entry's
#: ``shim.format`` rather than off the host id.
_HEADER_SYNTAX: Dict[str, Tuple[str, str]] = {
"markdown": ("<!-- ", " -->"),
"markdown+frontmatter": ("<!-- ", " -->"),
"toml": ("# ", ""),
}
#: One line, so removing it restores the body byte-for-byte (see :func:`body_of`).
_HEADER_RE = re.compile(
r"^(?:<!--|#)\s*" + HEADER_KEY + r":\s*(\{[^{}]*\})", re.MULTILINE
)
#: Slot -> how it is filled. The three verb slots come from the capability data
#: (``host_capabilities.VERB_SLOTS``); the rest are install-time facts.
SLOT_UV_MISSING_TEXT = "{{uv_missing_text}}"
SLOT_UV_MISSING_FILE = "{{uv_missing_file}}"
#: Every ``{{…}}`` slot spelling the renderer knows, for the "no unfilled slot"
#: assertion. Snippet slots are derived from the files in ``hosts/snippets/``.
_SLOT_RE = re.compile(r"\{\{[a-z_]+\}\}")
#: The rendered ``uv run [flags…] --project <skill dir>`` prefix, in both spellings
#: (quoted, and — for a path with no space — bare). The flag list sits between the
#: two words because it is rendered from ``unattended.uv_run_args``, so nothing
#: here may assume a fixed number of flags or an empty list.
_UV_RUN_FLAGS_RE = r"(?:[ \t]+--[^\s\"]+)*"
_BAKED_PREFIX_QUOTED_RE = re.compile(
r'uv run' + _UV_RUN_FLAGS_RE + r' --project "([^"]+)"'
)
_BAKED_PREFIX_BARE_RE = re.compile(
r"uv run" + _UV_RUN_FLAGS_RE + r" --project (\S+)"
)
#: Placeholder spellings that must never survive into an installed shim.
#: ``{UV_RUN_FLAGS}`` is one of them: a shim's dispatcher renders its ``uv run``
#: flags from :func:`utils.unattended.uv_run_args` rather than spelling them, so a
#: surviving token would be a command that cannot run at all — and a *dropped* one
#: a command that runs without ``--no-dev`` and syncs the dev group.
#: ``{DEFAULT_MODE}`` is another: the rule "no mode flag means ``review-plan``" is
#: rendered from :data:`modes.DEFAULT_MODE`, so a surviving token would leave the
#: model reading a brace where a mode word belongs. ``{NEEDS_HUMAN_RULE}`` is the
#: same shape for the exit-3 decision rule (:data:`modes.NEEDS_HUMAN_RULE`): a
#: surviving token would be a shim that never says what exit 3 means.
FORBIDDEN_IN_INSTALLED: Tuple[str, ...] = (
"{SKILL_DIR}", "${SKILL_DIR}", "$SKILL_DIR", "$ARGUMENTS",
"${CLAUDE_SKILL_DIR}", "{UV_RUN_FLAGS}", "{DEFAULT_MODE}",
"{NEEDS_HUMAN_RULE}",
)
#: The one placeholder that is legal in the one shim nobody renders: the reference
#: host expands ``${CLAUDE_SKILL_DIR}`` inside its own ``SKILL.md`` at load time
#: (D1b), so for an ``installable: false`` entry it is a binding, not a leftover.
_HOST_EXPANDED_PLACEHOLDER = "${CLAUDE_SKILL_DIR}"
#: Where the single-sourced uv install message lives, relative to the skill root.
UV_MISSING_RELATIVE = os.path.join("hosts", "uv-missing.txt")
#: Where the shared shim partials live, relative to the skill root.
SNIPPET_DIR = os.path.join("hosts", "snippets")
#: How many times a snippet may expand another snippet before we call it a loop.
_MAX_SNIPPET_DEPTH = 4
# ---------------------------------------------------------------------------
# Rendering
# ---------------------------------------------------------------------------
#: The codex plugin skill's ``description:`` budget, in characters (D3e). **A
#: budget this project chose, not a limit codex enforces**: codex shortens or
#: drops skill descriptions under a skills-context budget it never prints (R42),
#: shared with every other installed plugin. Calibrated against the sibling
#: route — the opencode plugin command's description is ~300 characters, the
#: core skill's ~650 — so the codex text has room to differ without room to
#: grow toward the one it competes with. Binds the *skill* description only;
#: the MCP tool description is under no skills budget. If a capture ever
#: measures a real ceiling, this moves and every row citing it moves with it.
PLUGIN_SKILL_DESCRIPTION_MAX = 400
def template_path(host_id: str, base: Optional[str] = None) -> Path:
entry = caps.entry(host_id, base)
template = entry["shim"]["template"]
root = Path(str(base) if base else str(skill_dir()))
if not template:
raise Refused(
f"ERROR: host '{host_id}' has no shim template.\n"
f" Its entry sets shim.template: null, which is how the data "
"records a host whose shim is the plugin's own SKILL.md. "
f"`install-host {host_id}` is --check-only."
)
return root / template
def snippets(base: Optional[str] = None) -> Dict[str, str]:
"""The shared shim partials, keyed by the slot spelling they fill.
``hosts/snippets/poll-loop.md`` fills ``{{poll_loop}}``. They are host
independent by construction (a test asserts it), interpolated here rather than
referenced, because a shim may not send an agent off to open a second file.
"""
root = Path(str(base) if base else str(skill_dir())) / SNIPPET_DIR
found: Dict[str, str] = {}
if not root.is_dir():
return found
for path in sorted(root.glob("*.md")):
slot = "{{" + path.stem.replace("-", "_") + "}}"
found[slot] = path.read_text(encoding="utf-8")
return found
def render(
host_id: str,
*,
base: Optional[str] = None,
skill: Optional[str] = None,
template: Optional[str] = None,
) -> str:
"""The shim as an agent will read it — every slot filled, no header yet.
*base* is the root the capability data, the template and the snippets are read
from; *skill* is the absolute prefix baked into the result, defaulting to
*base*. They differ only in tests, which render the shipped templates against a
fixture skill dir containing a space while still reading the real data. At run
time both are the running skill dir: ``os.path.abspath``, symlinks preserved
(D1c). *template* renders text the caller already has, which is how the
shipped-shim CI guard renders a file (including the one shim that has no
template) through this exact function instead of a second implementation.
"""
root = str(base) if base else str(skill_dir())
prefix = str(skill) if skill else root
text = template if template is not None else template_path(
host_id, base
).read_text(encoding="utf-8")
# Snippets first: a partial may itself carry the uv-message slot.
partials = snippets(base)
for _ in range(_MAX_SNIPPET_DEPTH):
replaced = text
for slot, body in partials.items():
replaced = replaced.replace(slot, body)
if replaced == text:
break
text = replaced
for verb, slot in caps.VERB_SLOTS.items():
text = text.replace(slot, caps.verb_sentence(host_id, verb, base))
source = Path(root) / UV_MISSING_RELATIVE
text = text.replace(
SLOT_UV_MISSING_TEXT,
source.read_text(encoding="utf-8").rstrip("\n")
if source.is_file() else uv_missing_text(root),
)
# The *baked* path, so a shim that prints the message names the file where the
# skill actually is rather than where it was read from.
text = text.replace(
SLOT_UV_MISSING_FILE, str(Path(prefix) / UV_MISSING_RELATIVE)
)
text = render_instruction_text(text, prefix)
if not text.endswith("\n"):
text += "\n"
return text
def baked_prefix(text: str) -> Optional[str]:
"""The absolute skill dir a shim was rendered against, or ``None``.
Read back out of the one place every shim carries it: the invariant
``uv run [flags…] --project "<abs>"`` prefix. Quoted, so a path with spaces
survives — and native Windows form, because it was computed inside a Python
process (never an MSYS ``/c/…`` path a native Python cannot open). The flags
are matched as a group rather than skipped over, because they are rendered
from :func:`utils.unattended.uv_run_args` and a shim may legitimately carry a
different list than the one this process would render today.
"""
match = _BAKED_PREFIX_QUOTED_RE.search(text)
if match:
return match.group(1)
match = _BAKED_PREFIX_BARE_RE.search(text)
return match.group(1) if match else None
# ---------------------------------------------------------------------------
# The multi_llm_shim header
# ---------------------------------------------------------------------------
def _sha256(text: str) -> str:
return hashlib.sha256(text.encode("utf-8")).hexdigest()
def body_of(text: str) -> str:
"""*text* with its header line removed — what the body hash is taken over.
The header records the hash of the bytes as written, so it cannot include
itself. Removing exactly the one line it occupies restores the rendered body
byte-for-byte, which is what makes the re-hash on re-install meaningful.
"""
lines = text.splitlines(keepends=True)
kept = [line for line in lines if not _HEADER_RE.match(line)]
return "".join(kept)
def parse_header(text: str) -> Optional[Dict[str, object]]:
"""The ``multi_llm_shim`` block, or ``None`` for a file that is not ours."""
match = _HEADER_RE.search(text)
if not match:
return None
try:
payload = json.loads(match.group(1))
except ValueError:
return None
return payload if isinstance(payload, dict) else None
def _header_line(host_id: str, entry: Dict[str, object], payload: Dict[str, object]) -> str:
fmt = str(entry["shim"]["format"])
opener, closer = _HEADER_SYNTAX.get(fmt, _HEADER_SYNTAX["markdown"])
body = json.dumps(payload, sort_keys=True, separators=(", ", ": "))
note = (
f"{HEADER_KEY}: {body} — rendered by `multi_llm.py install-host "
f"{host_id}`; edit the template in the skill, never this file, and re-run "
"install-host after a plugin update."
)
return f"{opener}{note}{closer}\n"
def with_header(text: str, host_id: str, *, base: Optional[str] = None) -> str:
"""Insert the identifying header into a rendered body.
Placed **after** the frontmatter when the host requires one: a leading comment
before the opening ``---`` stops the host parsing the frontmatter at all.
"""
entry = caps.entry(host_id, base)
payload = {
"host": host_id,
"shim_version": SHIM_VERSION,
"template_sha256": _template_sha(host_id, base),
"body_sha256": _sha256(text),
}
line = _header_line(host_id, entry, payload)
lines = text.splitlines(keepends=True)
if lines and lines[0].strip() == "---":
for index in range(1, len(lines)):
if lines[index].strip() == "---":
return "".join(lines[: index + 1]) + line + "".join(
lines[index + 1:]
)
return line + text
def _template_sha(host_id: str, base: Optional[str] = None) -> str:
entry = caps.entry(host_id, base)
if not entry["shim"]["template"]:
return ""
return _sha256(template_path(host_id, base).read_text(encoding="utf-8"))
def render_installed(host_id: str, *, base: Optional[str] = None) -> str:
"""The exact bytes ``install-host`` writes: rendered body plus header."""
return with_header(render(host_id, base=base), host_id, base=base)
def local_edit(text: str) -> bool:
"""True when the file on disk no longer matches its own recorded body hash."""
header = parse_header(text)
if not header:
return False
return header.get("body_sha256") != _sha256(body_of(text))
def _is_pristine_shim(text: str) -> bool:
"""A shim of ours, byte-for-byte as it was written."""
return parse_header(text) is not None and not local_edit(text)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |