Evidence-led Windows performance investigation, inside the AI harness you already use.

---

NeuroTune is an Agent Skill for Windows gaming stutter and performance investigations. It runs inside your existing AI coding harness (Claude Code, Pi, OpenCode, Codex, or anything that can load a skill and run local commands) instead of being its own app. The harness supplies the model, the conversation and the permissions; NeuroTune supplies a small, deterministic local CLI for inventory, frame-time analysis and evidence-linked tuning plans.

It does not apply anything. NeuroTune investigates, cites evidence for every claim and produces a plan a human reviews — it has no system writer, no privileged broker and no Apply/rollback step. See Not implemented for the exact boundary.

Contents

• Why
• How it works
• What it does
• Not implemented
• Install
• Use it
• CLI quick start
• Safety and privacy
• Project layout
• Development
• License and provenance

Why

Most frontier models already roughly follow a sane investigation flow on their own. NeuroTune exists to make that flow repeatable, evidence-bound and consent-gated rather than to replace the model's own judgment — a thin skill layer, not a second agent. There is no bundled list of apps, services or tweaks to apply: the model classifies what it actually finds on the machine (safe to remove / ask the user / never touch), because a static list goes stale with every Windows update and OEM image. The skill's job is to make sure nothing gets silently skipped, not to think for the model — so a smaller or local model will still reason less reliably about any one finding than a frontier model would; NeuroTune narrows that gap, it does not close it. It is the successor to an earlier standalone desktop app project (NeuroTune, now retired): same investigation goal, no app, no provider lock-in, no separate UI to maintain.

How it works

The skill walks a conversation through six steps, each gated on explicit consent, never run silently in a batch:

1. Scope and guide — doctor/goals/help establish objectives and capabilities; at most two plain-language questions at a time.
2. Consent — nothing is collected or shared without being asked first; collecting local inventory and sharing it into the model's context are two separate approvals.
3. Evidence — every inventory, frame or app/service report is run through evidence and cited as metric | value | full fact ID, never pasted raw. Apps, services, startup items and drivers are read live through the harness's own command tool and worked through a fixed coverage checklist, so a category never gets silently skipped.
4. Measure — imports PresentMon CSV or a single CapFrameX JSON run; it does not record captures itself.
5. Challenge — states one plausible explanation plus at least one alternative, and names the measurement that would falsify it.
6. Assess and review — produces an evidence-linked plan or intervention proposal for the human to approve, choose from, or reject; no step in that proposal is ever executed by the skill.

Full workflow detail lives in skills/neurotune/SKILL.md.

What it does

• Local Windows inventory with a separate collect-then-share step.
• PresentMon-compatible CSV and single-run CapFrameX JSON analysis: average present cadence, frame-time percentiles, stutter counts.
• Before/after comparisons with workload, duration, stream-identity and duplicate-source checks.
• Objective presets and short guided question batches — no predefined tweak bundles.
• Structured assessments bound to validated source reports, with missing coverage and uncertainty stated explicitly.
• Hardware-specific game-config discovery guidance for 13 games (candidate paths/formats/keys, not static presets).
• Live-read apps, background services, startup items and driver versions via the harness's own command tool, classified per machine (safe to remove / ask the user / never touch) — no bundled debloat list to go stale.
• Live interrupt/DPC counters and IRQ-to-device mapping for stutter not explained by frame-time capture alone, with an optional LatencyMon pass or in-game PresentMon/FrameView capture for more precision.
• Evidence-linked advisory plans and intervention-proposal review, including dependency checks on selected steps. Invented fact IDs are rejected.
• A self-contained Agent Skills directory, Pi package and Claude Code plugin manifest, plus a JSON CLI any tool-capable harness can call directly.

Not implemented

Apply/rollback, live ETW capture, a privileged broker, tool acquisition/installation, driver/firmware updates, MCP transport, GPU/BIOS tuning, security remediation, or automatic diagnosis outside a harness. Imported comparisons are descriptive, not proof an optimization worked. Read-only is the current runtime limit, not the destination — see docs/ROADMAP.md for what assessment-driven execution would require (genuine approval, recovery, authority gates).

Install

Requires Node.js 22+. Live inventory additionally requires Windows with Windows PowerShell 5.1. No npm install needed. Pick one:

