lemmaly

A deterministic CI scanner for algorithmically lazy code, plus a codified four-skill methodology that teams can adopt as their reviewing standard.

Every AI coding assistant writes code that works. Few write code that scales, terminates correctly on every edge case, or reaches for the right algorithm. The same handful of failures ship in nearly every AI-generated codebase: O(n²) loops where a hash would do, N+1 queries, missed base cases, off-by-one bugs, brute force when a known algorithm exists, and "should be O(log n)" claims that were never derived.

lemmaly ships two things:

1. A CLI scanner with 59 deterministic rules across 11 languages that catches these patterns in CI without an LLM, without an API key, and without a network call. This is the validated, measurable value.
2. A four-skill methodology (gateway + correctness + math + corrective) with hand-authored Incorrect/Correct examples per rule. Use it as a team standard, a reviewer checklist, or as Claude Code / Cursor skills for projects where you want explicit complexity statements in code comments.

The suite — four skills

lemmaly is not one skill; it is a small family that covers the whole CS surface AI assistants typically skip.

| Skill | Triggers on | What it forces | | --- | --- | --- | | lemmaly (gateway) | any loop, collection, lookup, recursion, query | state Big-O, name the data structure, pick the algorithm family, justify repeated work | | mathguard | large-n problems, similarity, dedupe, top-K, streaming, embeddings, signal/poly, geometry | reach for probabilistic structures (Bloom, HLL, Count-Min, MinHash/LSH), FFT/NTT, JL projection, sweep line, kd-tree — and declare ε/δ when approximate | | invariant-guard | loops, recursion, mutating state | state loop invariants, base cases, termination measure, edge case table — before code | | complexity-cuts | "this is slow", "times out", "OOM", existing code with bad Big-O | corrective playbook: nested loop → hash, repeated scan → index, materialize → stream, naive → memoized, brute-force → sort+sweep |

The skills compose. lemmaly picks the algorithm; invariant-guard proves it works; mathguard reaches further when classical hits its floor; complexity-cuts fixes what already shipped.

What it ships

