Autonomous performance agent · Windows + Linux

Personalized medicine for your PC. Not a preset.

NVPilot reads your specific hardware, figures out what is actually holding your system back, and changes only the settings that are costing you performance on your GPU — preserving everything else at full quality. Every change is journaled with its inverse, so all of it is reversible.

Get started View source ↗

TypeScript · nvidia-smi · local LLM optional (Ollama) · always reversible

nvpilot — sample run (RTX 3060 Laptop)

$ npm run analyze >>> PERCEIVE — system state GPU: NVIDIA GeForce RTX 3060 Laptop GPU VRAM: 2481/6144 MiB (40% used) Temp: 67°C Power: 78W / 115W Load: 91% Tier: MID Game: javaw.exe (PID 18244, 3102 MB, priority normal) >>> PLAN — decided by LLM (nemotron-mini) VRAM headroom is fine; the GPU itself is the bottleneck at 91% load. Reduce render distance and clouds only; keep shadows. Proposed changes: ┌─ renderDistance: 16 → 10 └─ highest per-frame cost on this tier at current load ┌─ clouds: fancy → fast └─ minor visual cost, cheaper to render Preserved (kept at current quality): ✓ shadows ✓ mipmaps ✓ particles Apply these changes: npm run apply Undo everything: npm run restore

The agent loop

Perceive → plan → act → reflect, for the app you're actually using

In watch mode, NVPilot runs this cycle in real time: it detects the foreground app, optimizes for it, and reverts everything when you switch away or quit.

1 · Perceive

Reads GPU telemetry via nvidia-smi, classifies your GPU tier, and captures game settings, power state, and background processes.

src/drivers/

2 · Plan

A local Ollama model proposes a plan as structured JSON — or the built-in rule engine decides, so it always works without an LLM.

src/planners/

3 · Act

Every action is validated and clamped in code, then applied — with its inverse written to the journal before the next action runs.

src/core/executor.ts

4 · Reflect

Re-perceives the system and verifies each change actually landed, reporting setting-by-setting what changed and what didn't.

src/core/agent.ts

Scope

The full system, reasoned about together

Background apps, process priority, power plans, and game configs are planned as one problem — not tuned in isolation.

Layer	What it reads	What it changes
GPU	Utilization, VRAM, temperature, power draw (nvidia-smi)	Nothing — telemetry only
Game	Current graphics settings, with tier-relative guidance	Render distance, shadows, clouds, mipmaps, particles (Minecraft; registry ready for more games)
System	Running processes and memory usage	Process priority; optional background-app cleanup (opt-in via --allow-close)
Power	Active power plan or profile	Switches to a performance plan (powercfg on Windows; powerprofilesctl / cpufreq on Linux)

Design principles

Built to be trusted with your machine

Reversibility

Every change carries its inverse

Each mutation is recorded in a journal (~/.nvpilot/journal.json) together with its inverse before the next action runs. npm run restore, Ctrl+C in watch mode, or switching apps replays the inverses.

Game configs are additionally backed up before the first write. The one exception is closing background apps — which is exactly why it's off by default.

Guardrails

The LLM plans. The code decides.

The perceived state goes to a local Ollama model, which proposes actions as structured JSON. Every action is validated and clamped in code: unknown settings rejected, values clamped to legal ranges, protected processes always refused.

If Ollama is unreachable or its output fails validation, NVPilot falls back to the deterministic rule engine — the tool always works without an LLM.

Quickstart

Analyze first. Nothing changes until you say so.

Needs Node.js 18+, an NVIDIA GPU with drivers (nvidia-smi on PATH), and Windows 10/11 or Linux. Ollama is optional.

shell

git clone https://github.com/Kurisuo/NVPilot.git
cd NVPilot
npm install

npm run analyze    # read system state, print recommendations, change nothing
npm run apply      # apply recommended optimizations once (journaled, reversible)
npm run watch      # real-time agent: watch the foreground app, optimize for it
npm run restore    # revert every change NVPilot has made

# optional, for the LLM planner:
ollama pull nemotron-mini

--no-llmSkip Ollama and use the deterministic rule engine.

--allow-closePermit closing background apps from the safe-to-close allowlist — off by default, because closing is the one action that can't be auto-reverted.

--interval <ms>Foreground poll interval in watch mode (default 2000).

NemoClaw / external agents

Drive it from another agent

NVPilot exposes its capabilities as JSON-schema tool definitions (--tools-json) so an external agent runtime like NemoClaw or OpenClaw can call them. External tool calls pass through the same validation and journal as NVPilot's own planners — equally constrained, equally reversible.

shell

npx ts-node src/index.ts --tools-json   # emit tool definitions for an agent runtime