agent-complexity-optimizer

Scan any codebase for O(n^2) hotspots, N+1 queries, and algorithmic complexity issues. Get a structured report with severity, location, and fix suggestions — without modifying a single file.

Works as a skill/plugin for 13 AI coding agents, or standalone via Python CLI.

Extended from codex-complexity-optimizer by Kappaemme. See CREDITS.md for full attribution and a breakdown of what this project adds.

Demo

Given this code:

def find_duplicates(users, transactions):
    duplicates = []
    for t in transactions:
        for u in users:                          # O(n*m) nested scan
            if u["id"] == t["user_id"]:
                duplicates.append(t)
    return duplicates

def get_user_orders(user_ids, db):
    results = []
    for uid in user_ids:
        order = db.query(f"SELECT * FROM orders WHERE user_id = {uid}")  # N+1
        results.append(order)
    return results

The scanner produces:

# Complexity Hotspots

## HIGH nested-loop
- Location: `example.py:4`
- Finding: Nested loop may create O(n^2) or worse behavior.
- Suggestion: Check whether a map/set index, sort+two-pointer pass,
  grouping, or batching can replace the inner scan.

## HIGH io-or-query-in-loop
- Location: `example.py:12`
- Finding: Potential database/API/file operation inside a loop.
- Suggestion: Look for N+1 behavior; batch or preload while preserving
  auth, filters, ordering, and error handling.

What It Detects

Pattern	Severity	Example
Nested loops	High	for x in A: for y in B — O(n*m)
N+1 queries	High	db.query() / fetch() inside a loop
Sorting inside loops	High	.sort() called per iteration
Membership checks in loops	Medium	.includes(), in, indexOf() inside iteration
Render-path recomputation	Medium	.filter().map() in React component body
Pairwise comparisons	High	Every-pair scan that could be sort+sweep

Supports: Python (AST-based), JavaScript, TypeScript, JSX/TSX, Java, Go, C, C++, C#, Ruby, PHP, Swift, Rust, Kotlin, Scala, Lua, Zig, Elixir, Erlang, Dart, R, Julia, OCaml, Clojure, and more (regex-based).

Install

Claude Code (marketplace)

/plugin marketplace add sebastianbreguel/agent-complexity-optimizer
/plugin install complexity-optimizer@complexity-optimizer

Codex

npx skills add sebastianbreguel/agent-complexity-optimizer -a codex -g -y

All other agents (auto-detect)

npx agent-complexity-optimizer

Auto-detects installed agents (Cursor, Windsurf, Gemini CLI, Cline/Roo, Aider, OpenCode, Continue.dev, Amazon Q, Zed AI) and writes the correct config format for each. Preview with --dry-run.

GitHub Copilot reads instructions per-repository, so the installer can't set it up globally. Copy these into the repo you want to scan:

cp agents/copilot/copilot-instructions.md <your-repo>/.github/
mkdir -p <your-repo>/.github/complexity-optimizer
cp skills/complexity-optimizer/scripts/analyze_complexity.py <your-repo>/.github/complexity-optimizer/

Standalone (no agent needed)

python3 skills/complexity-optimizer/scripts/analyze_complexity.py /path/to/repo --format markdown
python3 skills/complexity-optimizer/scripts/analyze_complexity.py /path/to/repo --format json

Supported Agents

Agent	Install	Config format
Claude Code	marketplace / npx skills add	SKILL.md
Codex (OpenAI)	npx skills add	SKILL.md + openai.yaml
Pi	npm install -g	SKILL.md (pi.skills)
Cursor	auto-detect	.mdc rule
Windsurf	auto-detect	.windsurfrules
GitHub Copilot	manual (per-repo .github/)	copilot-instructions.md
Gemini CLI	auto-detect	GEMINI.md
Cline / Roo Code	auto-detect	.clinerules
Aider	auto-detect	CONVENTIONS.md
OpenCode	auto-detect	AGENTS.md
Continue.dev	auto-detect	Custom command YAML
Amazon Q	auto-detect	Rules .md
Zed AI	auto-detect	Assistant rules

Agent config files under agents/ are generated from skills/complexity-optimizer/SKILL.md and a condensed template — edit the source, then run python3 scripts/sync_agents.py (CI fails on drift).

Usage

Ask your agent naturally:

Analyze this codebase for complexity hotspots and give me a report.

Scan for performance issues — nested loops, N+1 queries, O(n^2) patterns.

Reports are read-only by default. To apply a fix:

Implement the lowest-risk optimization from the report and run the tests.

What This Project Adds

The original project supported Codex only. This fork extends it to 13 agents and adds:

• Universal installer — auto-detects agents and writes native config formats
• Claude Code marketplace — first-class plugin support
• Extended scanner — additional languages (Rust, Kotlin, Scala, Lua, Zig, Elixir, Erlang, Dart, R, Julia, OCaml, Clojure) and patterns (list comprehensions, generator expressions, more query signatures)
• Fewer false positives — membership checks against sets/dicts are skipped (Python AST tracks what was built as a set), and generic verbs like .get()/.find() only count as potential N+1 when called on a client-like receiver (db, session, client, requests, ...)
• Structured reports — with severity ranking, benchmark sections, and safety checklists

License

MIT