• Four Claude Code / Cursor skills in skills/ — drop into ~/.claude/skills/ or commit per-project under .claude/skills/. Each skill has frontmatter metadata (pathPatterns, importPatterns, chainTo) so the agent loads the right one automatically.
• Per-rule documentation in skills/lemmaly/rules/<rule-id>.md — one file per CLI rule with hand-authored Incorrect/Correct examples and an escalation path. CLI and skills share the same rule IDs.
• Compiled rule catalog in skills/lemmaly/AGENTS.md — single-document batch-load view of all 59 rules.
• Slash commands as the vocabulary: /complexity, /hotpath, /n-plus-one, /invariant, /cut, /benchmark, /ship-check, /scale-check.
• Reference modules loaded on demand — complexity tables, N+1 patterns, hot-path recognition, memory & async pitfalls. Small context cost.
• A deterministic CLI (lemmaly scan) — no API key, no LLM, no network. 59 rules across 11 languages: JavaScript / TypeScript, Python, SQL, Java, C#, Go, Rust, C++, PHP, Ruby, Shell / Bash. Runs in CI in seconds.
• Self-consistency tests (npm test) — rule-pattern tests plus a checker that verifies CLI rules, per-rule docs, AGENTS.md, and the gateway catalog stay in sync.
• Generators (npm run gen) — regenerate per-rule docs and the compiled catalog from rules/*.json whenever new rules are added.
• A GitHub Actions workflow ready to drop into any repo — runs both the scan and the self-test, fails CI on doc/rule drift.

Install

As a Claude Code / Cursor skill suite

# Via the skills CLI (works with Claude Code, Codex, Cursor, OpenCode, and 50+ agents)
npx skills add morsechimwai/lemmaly                # project-local
npx skills add morsechimwai/lemmaly -g             # global (~/.claude/skills/)
npx skills add morsechimwai/lemmaly --list         # see all 4 skills first

Or copy directly:

# Personal (every project picks them up)
cp -r skills/lemmaly skills/mathguard skills/invariant-guard skills/complexity-cuts ~/.claude/skills/
cp commands/*.md ~/.claude/commands/

# Or project-local (commit it with the repo)
mkdir -p .claude/skills .claude/commands
cp -r skills/lemmaly skills/mathguard skills/invariant-guard skills/complexity-cuts .claude/skills/
cp commands/*.md .claude/commands/

Hermes Agent (Nous Research)

Hermes uses the SKILL.md standard from agentskills.io. The npx skills CLI ships an hermes-agent target — verified in skills v0.x against ~/.hermes/skills/.

# Project-scoped — drops the four skills into ./.hermes/skills/
npx skills add morsechimwai/lemmaly --agent hermes-agent \
  --skill lemmaly mathguard invariant-guard complexity-cuts -y --copy

# User-global — drops them into ~/.hermes/skills/
npx skills add morsechimwai/lemmaly --agent hermes-agent -g \
  --skill lemmaly mathguard invariant-guard complexity-cuts -y --copy

Manual equivalent (if you don't want the CLI):

mkdir -p ~/.hermes/skills
cp -r skills/lemmaly skills/mathguard skills/invariant-guard skills/complexity-cuts ~/.hermes/skills/

OpenClaw

OpenClaw also reads SKILL.md (see docs.openclaw.ai/clawhub/skill-format). The npx skills CLI ships an openclaw target — verified to write to ./skills/ (project) and ~/.openclaw/skills/ (global).

# Project-scoped — drops the four skills into ./skills/
npx skills add morsechimwai/lemmaly --agent openclaw \
  --skill lemmaly mathguard invariant-guard complexity-cuts -y --copy

# User-global — drops them into ~/.openclaw/skills/
npx skills add morsechimwai/lemmaly --agent openclaw -g \
  --skill lemmaly mathguard invariant-guard complexity-cuts -y --copy

Manual equivalent:

mkdir -p ~/.openclaw/skills
cp -r skills/lemmaly skills/mathguard skills/invariant-guard skills/complexity-cuts ~/.openclaw/skills/

The four skills declare no requires.env or external bins, so OpenClaw's security scan passes them as-is — no extra metadata.openclaw block needed. The CLI scanner is optional; install it separately if you want CI gating (see below).

Targeting both at once: --agent hermes-agent openclaw is a single install. List every supported client with npx skills add <repo> -l.

As a CLI scanner

# From this repo
node cli/lemmaly.js scan ./src

# Or globally (once published)
npm i -g lemmaly
lemmaly scan ./src

Try it

node cli/lemmaly.js scan examples/before-after/bad.jsx

You should see 2 errors, 5 warnings, 3 info across 9 distinct rule IDs — every numbered anti-pattern in the demo file flagged with a specific fix. Compare against examples/before-after/good.jsx.

How to use it with an AI agent

Once the skills are installed (see above), invoke them by name from Claude Code, Cursor, or any agent that loads .claude/skills/. The skill descriptions, pathPatterns, and importPatterns also let it auto-trigger when you touch loops, queries, or collections — but explicit prompts are the most reliable.

| When | Paste this prompt | | --- | --- | | First look — no specific concern, just point it at the code | Use the lemmaly skill to check src/ for algorithmic risks. State the Big-O of any function over a collection, and call out N+1 queries, repeated scans, and brute-force loops with a named fix. | | Before writing a new function | Use the lemmaly skill: run /complexity on findDuplicates(items: T[]). State Big-O, the data structure choice, and the loop invariant in comments before writing the body. | | After AI writes an endpoint that feels slow | Use the lemmaly skill: run /n-plus-one on src/orders/list.ts. If it finds a repeated query inside a loop, follow up with /cut and rewrite using a single batched IN query. | | Pre-merge gate on a diff | Use the lemmaly skill: run /ship-check on the current diff. Block merge if any new function is O(n²) without a comment justifying it, and flag any recursion without a stated base case. | | Will it hold at 10×? | Use the lemmaly skill: run /scale-check on this dedupe at 10× and 100× today's 50k rows. Name the cliff and the next structure (HLL, MinHash, sweep line) when classical breaks. |

The slash commands (/complexity, /n-plus-one, /ship-check, /scale-check, /hotpath, /invariant, /cut, /benchmark) are the vocabulary — full list and demos at lemmaly.dev.

What we tested, honestly

We ran a live behavioral test: 8 prompts (2 per skill) sent twice to Claude Haiku 4.5 — once with the lemmaly skills installed in .claude/skills/, once without. We then scored each response for skill-aligned markers (Big-O claims, named data structures, invariants, ε-bounds for approximate algorithms). Reproducer here.

Result on Haiku 4.5: 7 ties, 1 cosmetic regression, 0 strong uplift, $0.40 total spend.

That finding matters. It means:

• Frontier 2026 models (Haiku 4.5 / Sonnet 4.6 / Opus 4.7) already produce skill-aligned code on these prompts by default. They reach for Set, write O(1) lookup in the explanation, and recommend HyperLogLog for cardinality-at-scale — without lemmaly installed.
• The skills are not making competent models smarter. They are codifying the discipline you would want a junior engineer or a less-capable model to follow.

Where lemmaly's value is empirically validated:

| Layer | Value | Evidence | |---|---|---| | CLI scanner | Catches the named anti-patterns deterministically in CI | 59/59 rule-pattern tests pass; sanity scan flags 21 findings across 8 sample files in 8 languages | | Per-rule docs + AGENTS.md | Single source of truth for both human reviewers and AI agents | Consistency test verifies CLI ↔ MDs ↔ AGENTS.md ↔ gateway stay in sync | | Skill methodology | Iron Laws, verification checklists, canonical Good/Bad pairs, escalation paths | Documents a complete reviewing standard a team can adopt | | Behavioral uplift on Haiku 4.5+ | Not measurably present. Skills duplicate what the model already knows | Live test: 0/8 strong wins |

Where we expect skills to actually move behavior (untested, but plausible): smaller / older models, code-review settings where the Iron Laws force explicit derivations in comments, and contexts where the CLI scanner output is fed back to the model.

The honest pitch

For competent models you barely need the skills. For CI gates and team standards, you need the rules.

Install the CLI. Drop the GitHub Actions workflow into your repo. Read the four SKILL.md files as a reviewing checklist. Install the skills into Claude Code / Cursor if you want every AI-generated commit to carry an explicit complexity comment — that part is discipline, not knowledge.

The rules

59 deterministic rules across 11 languages — JavaScript / TypeScript, Python, SQL, Java, C#, Go, Rust, C++, PHP, Ruby, Shell / Bash. Run lemmaly rules to see the full list, or read skills/lemmaly/AGENTS.md for every rule with its Incorrect / Correct example.

| Severity | Rule | Why it matters | | --- | --- | --- | | error | js-await-in-for-loop | N+1 over network | | error | js-async-in-foreach | dropped promises | | error | py-mutable-default-arg | shared default state | | error | sql-update-no-where | touches every row | | error | java-arraylist-remove-in-for-i | index shifts; CMException risk | | error | cs-async-void | unobserved exceptions crash the process | | error | go-loop-var-capture | pre-1.22 race on the last value | | error | php-query-in-loop | N+1 against the database | | warning | js-helper-call-in-iterator | N round-trips inside a loop | | warning | js-deep-clone-via-json | JSON.parse(JSON.stringify(x)) | | warning | sql-select-star | blocks index-only scans | | warning | java-string-concat-in-loop | use StringBuilder | | warning | cs-disposable-no-using | leak on exception | | warning | go-defer-in-loop | defers accumulate to function exit | | warning | rs-unwrap-in-prod | panics on None/Err | | warning | cpp-raw-new | manual delete; exception-unsafe | | warning | rb-bare-rescue | catches StandardError; hides bugs | | warning | sh-set-e-no-pipefail | pipe failures masked | | warning | sh-unquoted-var | word-splitting / glob expansion | | info | js-nested-for-loops | O(n×m) — hash one side | | info | cpp-range-loop-copy | use const auto& | | info | php-loose-equality | use === | | info | sh-useless-cat-pipe | pass file directly | | … 35 more across 11 languages | (see lemmaly rules or skills/lemmaly/AGENTS.md) | |

CI integration

# .github/workflows/lemmaly.yml
- run: npm i -g lemmaly
- run: lemmaly scan .

Exit code 1 on any error-severity finding. Warnings and info do not fail the build.

Status

v0.2 — multi-language CI scanner + codified methodology.

• ✅ 59 rules across 11 languages, all with positive + negative test cases.
• ✅ Per-rule documentation aligned with CLI rule IDs.
• ✅ Self-consistency tests prevent rule / doc / catalog drift.
• ✅ GitHub Actions workflow: scan + self-test + regenerate-and-diff.
• ✅ Static skill-triggering test (42 prompts) confirms prompt vocabulary matches skill descriptions.
• ✅ Live behavioral test scaffolding (tests/skill-triggering/live.js) and findings (above).

The case study in case-studies/ describes a measured 22.8× speedup on a real production app — predating this release's multi-language and live-test work.

Roadmap

• v0.2 — multi-language CI scanner + codified methodology + honest live-test findings. You are here.
• v0.3 — framework rule packs (Next.js, FastAPI, Rails) and broader sampling of the live behavioral test against weaker / older models where we expect the skills to actually move behavior.
• v0.4 — VS Code extension that surfaces CLI findings inline; CLI emits invariant-stub comments for invariant-guard.

Contributing

See CONTRIBUTING.md. Especially welcome: new rule proposals with both a positive and a negative test case, and new playbook entries for complexity-cuts and mathguard with derivations.

License

Apache 2.0. Use it commercially, modify it, fork it. If you are an enterprise looking for custom rule packs or codebase-specific tuning, reach out — that is the support model.