LLM 外部化代码扫描与修复插件

llm-externalizer

Offload expensive code-scan work to cheap LLMs. Keep the fix loop local in Claude Code.

What it does

This plugin helps you review a codebase with a cheap model, and then fix the findings with your normal Claude Code session.

The work splits in two halves:

• The scan — reading your files and listing what looks wrong (bugs, spec violations, duplicate code, broken imports). This half is sent to an inexpensive model of your choice: a free remote one, a paid remote ensemble of three models, or a local model running on your own machine.
• The fix — actually editing the code to resolve each finding. This half stays inside Claude Code and is done by Claude Sonnet or Opus, so you keep the same review-and-approve flow you already use for any edit.

Keeping the fix half local means the expensive model only touches code when it actually needs to. The scan half does all the slow reading work on the cheap side.

_{Scan target: ~38 KLOC TypeScript repo. Per-run cost on OpenRouter — measured 2026-05.}

Table of contents

• How it works
• Features
• Requirements
• Install
• First run
• Plugin commands (/llm-externalizer:* — what you type in Claude Code)
• CLI commands (direct llm-ext <command> calls — for skills, custom agents, scripts)
• Agents (internal, dispatched by commands)
• Breaking changes in 14.1.0
• Configuration
• Troubleshooting
• Plugin structure
• Contributing
• License

How it works

