nerd
Your codebase has hundreds of hardcoded thresholds, magic numbers, and untested heuristics. You don't know which ones matter. The nerd does.
A Claude Code plugin that obsessively researches your codebase overnight — finding every tunable parameter, designing rigorous experiments with competing theories, running them in isolated worktrees, and delivering findings that tell you what to keep, what to change, and what to rearchitect. It remembers what it learned, so it never wastes time re-testing what it already proved.
Why
Most "optimization" is guessing. You tweak a threshold, eyeball the result, ship it. The nerd treats your codebase like a research problem:
- It doesn't just test if a parameter is optimal. It generates competing theories about why it exists — is the parameter wrong? Is the model wrong? Is the feature unnecessary? Is the data the real bottleneck?
- It runs experiments in parallel worktrees so your working branch stays clean.
- It remembers everything via a persistent knowledge graph, so run 2 builds on run 1's findings instead of rediscovering them.
- It runs while you sleep. Schedule it tonight, review the findings tomorrow.
The most valuable findings aren't parameter tweaks. They're architectural discoveries that only emerge when you test competing explanations.
Install
claude plugin install nerd
Quick Start
/nerd-setup # One-time hardware calibration
/nerd # Let the nerd loose on your codebase
/nerd-loop "search relevance" # Deep continuous iteration on one area
/nerd-schedule tonight # Run experiments overnight
/nerd-setup runs once per machine. Projects auto-initialize on first /nerd run.
What It Actually Does
/nerd — Broad Research
Scans your codebase for every tunable parameter, designs experiments with competing theories, validates the lab environment, runs them in parallel, and delivers structured findings.
/nerd "search ranking"
├─ parameter-scanner finds 12 tunable parameters
├─ plan-reviewer generates 3 competing theories per experiment
├─ lab-tech validates data access, config wiring, build cache
├─ experiment-executor runs experiments in parallel worktrees
├─ report-compiler evaluates which theories held up
└─ loop-scout recommends the best target for deep iteration
/nerd-loop — Deep Iteration
Karpathy's autoresearch pattern applied to your code. Reads the code, hypothesizes an improvement, makes the change, measures, keeps if better, reverts if not — and repeats until it hits a local maximum.
/nerd-loop "search relevance"
├─ Establishes baseline metric (e.g., nDCG@10)
├─ Loops: edit → test → measure → keep/discard
├─ Pivots strategy after 5 consecutive failures
├─ Escalates after another 5
└─ Stops at local maximum (15 failures across 3 strategies)
It doesn't just sweep parameters — it rewrites algorithms, restructures logic, removes unnecessary code. Anything within the scoped files is fair game.
/nerd-this — Context-Scoped Research
Research just what you're working on right now. Infers scope from your current branch, session files, and conversation topics, then groups findings into research themes.
/nerd-this auth flow
├─ Infers scope from git diff + session context
├─ Groups parameters into research themes
└─ Runs the full experiment pipeline on selected themes
Competing Theories
This is the core insight. Most experiment tools ask "is this parameter optimal?" The nerd asks "what's actually going on?" by generating 3+ competing theories per experiment:
| Theory Type | What It Tests |
|---|
| Parameter is wrong | A different value would improve the metric |
| Model is wrong | The mathematical model is inappropriate — try a different one entirely |
| Feature is unnecessary | Removing the feature causes no degradation |
| Data is the bottleneck | The parameter doesn't matter because the input data is the real problem |
| Architecture is the bottleneck | No parameter value can fix this — the architecture needs to change |
Reports evaluate each theory as SUPPORTED / REFUTED / INCONCLUSIVE and recommend: KEEP, CHANGE, REMOVE, REARCHITECT, or INVESTIGATE.
Research DAG — The Nerd Remembers
Every theory, verdict, and finding is persisted in a JSON knowledge graph. The nerd gets smarter with every run:
- Skips dead ends — won't re-test parameters linked to active REFUTED verdicts
- Seeds from open threads — picks up unresolved theories from prior runs
- Detects staleness — re-tests when your source files change significantly
- Synthesizes patterns — surfaces cross-experiment insights when 3+ verdicts converge
shawnroos
