LinuxPerfAdvisor

Describe a performance problem, paste your profiler output (perf, AMD uProf, or Intel VTune), and get back the diagnostic skill that applies, exactly what to run next, and what to fix — grounded in a registry of 78 skills (60 AMD EPYC + 18 Intel Xeon) and the authoritative profiler docs.

The engine is deterministic (rule-based routing over a multi-vendor decision matrix) and works with no API key. If an OPENAI_API_KEY is set, an LLM refine step adds a root-cause hypothesis and sharper next steps on top.

How it works

flowchart LR
  UI["React UI: problem + paste"] -->|"POST /api/analyze"| API[FastAPI]
  API --> Parse["Parsers: perf stat / c2c / uProf / VTune / generic"]
  Parse --> Norm["Vendor-neutral metric normalization"]
  Norm --> Engine["Rule engine (vendor-filtered) + theme ladders"]
  Engine --> Cand["Ranked skills + evidence"]
  Cand --> LLM["OpenAI refine (optional)"]
  LLM --> Resp["Recommendations"]
  Resp --> UI
  Registry["skills.json (AMD 60 + Intel 18)"] --> Engine

Loading

Features: multi-vendor (AMD uProf + Intel VTune + perf), per-skill vendor tagging, cross-cutting theme lenses (ordered investigation ladders), an iterative loop (each new paste narrows the diagnosis via a session timeline), a grounded uProf command builder, PII redaction before any LLM call, inline matched-metric highlighting, a clickable decision map, a skill browser, and Markdown report export.

Documentation

Detailed guides live in docs/:

Guide	For
docs/README.md	Full documentation index
docs/USER_GUIDE.md	UI features and a worked example
docs/ARCHITECTURE.md	Code layout and extending skills
docs/API.md	REST API reference
docs/DEPLOYMENT.md	Team / server deployment
docs/BUILD_BINARY.md	Optional standalone executable

Prerequisites

Install these before running the app:

Tool	Minimum	Used for
Python	3.10+ (3.12 recommended)	Backend API, skill generators, tests
Node.js + npm	18+ (20+ recommended)	Frontend dev server (npm install, npm run dev)

The startup scripts create a Python virtual environment automatically. You do not need to activate it manually when using ./start.ps1 or ./start.sh.

On Linux, ensure start.sh has LF line endings (the repo ships .gitattributes for this). If you see /usr/bin/env: 'bash\r', re-checkout the file or run sed -i 's/\r$//' start.sh.

Quickstart

One command (recommended)

Sets up venv + deps, generates skill/uProf artifacts if missing, and launches both the backend (http://localhost:8000) and frontend (http://localhost:5173):

# Windows (PowerShell) — opens two terminal windows
./start.ps1

# macOS / Linux — single terminal; Ctrl+C stops both servers
chmod +x start.sh   # first time only
./start.sh

Flags:

• Windows: ./start.ps1 -SkipInstall / -NoFrontend
• Linux/macOS: SKIP_INSTALL=1 ./start.sh / NO_FRONTEND=1 ./start.sh

Open http://localhost:5173 in your browser. API docs: http://localhost:8000/docs.

Manual setup (equivalent)

Backend

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate   |   Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env        # optional: add OPENAI_API_KEY to enable LLM refine
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm install
cp .env.example .env        # VITE_API_BASE=http://localhost:8000
npm run dev

Usage

1. Describe the problem and (optionally) pick the CPU vendor + system context.
2. Paste perf stat / perf c2c / AMDuProfCLI report / vtune -report output — or click a Load example button.
3. Click Analyze for ranked skills with evidence, copy-ready "run next" commands, and fixes.
4. Run a command, paste the new output, and Analyze again — the session timeline narrows the diagnosis. Export report saves a Markdown summary.

For a full walkthrough of every panel (theme lens, decision map, skill browser, uProf command builder) and a worked example, see docs/USER_GUIDE.md.

Configuration

Copy backend/.env.example to backend/.env and adjust as needed:

Variable	Default	Purpose
OPENAI_API_KEY	(empty)	Enables LLM refine when set; app is fully functional without it
OPENAI_MODEL	gpt-4o-mini	OpenAI model for refine step
OPENAI_BASE_URL	(empty)	Custom OpenAI-compatible API base URL
MAX_INPUT_BYTES	262144	Max pasted output size (bytes)
LLM_TIMEOUT_S	30	LLM request timeout (seconds)
CORS_ORIGINS	http://localhost:5173,...	Allowed frontend origins (dev server)

Frontend API URL (dev only): set VITE_API_BASE in frontend/.env (see frontend/.env.example). Default points at http://localhost:8000.

Troubleshooting

Symptom	Likely cause	Fix
node: command not found	Node.js not installed	Install Node 18+ and re-run the startup script
python: command not found	Python not on PATH	Install Python 3.10+; on Linux use python3
/usr/bin/env: 'bash\r'	CRLF line endings in start.sh	Re-clone or convert to LF (see Prerequisites)
Frontend loads but Analyze fails	Backend not running or wrong port	Ensure backend is on :8000; check frontend/.env
CORS error in browser	Frontend origin not allowed	Add your origin to CORS_ORIGINS in backend/.env
Port 8000 already in use	Another process on 8000	Stop the other process or change the uvicorn port
LLM refine never runs	No API key	Set OPENAI_API_KEY in backend/.env and restart backend

Windows note: ./start.ps1 launches backend and frontend in separate PowerShell windows. Close those windows (or Ctrl+C in each) to stop the servers.

Security note: The default setup binds to localhost only and is intended for local diagnostic use. Session data is kept in memory and is not persisted across restarts. Pasted profiler output is redacted before any LLM call.

Maintenance

The skill registry is authored in backend/tools/skill_data.py and generated:

cd backend
python tools/gen_skills.py       # -> skills/**/*.md (human-facing)
python tools/gen_cheatsheet.py   # -> skills.json, themes.json, references/*.md (+ coverage asserts)
python tools/gen_uprof_db.py     # -> uprof_db.json (uProf debugging database)
python -m pytest -q              # tests + coverage asserts

• Skills live in backend/skills/**/*.md; reference docs in backend/references/ (incl. the uProf knowledge base under references/uprof/).
• Authoritative external sources are listed in backend/references/sources.md.
• The uProf debugging database (backend/uprof_db.json) maps a symptom/metric to an exact, family-gated AMDuProfCLI collect/report command.

Standalone binary (optional, not shipped)

This repo does not include pre-built executables. The recommended way to run the app is the quickstart above (Python + Node dev servers).

If you need a single double-clickable binary (no separate Python/Node install for end users), the project includes optional build scripts. See docs/BUILD_BINARY.md for step-by-step commands to build LinuxPerfAdvisor.exe (Windows) or LinuxPerfAdvisor (Linux) on your own machine.

License

Proprietary — internal use only. Copyright (c) 2026 The LinuxPerfAdvisor Authors. All rights reserved. See LICENSE for the full terms.

No permission is granted to use, copy, modify, or distribute this software without prior written consent of the copyright holder. Third-party dependencies remain governed by their own respective licenses. Contact the repository owner for licensing inquiries.