Harness	Command
Claude Code (one command, no clone)	/plugin marketplace add PrimeBuild-pc/NeuroTune then /plugin install neurotune@NeuroTune
Pi / any Agent-Skills-compatible harness	node scripts/install.mjs --skills-dir "$HOME/.agents/skills"
Pi package (no copy)	pi install "C:/path/to/NeuroTune.Skill"
Claude Code plugin (local clone, no copy)	claude --plugin-dir "C:/path/to/NeuroTune.Skill" then /neurotune:neurotune
No Agent Skills support	Point the model at skills/neurotune/SKILL.md and ask it to follow the workflow (needs local file + command tools)

The copy installer writes to <skills-dir>/neurotune and never touches harness settings. Reload/restart the harness afterward. See the full per-harness table for Pi, Claude Code, OpenCode, Codex and Hermes.

Use it

/skill:neurotune Investigate stutter in my game. Collect locally first; ask before sharing hardware facts.

Or in any harness without a slash command: "Use the NeuroTune skill to compare these before/after PresentMon captures. Explain uncertainty; do not apply tweaks."

The skill asks about symptoms and data sharing, selects relevant evidence, challenges its own explanation and produces a bounded next step — using the harness's current model and current command-permission settings, with no second permission system layered on top.

CLI quick start

node skills/neurotune/scripts/cli.mjs doctor
node skills/neurotune/scripts/cli.mjs goals
node skills/neurotune/scripts/cli.mjs collect --out "inventory-01.json"
# Review inventory-01.json locally before letting it into a model context.
node skills/neurotune/scripts/cli.mjs evidence --input "inventory-01.json"

node skills/neurotune/scripts/cli.mjs frames --input "before.csv" --process "game.exe" --conditions "Same replay, 1080p, fixed graphics" --out "before.json"
node skills/neurotune/scripts/cli.mjs frames --input "after.csv"  --process "game.exe" --conditions "Same replay, 1080p, fixed graphics" --out "after.json"
node skills/neurotune/scripts/cli.mjs compare --baseline "before.json" --candidate "after.json"

Output is a single JSON envelope ({ "ok": true, "data": ... } / { "ok": false, "error": ... }); errors exit nonzero. New report paths must be .json, and an existing report is never overwritten. See the measurement contract and advisory plan format for the rest of the command surface (apps-services, game-configs, assess, proposal-check, plan-check, frames-capframex, tools).

Safety and privacy

The local CLI has no arbitrary command endpoint and no system writer — it does not authenticate reports, sandbox the harness, or establish consent cryptographically. Run it from a non-admin harness session and review the harness's own tool permissions.

collect returns a receipt without hardware facts; later evidence/analysis output does enter the harness context, under that harness/provider's own retention policy. Data minimization is not anonymization — treat device strings and imported files as untrusted data. See SECURITY.md.

The original desktop app's protected journals, approvals and rollback are a separate project; this skill neither reads nor modifies them.

Project layout

skills/neurotune/     Installable, self-contained runtime and workflow
  SKILL.md             Small, harness-independent entry point
  scripts/             JSON CLI, pure analysis, Windows collector
  references/          Guided assessment/review, inventory, measurement and plan formats
.claude-plugin/        Claude Code plugin metadata (no host-specific runtime)
scripts/               Copy installer and verification tools
tests/                 Unit, subprocess and installation tests
evals/                 Native case definitions (local transcripts/results excluded)
docs/                  Architecture, roadmap, compatibility and continuation notes

Development

npm test              # unit + CLI tests
npm run check          # static checks
npm run test:package   # installation-outside-repo checks
npm run test:collector # explicit read-only live Windows smoke test
npm run pack:local      # build an offline-installable npm archive

npm test uses synthetic data only; live collection is opt-in. See docs/COMPATIBILITY.md for the exact per-OS/Node test matrix, and docs/ARCHITECTURE.md / docs/decisions/0001-skill-first.md / docs/ROADMAP.md before expanding scope.

License and provenance

MIT licensed — see LICENSE. No proprietary AMD component or vendor tool is bundled. NOTICE.md records exactly what numerical logic was reused from the retired MIT-licensed NeuroTune desktop project and under what terms.