agent-tune

Tune your car with KTuner and an AI assistant.

A VEHRA project.

KTuner lets you change almost anything in your car's ECU. Knowing what to change is the hard part, and usually that means paying a tuner.

agent-tune does the tuner's homework. Record a few full-throttle runs with KTuner and give the log to your AI assistant. It checks for knock, compares the fuel and ignition timing your engine actually got with what makes power, and comes back with specific edits: which table, which cells, from what value to what. Say yes, and agent-tune writes them into a new tune file. You open it in KTuner, look it over, and flash it. Then you drive the same runs again and see what changed.

It never flashes the car and never touches your original tune file.

agent-tune works with KTuner hardware and the KTuner app. It is not affiliated with or endorsed by KTuner.

What you need

• A Honda with a KTuner, and the KTuner app on a Windows laptop.

• An AI assistant that can use skills or MCP, such as Claude Code or Codex. Optional: every step also works as a command.

Related MCP server: Race MCP Server

Get started

Install it with uv (needs Python 3.11 or newer):

uv tool install "vehra-agent-tune[mcp]"

The package is called vehra-agent-tune on PyPI; the command it installs is agent-tune. Leave out [mcp] if you won't connect an AI assistant. To install the latest development version instead:

uv tool install "vehra-agent-tune[mcp] @ git+https://github.com/VehraLabs/agent-tune"

With an AI assistant

Connect it once:

Then ask it something like "I have a KTuner on my Honda and I want more power. What should I do first?" It will tell you how to drive for a log, check what you bring back, and propose edits for you to approve.

On your own

agent-tune guide power                          # how to drive and record for power
agent-tune check-log drive.csv --goal power     # does the log have what's needed?
agent-tune analyze drive.csv --findings         # knock, fuel, timing, room to improve
agent-tune tune check stock.kcl                 # can this tune file be edited?
agent-tune tune set stock.kcl --add "wot-h-6000-600=0.3" -o step-1.kcl --dry-run   # preview an edit

Without --dry-run it writes step-1.kcl and step-1.manifest.json, which lists every value it changed. After flashing and driving the same runs again, agent-tune compare before.csv after.csv shows the difference.

A few terms

• Datalog: a recording of your engine's sensors while you drive. KTuner records it; export it to CSV for agent-tune.

• Full-throttle run (or pull): accelerating with the pedal all the way down through the rev range. This is where power is made, so it's what power tuning looks at.

• AFR (air-fuel ratio): how much air there is for each part of fuel. Lower is richer (more fuel). Naturally aspirated engines usually make the most power around 12.5 to 13.2 at full throttle.

• Knock: uncontrolled combustion that can damage an engine. Any change that causes knock gets undone.

• Ignition timing: when the spark fires. A little more can add power, but too much causes knock.

• Tune file (.kcl): the file KTuner flashes to your car. Flashing means writing it to the car's computer.

What's supported

When agent-tune records live data itself, it reads RPM, measured and commanded lambda (AFR), MAF (g/s and Hz), MAP, throttle position and commanded throttle, ignition timing, short and long-term fuel trims, coolant and intake temperature, speed, gear, intake and exhaust cam angles (actual and commanded), FP1, battery voltage, knock control and fuel status. These match what KTuner displays. Knock count and VTEC state are not available that way yet, so record with the KTuner app when you need them. Any timing change needs the knock count.

Adding your car

Each new ECU is added once someone confirms it works. Here is how to check yours.

• Datalogs. Anything that reads a KTuner CSV export already works on any car. For recording with agent-tune itself, agent-tune log keeps every reply the dongle sends, including ones it doesn't recognize yet, so they can be matched against a KTuner datalog later. You can also give it your own channel layout with --platform my-car.json, starting from the bundled file.

• Tune files. agent-tune tune check your.kcl says whether your file is from a verified family. If not, it checks whether the known layout looks right for it (timing in a sensible range, the airflow curve increasing, rev limits in order, and so on). If it does, --unverified lets you read it and write a test file. Change one value, open the new file in KTuner, and confirm that exactly that value changed. Files written this way carry a warning. Don't flash anything until KTuner shows exactly what you expect.

If it works on your car, open an issue or a pull request with the fingerprint from tune check and your car details so it can be added. CONTRIBUTING.md has the steps. Please never share tune files, VINs or serial numbers.

Commands

Value ids look like ign-max-h-6000-100 (table, cam, RPM, column) and accept wildcards such as wot-h-6000-*. Add --unverified to tune commands for a file outside the verified families. tune set never overwrites the file you start from.

Safety

Tuning for power can damage an engine. Ignition timing is where engines get hurt.

• Keep your original tune and a stock backup. Flash only with a healthy battery or a charger connected, and never interrupt a flash.

• Change timing in small steps (1 degree or less), only where your logs show no knock, and never where the full-throttle AFR is lean.

• Judge every change with the same full-throttle runs in the same gear, at a similar temperature, and only where it is legal and safe.

• You are responsible for what you flash and for following the emissions and road laws where you drive.

For developers

uv sync --extra mcp
uv run pytest

CONTRIBUTING.md explains how to add a car or a tune-file family. SECURITY.md states exactly what the tool does and doesn't send to the car. AGENTS.md is the guide for AI agents changing this code.

License

MIT. See LICENSE. The VEHRA name and logo are trademarks of Vehra and are not covered by the license; see docs/brand.