┌─────────────────────────────────────────────────────────────────────────┐
│  YOUR CLAUDE CODE SESSION (local — Sonnet / Opus / Haiku)               │
│                                                                         │
│   /llm-externalizer:llm-externalizer-scan-and-fix                       │
│        │                                                                │
│        │  1. auto-discover codebase via git ls-files                    │
│        │  2. run "llm-ext scan-folder" or "llm-ext code-task"  ─┐       │
│        │                                                        │       │
│        │                                                        ▼       │
│        │           ┌─────────────────────────────────────────────────┐  │
│        │           │  BUNDLED CLI ENGINE (llm-ext, in the plugin)    │  │
│        │           │                                                 │  │
│        │           │  FFD-batches files into ~400 KB payloads        │  │
│        │           │  Streams each batch to the configured backend:  │  │
│        │           │    • OpenRouter ensemble (3 models in parallel) │  │
│        │           │    • OpenRouter single model                    │  │
│        │           │    • LM Studio / Ollama / vLLM / llama.cpp      │  │
│        │           │    • Nemotron free tier                         │  │
│        │           │                                                 │  │
│        │           │  Writes per-file / per-group / merged reports   │  │
│        │           │  to ./reports/llm-externalizer/*.md             │  │
│        │           └─────────────────────────────────────────────────┘  │
│        │                                                        │       │
│        │  3. receive report paths (only paths — never bodies)   │       │
│        │  4. dispatch FIXER SUBAGENTS (local Claude Sonnet/Opus)        │
│        │       • parallel: up to 15 concurrent, one per report          │
│        │       • serial:   one bug at a time from an aggregated list    │
│        │       • dispatch returns an agent id, NOT the fixer's answer;  │
│        │         each fixer runs in the background and reports back     │
│        │         in its own completion notification                     │
│        │                                                                │
│        │     EACH FIXER subagent:                                       │
│        │       a. reads ONE report from disk                            │
│        │       b. verifies every finding against the real source        │
│        │       c. rejects false positives / hallucinations              │
│        │       d. applies a minimal Edit only on REAL defects           │
│        │       e. runs the language linter, re-verifies                 │
│        │       f. writes a .fixer.*.md summary                          │
│        │                                                                │
│        │  4b. AWAIT every fixer's completion notification               │
│        │  5. join-script merges all fixer summaries into one report     │
└─────────────────────────────────────────────────────────────────────────┘

One-line summary. The llm-ext CLI is the scan engine; your Claude Code session is the fix engine. Only file paths cross the boundary — the orchestrator context never reads a report body.

Features

• Interactive setup wizard (/llm-externalizer:llm-externalizer-setup, since v9.6.0) — detects your platform (OS, arch, RAM, GPU), finds installed runners (Ollama, LM Studio, vLLM, llama.cpp, Jan), helps download a Hugging Face model with the hf CLI, runs five calibrated compatibility tests on the chosen model, and emits a paste-ready settings.yaml profile snippet via a stdlib-only generator (scripts/setup/build-snippet.py). The wizard NEVER writes to your settings.yaml — user-only-configuration policy.
• Scan externalization — 50 CLI commands for code review, duplicate hunting, import/reference validation, spec-compliance checks, bulk LLM-driven structured-output extraction (mass-scouting), full-sentence meaning-equivalence clustering (cluster-synonyms), size-bounded summarization (summarize), topic/keyword extraction (topics), semantic phrase deduplication (sem-deduplicate), concise file characterization (describe), injection-hardened security triage (security-scan), a $0 delegate mode (review-plan) where the host agent reviews with its own model, layered per-path review rules (rules-check debugs which rule fires), and diff-mode scoping on every review tool (--diff_workspace, --diff_from/--diff_to, --diff_commit — git-delegated, hunks carry enclosing-function context), all backed by a local or remote LLM you choose.
• Dry-run everything before paying — --estimate predicts a run's cost (expected + hard ceiling, self-calibrating from recorded usage) and --preview lists exactly which files would be scanned and WHY each exclusion happened; both compose, both send nothing.
• Fix loop stays local — fixes are applied by your Claude Code Sonnet / Opus session, NOT by the external LLM. You get the ensemble's second opinion without giving up editorial control.
• False-positive-aware fixers — every fixer subagent runs a verification pass (file-read + flow-trace) before editing. Empirically ~15–30% of ensemble findings are false positives; the fixer rejects them with a typed reason.
• 25 plugin commands — 23 base (setup, discover, reset, configure, change-model, install-statusline, update-all, benchmark, bench-free-pool, assess-model, check-model-health, discover-new-models, security-triage-benchmark, search-existing-benchmark, auto-replace, search-existing-implementations, cluster-synonyms, scan-and-fix, scan-and-fix-serially, fix-report, fix-found-bugs, high-quality-scan, high-quality-scan-and-fix) + 1 mass-scout dispatcher (mass-scout — all 16 pipeline actions via an action word, e.g. /llm-externalizer:llm-externalizer-mass-scout search …; the per-action mass-scout-* slash commands were removed in v13.5.9, the llm-ext mass-scout-* CLI subcommands are unchanged) + 1 dedicated security tool (security-scan). Full list in Plugin commands. Note: /llm-externalizer:llm-externalizer-change-model is a user-only redirect — it shows your current config (discover/get-settings) and guides you to edit ~/.llm-externalizer/settings.yaml by hand, then reload via reset. There is no change-model or set-settings CLI command (the CLI is read-only by design). Model / profile changes always go through editing ~/.llm-externalizer/settings.yaml (or running the setup wizard above).
• 50 CLI commands — 27 core/utility (chat, code-task, scan-folder, high-quality-scan, compare-files, check-references, check-imports, check-against-specs, search-existing-implementations, cluster-synonyms, summarize, topics, sem-deduplicate, describe, batch-check, review-plan, rules-check, discover, reset, get-settings, profile, list-profiles, session-summary, scan-local-llm-services, or-model-info, or-model-info-table, or-model-info-json) + 16 mass-scout (mass-scout-register, mass-scout-preclassify, mass-scout-estimate, mass-scout, mass-scout-search, mass-scout-search-xjob, mass-scout-get, mass-scout-export, mass-scout-jobs-list, mass-scout-audit-sample, mass-scout-body-get, mass-scout-build-fieldset, mass-scout-propose-fieldset, mass-scout-list-bundled-fieldsets, mass-scout-diff, mass-scout-chain) + 7 security / model-qualification (security-scan, security-triage-benchmark, search-existing-benchmark, assess-model, check-model-health, discover-new-models, check-tool-replacements). The CLI is read-only by design — there are no set-settings, change-model, fix-code, batch-fix, merge-files, split-file, revert-file, or custom-prompt commands (configuration is user-only; custom_prompt was merged into chat). The max_retries: 3 parameter on per-file commands (chat/code-task/scan-folder) replaces the older batch-check workflow (parallel execution + exponential backoff + circuit breaker); batch-check itself is DEPRECATED.
• 6 internal agents — setup wizard + reviewer + 4 fixer variants (parallel/serial × Sonnet/Opus). The setup-agent ships with five preloaded Hugging Face helper skills (huggingface-best, huggingface-local-models, huggingface-mlx-models, hf-cli, huggingface-community-evals) — all marked user-invocable: false. See Agents.
• 3 backend modes — local (sequential), remote (parallel, single model), remote-ensemble (parallel, three models → combined report).
• 7 backend presets — LM Studio, Ollama, vLLM, llama.cpp, generic local, OpenRouter, chat.b.ai.
• Auto-batching — First-Fit-Decreasing bin-packing packs 1–5 files per LLM request (~400 KB per batch). The LLM never sees the whole codebase at once.
• File grouping — ---GROUP:<id>--- markers in a file list pack related files into one request and produce one report per group.
• Secret handling — every file is run through the pre-scan secret detector (scan_secrets: true) before it leaves your machine, and any hit is rewritten to [REDACTED:LABEL] (redact_secrets: true) so the scan still completes on partially-dirty inputs. The detector's SECRET_PATTERNS set now includes wildcard variants for the common API-key shapes (sk-…, gho_…, aws_…, etc.) and prefix-bearing tokens, so accidental leaks via .env, fixtures, or stale comments are caught and silently masked instead of being shipped to the remote LLM. Opt out per run with --no-secrets only after you have moved secrets to a gitignored .env.
• File-based output — every report lands in ./reports/llm-externalizer/. Only paths flow through the orchestrator context (≤ 200 bytes per report).
• Cross-platform — macOS, Linux, Windows. llm-ext is a bundled Node executable; the helper scripts are pure Python 3.12+.

Requirements

These are the user requirements for installing from the marketplace. Additional tools for building from source are listed under Contributing → Developer requirements.

Install

Every step below is a single pasteable block. Run them in your terminal — not inside a Claude Code session.

1 · Add the marketplace

# Add the marketplace that hosts this plugin
claude plugin marketplace add Emasoft/emasoft-plugins

# Add the marketplace that hosts this plugin
claude plugin marketplace add Emasoft/emasoft-plugins

2 · Install the plugin

# Install llm-externalizer from the Emasoft marketplace
claude plugin install llm-externalizer@emasoft-plugins

Claude Code 2.1.221+ activates a newly installed plugin immediately when it is safe to do so, and 2.1.232 refreshes the marketplace as part of the install — so neither a restart nor a manual marketplace update is normally required. If the commands do not show up, /reload-plugins.

3 · (Later) Update the plugin

# Pull the newest version published in the marketplace
claude plugin update llm-externalizer@emasoft-plugins

4 · (Optional) Uninstall

# Remove the plugin
claude plugin uninstall llm-externalizer@emasoft-plugins

Install from inside Claude Code

If you prefer conversational install, paste this repo URL in Claude and ask it to install the plugin:

https://github.com/Emasoft/llm-externalizer-plugin

Global llm-ext command

Claude Code puts a plugin's bin/ on PATH only inside its own sessions, so llm-ext in a plain terminal would otherwise be "command not found". A SessionStart hook (matcher startup|resume) installs or refreshes a small POSIX-sh wrapper at ~/.local/bin/llm-ext every time a Claude Code session starts or resumes. The wrapper resolves the real CLI at run time — first the current session's own plugin bin/ if one is on PATH, otherwise the user-scope install path Claude Code recorded in installed_plugins.json — so it keeps working across plugin updates without going stale like a symlink into a version-specific cache dir would.

• Opt out: set LLM_EXT_NO_PATH_SHIM=1 — either in the env block of ~/.claude/settings.json, or exported in your shell before starting Claude Code — to turn the hook off entirely.
• Uninstalling the plugin does not remove ~/.local/bin/llm-ext. It fails loudly instead rather than silently doing nothing: with no user-scope record left, the wrapper exits with expected exactly one user-scope llm-externalizer install … found 0 (of 0 …); delete ~/.local/bin/llm-ext by hand once you've uninstalled.
• Project-scope-only installs make the wrapper fail outside a Claude Code session, since there is no user-scope record to fall back to (llm-ext: expected exactly one user-scope llm-externalizer install … found 0 (of N …)).
• Two plugin versions installed (e.g. during an upgrade) may each rewrite ~/.local/bin/llm-ext in turn — harmless, since the wrapper always resolves the current install path at run time rather than baking one in.
• Native Windows (cmd.exe/PowerShell) is skipped — an sh script in ~/.local/bin isn't runnable there.

First run

0 · Run the setup wizard (recommended)

The fastest path is the bundled interactive wizard:

/llm-externalizer:llm-externalizer-setup

The wizard inspects your platform (OS, arch, RAM, GPU), looks for installed local-model runners (Ollama, LM Studio, vLLM, llama.cpp, Jan), helps you install one if none is present, downloads a Hugging Face model via the hf CLI (installing it on demand), runs five calibrated compatibility tests (smoke / structured output / code understanding / long context / output length), and finishes by printing a ready-to-paste settings.yaml profile snippet generated by scripts/setup/build-snippet.py. The wizard never writes to your settings.yaml — it stays user-only by policy. On Apple Silicon the wizard cross-links the vllm-metal-setup and vmlx-setup skills for MLX-native serving paths.

Manual options A–D below remain fully supported for users who want explicit control over which backend, model, and profile structure to use. Pick one of them if you already know your stack, or skip back here for the wizard if anything goes wrong. For the complete manual path — settings.yaml schema, the per-platform / per-GPU backend matrix, model sizing, and troubleshooting — see docs/setup-and-configuration.md.

1 · Configure a backend

Pick one of the following backends. The four most common are below; vLLM and llama.cpp follow the same shape — see Configuration → E. Local — vLLM or llama.cpp.

# Put this in ~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish
export OPENROUTER_API_KEY="sk-or-v1-..."

# Persist for your user account (survives reboot and new terminals)
[Environment]::SetEnvironmentVariable("OPENROUTER_API_KEY", "sk-or-v1-...", "User")

setx OPENROUTER_API_KEY "sk-or-v1-..."

profiles:
  my-paid-profile:
    mode: remote-ensemble
    api: openrouter-remote
    api_key: sk-or-v1-...        # literal — do NOT commit this file
    # api_key: $MY_CUSTOM_VAR    # or a different env-var name

# Opens an interactive TUI; paste the key when prompted
claude plugin configure llm-externalizer

allow_paid_models: false      # ← DEFAULT (absent ⟺ false). Zero paid spend.
profiles:
  # ... your profiles, paid models and all ...

# pass --profile my-free-only-profile on the call
profiles:
  my-free-only-profile:
    mode: remote-ensemble
    api: openrouter-remote
    free_only: true
    api_key: $OPENROUTER_API_KEY     # free models still need the key (rate-limited, but $0)
    free_models:
      - "deepseek/deepseek-v4-flash:free"
      - "qwen/qwen3-next-80b-a3b-instruct:free"
      - "openai/gpt-oss-120b:free"
      - "z-ai/glm-4.5-air:free"
      - "meta-llama/llama-3.3-70b-instruct:free"
      - "nvidia/nemotron-3-super-120b-a12b:free"

security_triage_benchmark   models: ["deepseek/deepseek-v4-flash:free", "openai/gpt-oss-120b:free", ...]

# One-time: pull the model weights (~17 GB for Qwen3.5 27B at Q4_K_M / 4-bit MLX)
ollama pull qwen3.5:27b

# Start Ollama (or launch the tray app)
ollama serve

2 · Verify health

Inside Claude Code:

/llm-externalizer:llm-externalizer-discover

You should see your active profile, model ID, auth status, and ONLINE.

3 · Run your first scan + fix

/llm-externalizer:llm-externalizer-scan-and-fix

The command will auto-discover your codebase, present the file list for confirmation, run the scan, then dispatch local Claude fixer subagents that verify each finding before editing.

Plugin commands

Commands are slash-invoked inside Claude Code. The format is /llm-externalizer:llm-externalizer-<name>.

Base commands (18)

Mass-scout (one dispatcher command, 16 actions)

Since v13.5.9 the whole family lives behind ONE slash command: /llm-externalizer:llm-externalizer-mass-scout <action> [flags] (bare = the end-to-end scout run). The 15 per-action slash commands (…-mass-scout-register, …-mass-scout-search, …) were removed to unclutter the command menu; every bin/llm-ext mass-scout-<action> CLI subcommand is unchanged. Note the hyphen: the CLI takes mass-scout-search, never mass-scout search (the spaced form silently drops the action word).

Bundled fieldsets shipped with the plugin: code-audit, skill-audit, security-audit, pr-review (pass as --fields-file bundled:<name>). The CLI also exposes every tool as bin/llm-ext mass-scout-<subcommand> — see --help for the full flag list.

CLI commands

These are direct llm-ext calls — run as llm-ext <command> [--flag value ...] (or "$CLAUDE_PLUGIN_ROOT/bin/llm-ext" <command> ... from a skill/agent/script). End users typically don't call these directly; they use the slash commands above. Commands are listed here for advanced users writing custom workflows.

In-depth docs (docs/, on-demand companions to the lean always-loaded rules/use-llm-externalizer.md):

• agent-usage-reference.md — full operational reference: per-tool tables, the batching model, the answer_mode explanation, the profile/auth/tool_models workflow, usage patterns, safety, constraints.
• tool-use-cases.md — "which tool for which goal?" decision guide; when to pick each tool and what to use instead.
• setup-and-configuration.md — setup wizard + manual config, the settings.yaml schema, and the per-platform / per-GPU backend matrix (local & remote).

Analysis tools

Mass-scouting tools (16)

The base 8-tool pipeline plus 8 follow-on tools for fieldset authoring, job introspection, and job-to-job operations.

The CLI exposes every sub-command as its own hyphenated command, bin/llm-ext mass-scout-<subcommand> (e.g. bin/llm-ext mass-scout-register) — NOT mass-scout <subcommand> with a space; the latter fails fast with unexpected argument '<subcommand>' (all inputs are named flags) and exits 1. The grouped spelling bin/llm-ext scout <action> (e.g. scout register) works too. On the slash-command side, the single /llm-externalizer:llm-externalizer-mass-scout dispatcher covers all 16 actions (it folds the action word into the hyphenated CLI subcommand for you). The llm-externalizer-mass-scouting skill walks through the full pipeline including the bundled fieldsets, troubleshooting flowchart, and worked example.

Security tools

Utility tools

session_summary — Claude-Code-compaction-equivalent, $0 by construction

Why it exists: Claude Code's own /compact burns paid-model tokens summarizing a session and runs only inside that same session. session_summary reproduces the same compaction-equivalent output — for any session, from its .jsonl transcript, from a fresh agent that never held that context — and does it entirely on free OpenRouter models, so compacting an arbitrarily long session costs $0.

Pipeline: stream the transcript (never loaded fully into memory) → extract real context (user turns, assistant text/thinking/tool_use, tool results) while dropping JSONL bookkeeping → prune (--prune aggressive|moderate|none, default aggressive — drops tool-result payloads, pasted file contents, thinking blocks; keeps user/assistant prose, tool names + arg summaries, errors) → pack into token-budgeted chunks, splitting only between turns, never mid-turn (capped at 50,000 tokens by default, regardless of how large the selected model's own context window is — quality collapses long before the context LIMIT is reached, especially on free models; override with --max-chunk-tokens) → map (summarize each chunk against a fixed nine-section compaction schema) → reduce (deterministically join the chunk summaries in code — no second LLM pass, so no fact can be dropped in the merge; recurses when a fold itself overflows the window). Every chunk/fold is checkpointed, so an interrupted run (e.g. a free daily-quota hit) resumes automatically on re-run.

What gets captured / dropped from the transcript:

• Messages sent mid-turn (stored by Claude Code as type: "queue-operation", not type: "user") are captured as real user content.
• Machine-injected turns are excluded: janitor-heartbeat cron fires, no-visible-output nudges, system-reminder-only turns, slash-command plumbing, task notifications, skill-doc loads.
• Embedded images (base64 / data: URIs) are dropped at every prune level, leaving an [image omitted] marker — a text-only model can't read them, and leaving them in would evict real content from the chunk budget for nothing.

The nine-section schema each chunk is summarized against (verbatim in the merged report): Primary Request and Intent · Key Technical Concepts · Files and Code Sections · Errors and Fixes · Problem Solving · All User Messages (verbatim — the only section that copies transcript text) · Pending Tasks · Current Work · Next Step.

Cost safety is structural, not a flag: it only ever selects a free OpenRouter model that has text on both sides of its architecture.modality (extra modalities on either side — image, audio, video — are irrelevant and never disqualify). There is no hard context floor by default — it always picks the BIGGEST such model available today, whatever that is; pass --min-context to require a hard floor instead (fails if nothing clears it). If the picked model is delisted, stops being free, exhausts its daily cap, returns an empty/no-text response, or echoes its input back verbatim instead of summarizing it, mid-run, the run falls back automatically to the next-biggest eligible model and re-chunks the remaining (unsent) work to its context — already-checkpointed chunk/fold summaries are untouched. If every eligible model is exhausted this way, the command exits non-zero rather than reporting a false success. The kebab-case spelling of a catalog command name is supported, not deprecated: session-summary is the supported CLI spelling of session_summary.

Checkpoint durability. Each checkpoint is written to a sibling temporary file, then renamed into place. Process termination leaves the previous complete checkpoint or the new one, possibly with a leftover temporary file; before the first successful checkpoint there is no previous checkpoint to resume. No fsync is performed, so this does not guarantee durability across a machine crash or power loss.

Caller time bounds. --chunk-timeout-s (--chunk_timeout_s) limits each attempt, not total runtime. The observed 91–1478 seconds per chunk on v13.5.0 is historical evidence, not a current latency guarantee. A caller needing a total-time bound must enforce an external deadline that ends the process, especially with --until-done (--until_done), which retries whole compactions. Resuming still requires the checkpoint and transcript to pass the command’s normal validation; a bound too short to finish a chunk can repeatedly discard its progress.

What it reports. Alongside the model, chunk count and prune ratio, the command prints the outcome — how much smaller the summary is than the transcript it replaces — to stderr and embeds the same line in the report header:

Size: 2.08 MB (2,179,678 B) transcript → 13.9 KB (14,242 B) summary — 99.35% reduction; pruned to 812 KB before summarizing

Exact byte counts sit beside the human-readable sizes deliberately: the human form is what you read, the raw number is what you compare across runs. A summary that came out larger than its transcript is reported as such rather than rounded to 0%.

When the summary must exist no matter what. By default this command is checkpoint-and-stop: a chunk gets its retry budget, a dead or quota-capped model is demoted to the next ranked free one, and when those run out the command fails and tells you to re-run. Use --until-done for unattended runs; wrap it in until llm-ext session-summary …; do sleep 60; done as well if the process itself might be killed. Both converge for the same reason — the checkpoint makes every pass keep the work that already landed.

Worked examples:

# (a) Summarize the current project's most recent session — no
#     flags needed, resolves the transcript automatically. Writes a report
#     under reports/llm-externalizer/ and prints its path.
llm-ext session-summary

# (b) Summarize one specific transcript and print the summary text directly
#     (e.g. to pipe into another tool), instead of writing a report file.
llm-ext session-summary \
  --transcript ~/.claude/projects/-Users-me-Code-myproj/3f9c1a2b-....jsonl \
  --stdout

# (c) Resume an interrupted run (e.g. hit a free-model daily quota mid-run) —
#     `--resume` fails fast instead of silently starting over if no matching
#     checkpoint exists yet at the default checkpoint path.
llm-ext session-summary --transcript /path/to/session.jsonl --resume

# (d) Unattended: must produce a summary eventually. Retries the whole
#     compaction, resuming from the checkpoint each pass, and waits for the
#     00:00 UTC reset when the failure is an exhausted daily quota.
llm-ext session-summary --until-done --max-retries-per-chunk 10

Verified: llm-ext session-summary --resume (no transcript, no checkpoint) fails fast with FAILED: session-summary: no transcript directory for this project ...; llm-ext session-summary --transcript /tmp/does-not-exist.jsonl --stdout fails fast with FAILED: session-summary: --transcript path does not exist: ... — both confirm the flags parse and the fail-fast paths work without spending any free-tier quota.

Model-qualification tools

Per-tool model selection (TRDD-f45eeaa0): each LLM tool declares its own requirements + (optionally) a benchmark; a model serves a tool only if it meets the requirements and passes that tool's benchmark. See Configuration § F. Per-tool model overrides.

answer_mode (every multi-file analysis tool)

Defaults. scan_folder → 0. chat / code_task / check_* / search_existing_implementations → 2.

[!IMPORTANT] Batching. Every multi-file tool packs files into LLM requests of 1–5 files each (~400 KB per batch). The LLM never sees the whole codebase at once — answer_mode controls only how reports are organised on disk. For cross-file analysis, use search_existing_implementations or check_against_specs — their per-batch design actually validates against an authoritative reference.

Advanced parameters (most tools)

Agents

All six agents are internal — users dispatch them via slash commands, not directly. Each Agent spawn is fresh (zero parent-conversation context — which is why the commands never use subagent_type: "fork"); user / project CLAUDE.md load the same way they do under claude -p. The fixer commands show a two-option menu (Sonnet default, Opus optional) before dispatching; the four fixer variants below exist so the selected model is pre-baked and callable without a model: override.

[!NOTE] Every fixer agent runs a MANDATORY verification pass before editing any source file: open the cited line, trace the flow, reject hallucinations / style suggestions / redaction artifacts / already-fixed claims. A no-edit "false-positive" verdict is treated as a SUCCESSFUL outcome.

Breaking changes in 14.1.0

• active: is a real default-profile pointer again. Precedence is --profile <name> > active: <name> in settings.yaml > the built-in free profile. active: may name any profile, dynamic or static. A fresh install writes active: free. A dangling active: value (naming a profile that no longer exists) only errors when it would actually be selected — info commands and an explicit --profile still run.
• Three built-in dynamic profiles: free, paid, local. They are generated and refreshed automatically — free for the latest free OpenRouter models, paid for the latest paid OpenRouter models, local for the llama.cpp / OpenAI-compatible / LM Studio / Ollama endpoints detected on this machine. All other profile names are STATIC, hand-written by the user (see "Built-in dynamic profiles"; the retired former placeholder names are in CHANGELOG.md).
• No cross-profile fallback. On a model failure, llm-ext falls back to the next model of the SAME profile only — dynamic profiles in benchmark-rating order, static profiles in the listed order. It never switches to free, local, or any other profile: "no switching to free models (or local models) must exist anymore. llm-ext must stick to the selected profile in --profile <profile name> (or free profile if omitted). no change of profile must be allowed once the command is executed."
• A STATIC profile no longer auto-falls back to bundled free models. A static profile forced to free mode (allow_paid_models: false) with no free_models and no free-provider route now refuses with a clear error, instead of silently borrowing FREE_POOL_SEED.
• A dynamic profile's ownership boundary is enforced. Inside free/ paid/local, selection and high_quality_model are yours to edit (paid also owns providers) — every other key is now refused instead of silently dropped on the next regeneration (see "Built-in dynamic profiles").
• The paid profile's price ceiling moved. The top-level ensemble_price_ceiling_usd_per_million key is retired — set profiles.paid.selection.price_ceiling_usd_per_million instead (default still $1.3/M, input AND output each <= the ceiling). On first boot after upgrading, llm-ext moves an existing top-level value there for you and deletes the old key; if both are set to different values it leaves the file untouched and refuses every command until you delete the top-level key by hand.

Configuration

The settings file lives at:

• macOS / Linux: ~/.llm-externalizer/settings.yaml
• Windows: %USERPROFILE%\.llm-externalizer\settings.yaml
• WSL2 (Linux side, addressed from Windows): \\wsl$\Ubuntu\home\<user>\.llm-externalizer\settings.yaml

The plugin creates it on first install with three built-in DYNAMIC profiles — free, paid, and local — plus a single active: free line pointing at the default one (see "Built-in dynamic profiles free, paid, and local" below). free costs nothing and populates on first use; paid stays unpopulated until allow_paid_models: true; local populates from whatever compatible endpoint is detected on this machine. Every other profile name is STATIC — used exactly as written, never modified by llm-ext. Edit the file with any text editor, save, then run llm-ext reset to purge the caches (a restart is not required — every CLI call re-reads it fresh anyway).

[!NOTE] The setup wizard uses scripts/setup/build-snippet.py to safely quote settings.yaml values via stdlib-only logic (no PyYAML at this step) so an attacker who controls a model name or env-var reference cannot trigger arbitrary code execution through a malicious YAML constructor. Documented model IDs are also verified against OpenRouter's live /v1/models endpoint by scripts/publish.py as a CI gate on every release.

Built-in dynamic profiles free, paid, and local

Three profile names are DYNAMIC: llm-ext owns their settings.yaml sections (each marked # <-- do not touch, generated by llm-ext -->), re-generates them as soon as a change is detected (new/removed OpenRouter models or repriced ones for free/paid, new or updated local endpoints for local), drops dead or repriced models immediately, benchmarks newcomers in the background, and keeps the best model per command. A hand-written free:/paid:/local: block is backed up once to ~/.llm-externalizer/backups/ (as settings-before-generated-<name>-<ts>.yaml from the pick CLI, or settings-before-regenerate-<name>-<ts>.yaml from the dynamic maintainer), then regenerated. Every other profile name is STATIC — created by hand by the user, used exactly as written, never modified by llm-ext; a failing model in a static profile fails with the provider error and is never silently replaced by a model from outside the profile.

The ownership boundary inside a dynamic profile (14.1.0). llm-ext rewrites only its own GENERATED keys (mode, api, model, free_models, tool_models, etc., one at a time) — it never touches a subsection you add yourself. As of 14.1.0 every dynamic profile's USER-OWNED set includes selection (auto-pick constraints) and high_quality_model; paid additionally owns providers (llm-ext writes no provider bindings of its own onto paid today, so it is yours to hand-edit there — free and local still generate their own providers bindings and refuse a hand-written one). Every owned key survives every regeneration byte for byte, comments and all. Any OTHER key inside a dynamic profile is now refused at load time rather than silently dropped on the next regeneration — rename your own hand-picked profile instead of using free/paid/local if you want to choose every model yourself. The paid profile's auto-pick price ceiling (see next section) now lives inside its selection subsection for exactly this reason: it is yours to set, and llm-ext will never overwrite it.

• free — OpenRouter :free models plus chat.b.ai (glm-5.3-flash, a soft-pinned ensemble slot when $BAI_API_KEY is set). All checks and benchmarks run at $0. This is the profile used whenever both --profile and active: are omitted.
• paid — paid OpenRouter models. Benchmarking new candidates only happens with allow_paid_models: true, and only within paid_benchmark_daily_cap_usd (default 0.50 USD/day; 0 disables paid benchmarking).
• local — the llama.cpp / OpenAI-compatible / LM Studio / Ollama endpoints detected on this machine. Regenerated as soon as a new or updated local endpoint is detected.

Fallback and maintenance. The command's own path never updates or benchmarks: it runs whichever profile was selected, and a parallel detached process checks in the background for changes (new/removed models, changed costs, new/updated local endpoints) and, if any, spawns another detached process to run the update/scan/benchmark so the next command sees the refreshed pool — the current command never waits on it. A command may spawn one background change check for its profile, at most once per minute; a detected change starts one background update, which finishes on its own; no check or update starts without a command. A single lock per profile (free, paid, local) per config directory (the lock file lives under the config directory, so two different LLM_EXT_CONFIG_DIR values get independent singletons) guards its change check and its update/benchmark together, so however many commands run at once, at most one background process per profile is ever doing update/benchmark work (three total, one per profile) — while a profile's benchmark is running, that profile's own change check does not start a second process; other profiles are unaffected. On a model failure, llm-ext falls back to the next model of the SAME profile: for a dynamic profile, benchmark-rating order over the written validated list; for a static profile, the order the user listed. A dynamic profile whose whole validated list has failed starts its update in the background (unless one is already running, or one finished less than 30 minutes ago and the model catalog has not changed since) and exits non-zero at once with "no model of the '' profile is working right now; the profile update is underway in the background and will be finished soon — retry later." The command never waits for the update, and while the profile still has a working model an update runs without any message. When the failure is one an update cannot fix, that error is shown instead and no update starts: every model of paid answered 402 (no credit), or the API key was rejected (401); a failure specific to one file (for example a 413 for a file too large for every model) fails only that file. A static profile whose whole list has failed exits non-zero with "the models in the selected profile are all failing; retry later or change the profile." There is no cross-profile fallback in either case.

Selection. Precedence is --profile <name> > active: <name> in settings.yaml > the built-in free profile. active: is a single line and may name any profile, dynamic or static; a fresh install writes active: free. If active: is missing, the default profile is free. A dangling active: value (naming a profile that does not exist) errors only when it would actually be selected — info commands (llm-ext settings status / settings show) and an explicit --profile still run regardless. llm-ext settings status / settings show print Effective profile: <name> (source: --profile | active | default).

Honest limits — when a dynamic profile cannot serve a call:

"Never fails" means: never fails because a configured model went away, got repriced, or started rejecting calls. It cannot manufacture a model when the provider class itself is down — that is reported plainly, never papered over with a model from outside the profile.

Spend and write bounds live per config directory, not per machine. The paid daily spend cap (paid_benchmark_daily_cap_usd, default 0.50), the 6-hour floor between successful sweeps, the failure cooldown, and the lock over the generated sections are all state under LLM_EXT_CONFIG_DIR — running two config dirs on one machine (or one account) doubles the effective cap, by design. With allow_paid_models: true, any dispatch — even one made with --profile free — can spawn the paid benchmark in the background, bounded by that same cap, floor and cooldown; this is new, observable spend beyond what a --profile paid call by itself would cause. --apply-profile <name> on a non-free_only profile similarly authorizes spend, but only behind allow_paid_models: true and the benchmark's own --allow-paid-models-tests.

profiles.free and profiles.paid each have exactly one writer, the dynamic maintainer: llm-ext-benchmark --apply-free-pool free/paid and update-all --profile free/paid now refuse rather than silently overwrite the generated section — use --populate-default-profile <name> to seed a fresh install's dynamic profile by hand instead. A STATIC free_only profile no longer gets automatic population of benchmark-results.json at boot (the retired background populator used to do that); --bench-free-pool remains the manual path.

Known limitation, not a feature: on a machine with only a chat.b.ai credential (no OpenRouter key), the provisional free pool boots configured when the OpenRouter catalog snapshot is EMPTY. Once a catalog is cached from an earlier run, the pool would mix b.ai and OpenRouter :free ids, so the write is skipped on every dispatch and free never populates on that machine — the gate's own message does not yet name this specific cause.

Profile modes

A. Remote ensemble (recommended)

# ~/.llm-externalizer/settings.yaml   (or %USERPROFILE%\.llm-externalizer\settings.yaml)
# pass --profile remote-ensemble on the call, or set active: remote-ensemble

profiles:
  remote-ensemble:
    mode: remote-ensemble
    api: openrouter-remote
    model:        "google/gemini-2.5-flash"
    second_model: "x-ai/grok-4.1-fast"
    third_model:  "qwen/qwen3.6-plus"
    api_key: $OPENROUTER_API_KEY

Every file is reviewed by all three models in parallel; the report combines their responses. Swap any line to try a different model — see https://openrouter.ai/models.

B. Remote free (Nemotron)

A single call to NVIDIA's free Nemotron tier on OpenRouter. One model, no ensemble, no cost.

# pass --profile remote-free on the call

profiles:
  remote-free:
    mode: remote
    api: openrouter-remote
    model: "nvidia/nemotron-3-super-120b-a12b:free"
    api_key: $OPENROUTER_API_KEY

[!WARNING] The free tier logs your prompts on the provider side. Use this only on open-source code or code you don't mind being logged. For proprietary code, use the ensemble (option A) or a local model (options C / D / E).

C. Local — LM Studio (Qwen 3.5 27B)

# pass --profile local-lmstudio on the call

profiles:
  local-lmstudio:
    mode: local
    api: lmstudio-local
    # Apple Silicon → use the MLX build (much faster than GGUF):
    model: "mlx-community/Qwen3.5-27B-Instruct-4bit"
    # Windows / Linux → use the GGUF build:
    # model: "bartowski/Qwen3.5-27B-Instruct-GGUF"

D. Local — Ollama

# pass --profile local-ollama on the call

profiles:
  local-ollama:
    mode: local
    api: ollama-local
    model: "qwen3.5:27b"
    # Default URL is http://localhost:11434 — override only for remote/custom hosts:
    # url: "http://192.168.1.42:11434"
    # Ollama needs no auth, so api_token is omitted.

Before first use, pull the model:

# One-time — downloads ~17 GB of model weights (Q4_K_M / 4-bit MLX)
ollama pull qwen3.5:27b

E. Local — vLLM or llama.cpp

Same shape as the Ollama block; change the api: preset:

profiles:
  local-vllm:
    mode: local
    api: vllm-local         # default URL: http://localhost:8000 — auth: $VLLM_API_KEY
    model: "Qwen/Qwen3.5-27B-Instruct"

  local-llamacpp:
    mode: local
    api: llamacpp-local     # default URL: http://localhost:8080 — no auth
    model: "Qwen3.5-27B-Instruct"

Set model: to whatever ID your server advertises at its /v1/models endpoint.

F. Per-tool model overrides (advanced)

Every LLM-using tool normally runs on the active profile's model. You can override the model per tool with an optional tool_models: map on a profile. This lets one backend serve, say, security_scan with a cheap small model while code_task uses a stronger one — without juggling multiple active profiles.

profiles:
  remote-ensemble:
    mode: remote-ensemble
    api: openrouter-remote
    model:        "google/gemini-2.5-flash"
    second_model: "x-ai/grok-4.1-fast"
    third_model:  "qwen/qwen3.6-plus"
    api_key: $OPENROUTER_API_KEY
    tool_models:                       # optional — absent ⇒ this profile's `model`
      security_scan: "qwen/qwen-2.5-7b-instruct"
      code_task:     "google/gemini-2.5-flash"

Resolution order for a given tool (first match wins):

1. an explicit model passed in the tool call (e.g. security_scan's model arg);
2. tool_models.<tool> on the active profile;
3. the tool's own built-in default (e.g. security_scan → qwen/qwen-2.5-7b-instruct);
4. otherwise the profile's model.

So a profile with no tool_models behaves exactly as before — this is fully back-compatible. Keys must be real LLM-tool names (the loader rejects typos like securty_scan); values are model ids your backend advertises.

Vet a model before you assign it. Each tool declares its own requirements (cost ceiling, context, output, structured-output / reasoning support), and some tools additionally gate selection on a benchmark. Two helpers:

# Which tools can a model serve (requirements only — free, no LLM call, no API key)?
llm-ext-benchmark --assess-model google/gemini-2.5-flash
#   …or the slash command:  /llm-externalizer:llm-externalizer-assess-model

# For a benchmarked tool (today: security_scan), confirm it actually PASSES:
llm-ext-benchmark --security-triage --model google/gemini-2.5-flash
#   …or:  /llm-externalizer:llm-externalizer-security-triage-benchmark

A model you put in tool_models.<tool> for a benchmarked tool should pass that tool's benchmark first. The standing rule holds throughout: the auto-selection gates never bump a tool to a pricier model than its incumbent.

[!NOTE] Today exactly one tool (security_scan) ships a model-judgment benchmark (security-triage); mass_scout reuses the keyword-classification benchmark. The other tools are gated by requirements only until their golden dataset lands — --assess-model shows, per tool, whether a benchmark gate also applies.

Backend presets

Environment variables

[!NOTE] The shell environment variable is the recommended way to provide every key listed above. The statusline subprocess and every llm-ext invocation inherit it automatically, with no extra plumbing. Profile-level api_key / api_token fields are a supported fallback (read from settings.yaml). The Claude Code keychain (userConfig.openrouter_api_key) is not a reliable fallback — see First run § A. OpenRouter for why. See that same section for the full precedence list and the trade-offs.

Optional: statusline

Adds a multi-tier status bar with: model name, context-window bar, live OpenRouter credit balance, LLM tokens & cost, git branch, and Claude Code 5-hour / 7-day usage limits. Width-aware (1 line at ≥ 184 cols → 6 lines under 65 cols), per-section error isolation, no external dependencies.

Easiest way — invoke the bundled slash command from inside Claude Code:

/llm-externalizer:llm-externalizer-install-statusline

Manual install (cross-platform Python):

# Default 3-second refresh cadence (re-tiers within 3 s of a terminal resize)
python3 "$CLAUDE_PLUGIN_ROOT/scripts/install_statusline.py"

# Or override the refresh cadence
REFRESH_INTERVAL=5 python3 "$CLAUDE_PLUGIN_ROOT/scripts/install_statusline.py"

# Bash-only equivalent (same behaviour, identical settings.json output)
bash "$CLAUDE_PLUGIN_ROOT/scripts/statusline/install.sh"

python3 "$env:CLAUDE_PLUGIN_ROOT\scripts\install_statusline.py"

[!NOTE] The OpenRouter remaining-credit panel (🏦) only renders when OPENROUTER_API_KEY is exported in your shell environment. The statusline runs as a fresh subprocess on every refresh, so the plugin's keychain (userConfig.openrouter_api_key) and the per-profile api_key field in settings.yaml are not visible to it — see First run § A. OpenRouter for why the shell env is the only way to get every consumer (statusline, llm-ext) to share the same key.

See scripts/statusline/README.md for the full feature matrix and width-tiering details.

Usage history

Every LLM web request the plugin makes — from any llm-ext command — appends one flat, human-readable line to ~/.llm-externalizer/history.log (honors LLM_EXT_CONFIG_DIR; the file is created on first write, append-only, never truncated). One line per web request — a tool that makes several backend calls writes several lines, and a tool that makes none writes nothing. The log is for eyeballing and grep; the plugin ships no query/aggregation command for it.

Each line has 7 --separated fields:

<TIMESTAMP> - <PROJECT-DIR> - <TOOL/COMMAND(params)> - <SUCCESS|FAIL> - <DURATION> - <COST> - <OP-ID>

• TIMESTAMP — local time + GMT offset, YYYY-MM-DDTHH:MM:SS±HHMM (sortable).
• PROJECT-DIR — CLAUDE_PROJECT_DIR if set, else the git top-level of the working dir, else the working dir.
• TOOL/COMMAND(params) — the originating tool/command plus a compact param summary (scalars inline, long strings truncated to ~80 chars, arrays as name[N], secrets redacted; never a whole snippet or file body).
• SUCCESS|FAIL — whether that one web request succeeded.
• DURATION — wall-clock of that request, <N>ms (or <N.N>s once ≥ 1000 ms).
• COST — USD of that request, $0.000000 (6 dp); $0.000000 for local / free / cached calls.
• OP-ID — op-<8hex> shared by every request from the same tool/command invocation, so all the lines of one call can be correlated later with grep <op-id> ~/.llm-externalizer/history.log.

Example:

2026-05-24T05:56:39+0200 - /home/me/proj - chat(instructions=Refactor the auth module…(120), input_files_paths=[2], free=true) - SUCCESS - 1.4s - $0.000007 - op-4047e633

Writing the log is strictly best-effort — a history-write failure never breaks or slows the actual tool call. The file lives in your home dir and may contain absolute paths; it is not committed anywhere.

Troubleshooting

Run /llm-externalizer:llm-externalizer-discover first — the output identifies most problems immediately.

OpenRouter

LM Studio

Ollama

General

Setup wizard

Plugin structure

llm-externalizer-plugin/
├── .claude-plugin/plugin.json     # Plugin manifest
├── bin/                           # llm-ext + llm-ext-benchmark CLI entry points
├── commands/                      # 40 slash commands
├── agents/                        # 6 internal agents (reviewer + 4 fixers + setup-agent)
├── skills/                        # 16 auto-discovered skills
├── rules/                         # Lean always-loaded usage rule (auto-installed to ~/.claude/rules/)
├── scripts/                       # Python: setup, publish, validators, helpers
│   └── llm-ext/                   # Bundled TypeScript CLI engine (all 46 commands; name is historical)
└── docs/                          # Banner, cost image, agent docs (usage-reference, tool-use-cases, setup-and-configuration), OpenRouter refs

Contributing

[!IMPORTANT] The owner-only boundary. Three things are reserved for the upstream repo owner and must not be run by contributors:

1. scripts/publish.py — bumps the plugin version, regenerates CHANGELOG.md, tags, and pushes. Version bumps belong to the release manager, not to individual PRs.
2. The .githooks/pre-push hook — this hook exists to force the owner through publish.py when pushing to upstream. On a fork, it blocks every normal git push and is useless.
3. The .github/workflows/notify-marketplace.yml CI — this workflow notifies the emasoft-plugins marketplace that a new release is available. On a fork it would either fail (no MARKETPLACE_PAT secret) or try to notify the marketplace about your fork — neither is wanted.

The setup below disables all three on your fork so you can push PRs cleanly.

Developer requirements

Beyond the user requirements above, you need:

• uv — Python dependency management (uv venv --python 3.12, uv run ...)
• gh (GitHub CLI) — for opening the PR and managing workflows on your fork

1 · Fork on GitHub, then clone YOUR fork

# Fork at https://github.com/Emasoft/llm-externalizer-plugin/fork
# Then clone — replace <your-username>
git clone https://github.com/<your-username>/llm-externalizer-plugin.git
cd llm-externalizer-plugin

# Track upstream so you can pull in new releases later
git remote add upstream https://github.com/Emasoft/llm-externalizer-plugin.git

2 · Disable owner-only automation on your fork

Do this ONCE, right after cloning, BEFORE your first push. Skipping this step will make your pushes refuse or trigger broken CI runs.

2a · Disable the pre-push hook locally

The repo ships with core.hooksPath = .githooks in its committed config. On a fork you need to undo that.

# Unset the repo's hooksPath so git uses the default .git/hooks/ (which is empty)
git config --local --unset core.hooksPath

# Verify — should print nothing (no active hooks path)
git config --local --get core.hooksPath

# Unset the repo's hooksPath so git uses the default .git\hooks\ (empty)
git config --local --unset core.hooksPath

# Verify — should print nothing
git config --local --get core.hooksPath

The pre-push script itself is unchanged on disk (it's tracked in .githooks/). You're only telling your git not to run it.

2b · Disable GitHub Actions workflows on your fork

The notify-marketplace.yml workflow triggers on every push to main and needs a MARKETPLACE_PAT secret that only the owner has. The ci.yml workflow also runs owner-expected gates. Disable both on your fork so PRs don't spam red CI runs.

Option A — via the gh CLI (fastest):

# Disable the workflow that notifies the marketplace (owner-only)
gh workflow disable "Notify Marketplace" --repo <your-username>/llm-externalizer-plugin

# (optional) Also disable CI on your fork — the upstream PR will run CI instead
gh workflow disable "CI" --repo <your-username>/llm-externalizer-plugin

Option B — via the GitHub web UI:

Go to https://github.com/<your-username>/llm-externalizer-plugin/actions, click each workflow listed in the left sidebar → ... menu → Disable workflow.

Option C — delete the workflow files on your fork branch (nuclear):

If you never want these workflows to run anywhere on your fork, commit a deletion to your branch. Don't do this on main — it would show up in your PR diff.

# Only if you really want to remove the workflows from your fork's main.
# This changes the diff — don't include in a PR.
git checkout -b chore/disable-fork-ci
git rm .github/workflows/notify-marketplace.yml .github/workflows/ci.yml
git commit -m "chore: disable owner-only workflows on fork"

3 · Build the bundled CLI

# Installs npm deps and compiles TypeScript
python3 scripts/setup.py

4 · Install your working copy for local testing

# Point Claude Code at your cloned checkout
claude plugin install "$PWD"

5 · Create a feature branch

git checkout -b feat/<short-description>

6 · Validate before committing

# Fast local validation
claude plugin validate .

# (optional) deeper CPV remote validator
uvx --from git+https://github.com/Emasoft/claude-plugins-validation --with pyyaml \
    cpv-remote-validate plugin "$PWD"

7 · Commit with a Conventional Commit prefix

# The maintainer's release pipeline uses the prefix to classify changes.
#   feat:  — new feature (minor bump)
#   fix:   — bug fix      (patch bump)
#   docs:  — documentation
#   refactor: / chore:    — other housekeeping
#   BREAKING CHANGE: …    — major bump (body or footer)
git commit -m "feat: <what it does>"

[!CAUTION] Do NOT bump version in plugin.json, scripts/llm-ext/package.json, or pyproject.toml in your PR. Do NOT edit CHANGELOG.md. Do NOT run scripts/publish.py. All version work is done by the maintainer after merge.

8 · Push to YOUR fork and open a PR

# Push the feature branch to your fork
git push origin feat/<short-description>

# Open PR against Emasoft/llm-externalizer-plugin main
gh pr create --repo Emasoft/llm-externalizer-plugin --base main

Release pipeline (maintainer only — DO NOT RUN AS A CONTRIBUTOR)

This section documents the commands the upstream maintainer runs after merging PRs. Contributors should ignore it. The pre-push hook on the upstream clone (which contributors disable via step 2a) exists specifically to force these scripts to be used.

Additional maintainer-only tooling:

• git-cliff — auto-computes the next version and regenerates CHANGELOG.md from Conventional Commits (pulled in by publish.py)

# Auto-bump version from Conventional Commits, run all gates, push tag + release
python3 scripts/publish.py

# Force a specific bump
python3 scripts/publish.py --patch
python3 scripts/publish.py --minor
python3 scripts/publish.py --major

# Dry-run preview (still runs all checks)
python3 scripts/publish.py --dry-run

# Used by the pre-push hook — runs checks, exits, no mutations
python3 scripts/publish.py --check-only

publish.py runs 9 mandatory validation gates before any tag or push: npm ci, npm run typecheck, npm run lint, npm run build, npm test, ruff check, shellcheck, plugin.json schema, claude plugin validate. All must pass with zero errors.

npm test is offline and free — it never makes a real LLM call. Real-LLM (live) tests are opt-in behind LIVE_TESTS=1 + OPENROUTER_API_KEY. See scripts/llm-ext/TESTING.md.

License

MIT — see LICENSE.

Links

• Marketplace: https://github.com/Emasoft/emasoft-plugins
• Source: https://github.com/Emasoft/llm-externalizer-plugin
• Issues: https://github.com/Emasoft/llm-externalizer-plugin/issues