obd-scanner
A desktop diagnostic app that reads every answering module of a car over KWP2000, UDS and OBD-II, with an embedded Claude agent that gets 18 MCP tools and no serial port. For automotive engineers who want manufacturer-level reads from an ELM327-class adapter, and AI engineers who want a worked example of an agent bounded by a tool layer and a PreToolUse hook.
- Repository
- darblinko/q50-obd-scanner
- Revision
7cfe6d9- Measured
- 2026-11-05 (tests), 2026-10-17 (field session)
- License
- Apache-2.0; two OBDb-derived PID tables CC-BY-SA-4.0
Problem
A 2017 Infiniti Q50 3.0t had intermittent heavy steering. Its rack electric power steering (EPS) module answers on CAN IDs 742/762 with Nissan KWP2000 local identifiers (21 xx) after a 10 C0 session request. A generic OBD-II reader queries the engine through modes 01 and 03 and never reaches it, and no public source gives EPS identifiers for the Q50.
An AI agent that helps with this work needs live car data and the ability to change the decoding code. Given a shell and the serial port, the same agent could also send ECU reset, security access or write services to the car.
How it works
The GUI and the agent share one session worker thread, and every request to the car passes one allowlist. The agent reaches the car through an in-process MCP server; its file and shell tools pass a PreToolUse guard hook first.
flowchart TB
user["User"] --> pages["GUI pages"]
user --> panel["MechanIQ panel"]
panel --> agent["Claude Agent SDK client"]
agent --> hook{{"PreToolUse guard hook"}}
hook -->|allowed| files["Read, Edit, Write, Bash inside the project"]
hook --> mcp["In-process MCP server q50, 18 tools"]
mcp --> session["Session worker thread"]
pages --> session
session --> gate{{"Request allowlist"}}
gate --> transport["ElmTransport or SimulatedTransport"]
transport --> adapter["ELM327 or STN adapter"]
adapter --> car["Vehicle CAN: KWP2000, UDS, OBD-II"]
Protocol layer
The ELM driver sets up the adapter with ATE0 ATL0 ATS1 ATH1 ATAT1, selects HS-CAN 500 kbps or Ford MS-CAN with STN STP commands, addresses each module with ATSH and ATCRA, and reassembles ISO 15765-2 frames per CAN ID. A 7F xx 78 response pending reply is retried once with the longest ELM timeout.
Request gate
Allowed: OBD modes 01, 02, 03, 05, 06, 07, 09, 0A; services 17, 18, 19, 1A, 21, 22; 3E; and 10 with sub-functions 01, 03, 81, 89 or C0. Clearing codes (04, 14) needs a confirmation dialog on the Trouble Codes page. Everything else raises RequestBlocked. Discovery probes known modules with 3E 00, then the vehicle profile's fallback probes (Q50: 10 81 default session and 21 83; Mustang: 22 F190). The sweep of unknown addresses sends only 3E 00. Neither transmits on a response ID.
Tool boundary and guard hook
The agent runs with permission prompts off, so the PreToolUse hook is its boundary. It denies file writes outside the project, Bash that opens a serial device, access to .env files and the settings file that holds the API key, git push, git reset --hard and git clean, and all PowerShell. Bash is split into shell segments with shlex, and redirect targets are checked as writes. The agent's raw_read tool sends one request through the same allowlist without the clear permission. apply_change runs the related tests before it reloads and commits an edit.
Measured results
One field session on the Q50 with a vLinker FS (STN1170) at 115200 baud, about 16 ms per command.
Safety tests in the suite at revision 7cfe6d9, all passing. The guard cases include allowed commands as controls, so a guard that denies everything would fail them.
Run it
git clone https://github.com/darblinko/q50-obd-scanner cd q50-obd-scanneruv sync --frozenQT_QPA_PLATFORM=offscreen uv run pytest -quv run python -m q50diag --sim
Limitations
- Field data covers one car, one adapter and one session. The heavy steering complaint was not reproduced while EPS data was captured.
- Six of the eight decoded EPS fields (velocity, assist load, driver torque, temperature, assist limit, motor speed) are inferences.
- The OBD port on this Q50 is gatewayed: 0 broadcast frames in a 5 s unfiltered monitor, so every value is polled.
- The Mustang S550 profiles come from public address lists; the repository holds no field capture from a Mustang.
- The guard hook catches agent mistakes and does not sandbox the agent: a script the agent writes can do anything its interpreter allows.