Pit Engineer

Status: alpha. Built for my own use with iRacing; works end to end but hasn't been tested across different setups.

AI-powered race engineer assistant for iRacing. Reads telemetry in real time, analyzes each lap, and delivers voice + text feedback — like a real engineer on the radio.

Requirements

• Windows 10/11
• Python 3.11+
• iRacing (must be running for telemetry)
• Anthropic API key (get one here)

Setup

pip install -r requirements.txt

Copy config/settings.example.json to config/settings.json and add your Anthropic API key (or launch the app and go to the tray icon → Settings — it writes the key to config/settings.json for you). That file is gitignored so the key never gets committed. Alternatively, set the ANTHROPIC_API_KEY environment variable — it takes precedence over the file.

Run

python main.py

The overlay appears on screen. Start iRacing — the status line updates to "Connected" once telemetry is detected.

How it works

1. Telemetry daemon polls iRacing shared memory at 60hz
2. On each lap boundary, samples are finalized and analyzed
3. The lap is split into 3 sectors; deltas vs the reference lap are computed
4. A structured summary is sent to Claude Haiku
5. The engineer's response appears in the overlay and is read aloud

Testing

The analysis pipeline (analysis/, telemetry/lap_recorder.py) is pure Python with no dependency on iRacing, PyQt6, or the Anthropic API, so it can be tested offline with synthetic telemetry — no sim session required.

python -m venv .venv
.venv\Scripts\pip install -r requirements-dev.txt
.venv\Scripts\pytest -v

Test data is built in-memory via tests/factories.py (make_lap, smooth_corner_steering, ...) rather than requiring recorded .ibt files. tests/test_lap_validator.py covers analysis/lap_validator.py's historical-best rejection rules (near-stop, genuine off-track excursions) including a regression test for a fixed bug where a flat 180° steering threshold used to false-positive on tight hairpins.

Settings (config/settings.json)

Key	Default	Description
reference_mode	vs_best	vs_best (historical best only, session best as fallback when historical has no corner telemetry) or vs_both (historical + session best always shown together)
hotkey	F8	Press to re-analyze the last completed lap
tts_enabled	true	Enable/disable voice
tts_voice_index	0	Windows TTS voice index
overlay_opacity	0.85	Overlay transparency (0.3–1.0)
anthropic_api_key	""	Your Anthropic API key

File structure

pit-engineer/
├── main.py                  # Entry point
├── telemetry/
│   ├── daemon.py            # iRacing polling loop
│   └── lap_recorder.py      # Per-lap sample storage
├── analysis/
│   ├── comparator.py        # Sector delta computation
│   ├── lap_validator.py     # Spin/crash rejection for historical-best laps
│   └── insight_generator.py # Claude API integration
├── output/
│   ├── tts.py               # edge-tts + playsound voice output
│   └── overlay.py           # PyQt6 HUD overlay
├── config/
│   ├── settings.json        # User preferences (gitignored, has your API key)
│   └── settings.example.json
├── tests/                   # pytest suite — no iRacing/PyQt6 required
└── requirements.txt