PC-Pilot

Your AI-powered PC shopping assistant. Scans your current hardware, benchmarks performance, identifies bottlenecks, and hunts the web for your perfect upgrade — all through natural conversation with Claude.

---

What It Does

1. Scans your current hardware specs automatically
2. Benchmarks your CPU, RAM, and storage performance
3. Interviews you about what you need and your budget
4. Diagnoses where your current PC falls short (with a letter-grade Report Card)
5. Hunts the web for the best deals matching your requirements
6. Recommends top picks with full price/performance analysis

---

Requirements

• Claude Code (Anthropic's CLI tool)
• Python 3.8+
• Dependencies listed in requirements.txt

That's it. No extra API keys, no accounts, no complicated setup.

---

Setup (Step by Step)

1. Install Claude Code

If you don't have Claude Code yet, install it via npm:

npm install -g @anthropic-ai/claude-code

Then authenticate:

claude login

Need help? See the Claude Code docs.

2. Install Python (if you don't have it)

You need Python 3.8 or newer. Check with:

python --version

If you don't have it:

• Windows: Download from python.org and check "Add to PATH" during install.
• macOS: brew install python3 (or download from python.org)
• Linux: sudo apt install python3 (Ubuntu/Debian) or sudo dnf install python3 (Fedora)

3. Get the project

git clone <repo-url>
cd Speed-test

Or download the ZIP and extract it.

4. Install dependencies

pip install -r requirements.txt

This installs psutil which gives the benchmark script enhanced details like CPU frequency, available RAM, and disk usage. The core scripts work without it, but you get richer output with it installed.

5. (Optional) Fill in your wishlist

Open wishlist.yaml in any text editor and fill in your budget, use case, and preferences. This is totally optional — if you skip it, Claude will just ask you these questions during the conversation.

---

How to Run

The Easy Way (Recommended)

Open a terminal in the project folder and launch Claude Code:

cd Speed-test
claude

That's it. Claude reads the CLAUDE.md guide automatically and knows exactly what to do. Just tell it what you need:

• "Scan my PC and tell me what I've got"
• "I need a gaming PC under $1,500"
• "What should I upgrade first?"
• "Find me the best prebuilt with an RTX 5070"
• "Build me a video editing workstation for $2,000"
• "Is my PC good enough for streaming?"

Claude will run the scanner and benchmarks for you, then walk you through the full recommendation process.

Running the Scripts Yourself

You don't have to run these manually (Claude handles it), but you can:

# Scan your hardware — prints a report and saves JSON to results/my_specs.json
python detect.py

# Scan hardware — output raw JSON only
python detect.py --json

# Scan hardware — save JSON silently (no terminal output)
python detect.py --quiet

# Run benchmarks — takes 2-4 minutes, saves to results/benchmark.json
python benchmark.py

What the Output Looks Like

Hardware scan prints a formatted report like this:

  ╔════════════════════════════════════════════════════════════╗
  ║                  PC-PILOT  HARDWARE  SCAN                  ║
  ║           Know your machine. Find your upgrade.            ║
  ╚════════════════════════════════════════════════════════════╝

    Form Factor:           Desktop

  ──────────────────────────────────────────────────────────────
  PROCESSOR (CPU)
  ──────────────────────────────────────────────────────────────
    Model                    Intel(R) Core(TM) i9-14900KF
    Cores / Threads          24C / 32T
    Socket                   LGA 1700
    ...

Benchmarks score your PC out of 10,000 and assign a tier:

  YOUR SCORE:  17,398 / 10,000
  TIER:        MONSTER
  Top 1% -- Extreme enthusiast / workstation

---

How It Works

The magic is in CLAUDE.md — a structured guide that teaches Claude Code how to be a PC hardware consultant. When you open this project in Claude Code, it follows a 6-phase process:

SCAN  -->  INTERVIEW  -->  DIAGNOSE  -->  HUNT  -->  COMPARE  -->  RECOMMEND
 |            |               |             |           |              |
 v            v               v             v           v              v
Detect     Ask about       Grade each    Search      Rank by       Present
hardware   needs &         component     the web     value &       top picks
specs      budget          A+ to F       for deals   performance   with links

Results are saved to the results/ folder for easy reference.

---

Project Structure

Speed-test/
├── CLAUDE.md            # The AI brain — teaches Claude the PC shopping process
├── README.md            # You're reading it
├── requirements.txt     # Python dependencies (pip install -r requirements.txt)
├── detect.py            # Cross-platform hardware scanner (Win/Mac/Linux)
├── benchmark.py         # CPU, RAM, and disk performance benchmarks
├── wishlist.yaml        # Your preferences template (optional)
├── ram_check.ps1        # Quick RAM usage check (Windows PowerShell)
└── results/             # Output folder (auto-created on first run)
    ├── my_specs.json    # Hardware scan results
    ├── benchmark.json   # Benchmark scores
    └── recommendation.md  # Final recommendation report

---

Platform Support

Platform	Hardware Scan	Benchmarks	Web Search
Windows 10/11	Yes	Yes	Yes
macOS	Yes	Yes	Yes
Linux	Yes	Yes	Yes

What gets detected: CPU (model, cores, threads, clock, socket), GPU (model, VRAM), RAM (total, type, speed, stick config), Storage (model, capacity, NVMe vs SATA vs HDD), Motherboard (manufacturer, model), OS, and form factor (desktop vs laptop).

Known limitations:

• PSU wattage can't be detected via software — check the physical label.
• GPU VRAM for cards >4 GB may use a lookup table if nvidia-smi isn't available (covers all major NVIDIA/AMD/Intel Arc GPUs).
• CPU clock shows base frequency from BIOS, not turbo/boost speed.

---

Tips

• Be specific about your use case. "Gaming" is good. "1440p 144Hz competitive FPS" is better.
• Set a real budget. Include monitor/peripherals if you need those too.
• Mention your timeline. If you can wait, Claude might suggest holding for a sale.
• Ask follow-ups. Claude can deep-dive into any recommendation, compare two specific models, or explain trade-offs.
• Check your PSU. The scanner can't detect PSU wattage. If you're upgrading, check the label on your power supply and tell Claude.

---

Troubleshooting

python command not found Try python3 instead. On Windows, you may need to reinstall Python and check "Add to PATH."

Unicode errors on Windows (box-drawing characters) The scripts handle this automatically, but if you see garbled output, try running in Windows Terminal (not the old cmd.exe).

nvidia-smi not found This only matters for NVIDIA GPU VRAM detection. The scanner falls back to a built-in lookup table for all common GPUs. If your GPU model is missing, VRAM will show as null — Claude will look it up for you.

Benchmark takes too long Normal runtime is 2-4 minutes. If it hangs, it's likely on the disk benchmark (writes a 512 MB test file). Make sure you have at least 1 GB of free temp space.

---

Contributing

Found a bug? Have an idea? Open an issue or PR.

License

MIT