🕸️ RECLUSE

An autonomous detect→fix→verify loop for the bugs that hide in your system's seams. MCP server + GitHub Action + a shared bug-corpus.

The recluse bites the bugs that hide in the seams.

When you vibe-code, writing is fast but debugging is slow — you didn't write the code, so you don't know where it broke. And the bugs that actually bite in production usually aren't in one file; they live in the seams between subsystems: a value written in cents and read as dollars, an auth check that passes on NULL, an RLS policy that leaks every row, a SECURITY DEFINER function anyone can call because the grant went to PUBLIC.

RECLUSE traces those seams (producer → store → consumer), catches the mismatch with live evidence, dispatches a fixer, re-verifies — then pools every caught pattern into a shared corpus so the next project catches the same trap at round-zero.

→ Live page & corpus: https://eduverse-ai.app/recluse

What it does — a closed loop

WEB (detect) → CATCH (contract mismatch) → SPIDER (autonomous fix) → RE-WEAVE (verify) → loop until 🔴 = 0

• WEB — fan out read-only QC agents with different viewpoints (security, data/payment, integration contracts). One reviewer's blind spot is another's catch.

• CATCH — where a producer/consumer contract tears, report it with the exact coordinate (file:line, constraint, RLS policy) and a severity.

• SPIDER — dispatch a fixer agent per finding into an isolated git worktree; several fix in parallel without collision. Only the orchestrator merges — detectors stay read-only.

• RE-WEAVE — re-run the fixed strand and its neighbors to prove no regression. Loop until clean.

The orchestration (fan-out, dedup, dispatch, re-weave) is deterministic code — a plain loop, not model-driven. Only the spiders (detect/fix) are LLM calls.

What it caught (real, on a live app)

Run against a production Next.js + Supabase/Postgres app, it found privilege-escalation bugs a static review had passed:

• a SECURITY DEFINER function callable by anon, because REVOKE EXECUTE ... FROM anon is a no-op when the grant is to PUBLIC;

• a plpgsql guard bypassed by NULL three-valued logic — NULL OR false is NULL, which IF NOT treats as false, so the guard's exception never fired;

• a SECURITY DEFINER view that let anon write through it, bypassing RLS on the base table.

All three only reproduced against a live endpoint — reading the source called them safe. Each is now a built-in detection signal (spider_signals) with the exact query to reproduce it — alongside curriculum order-integrity (band inversion / cyclic prerequisites), per-user-limit anonymous farming, stream-budget 502s, and event producer↔consumer contract drift.

Related MCP server: Smart Contract Security Analyzer

Quickstart

① MCP server — for your editor (Claude, Cursor, any MCP client)

One line, no clone — published on npm:

{ "mcpServers": { "recluse": {
  "command": "npx",
  "args": ["-y", "recluse-mcp"],
  "env": { "SPIDER_CORPUS_API": "https://eduverse-ai.app/api/corpus" }
} } }

Tools: spider_plan · spider_classify_tier · spider_checklist · spider_signals (detection query/grep per bug class) · spider_record_pattern (local + shared contribution) · spider_pull_corpus (collective pull, verified-first). Resources: spider://checklist · spider://queries · spider://corpus · spider://blackbox.

Knowledge is built into the server — the checklist, contract queries, and a seed corpus of live-verified bug classes ship inside the package, so it works standalone. If you also run the spiderweb-qc skill, its richer reference files are picked up automatically (set SPIDER_REF_DIR).

② GitHub Action — gate every PR (blocks on 🔴)

# .github/workflows/recluse.yml
name: RECLUSE
on:
  pull_request:
    branches: [main]
jobs:
  weave:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: vinsenzo83/recluse@v1.1
        with: { base: origin/${{ github.base_ref }} }
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Without a key it runs in advisory mode (known-trap checklist, non-blocking). With ANTHROPIC_API_KEY it does a real weave on the diff, blocks on 🔴, and contributes new patterns to the corpus.

Spider tiers — resource by criticality

Not every path deserves Opus. Tier by risk:

So you're not paying Opus rates to check a comment — and the paths where a false negative is expensive get the most scrutiny.

The shared corpus

Every caught bug is distilled into a stack-keyed pattern (detection signal + fix principle) and pooled. A new project checks known traps at round-zero — the more it's used, the thicker the net.

• Scrub-first: file paths, code literals, secrets (keys / JWT / high-entropy), emails, URLs, IPs are stripped before anything is shared; anything still suspicious is rejected. Only the generalized technique leaves your machine.

• Anonymous: contributors/projects are stored as irreversible hashes — no identity, no raw text.

• Consensus: a pattern needs 3 independent contributors before it's marked verified.

Corpus API (base = SPIDER_CORPUS_API)

• POST /patterns {klass,name,signal,fix,tags?,severity?,tier?} → scrub · dedup · trust accrual (rate-limited per IP)

• GET /patterns?tags=postgres,payment&class=unit&verified=1&limit=50 → pull the corpus (verified=1 = consensus-verified only, for production use)

Contributing is open — pick a contributor token, POST. No signup, no key required (the token is your anonymous identity, not a credential).

Honest limitations

• Early (v0.1.1), best-tested on Next.js / Supabase / Postgres — other stacks have thinner coverage until the corpus fills in.

• Running it costs tokens. The tool is free to use, but a full weave spawns model calls (Opus on critical paths). It's not free to run.

• Not open-source. The MCP client is on npm and the repo is source-available, but not OSI-licensed; the corpus backend is a hosted, closed service. A free tool, not an open one.

• "Live evidence only" is the rule, not a proof. The model can still be wrong — the re-verify step is the guard, not a guarantee.

Principles

No fabrication (live evidence only) · scrub-first (zero code/secret leakage) · opt-in & anonymous · detection = read-only, fixes = isolated spiders.

Repo layout

src/index.js       # MCP server (stdio)
cli/recluse.mjs    # CI weave CLI
action.yml         # GitHub Action

The shared corpus is a hosted service (https://eduverse-ai.app/api/corpus); its backend (schema, scrub pipeline, ingestion) is closed-source.

License

UNLICENSED (proprietary). Free to use; not open-source.