Interactive TUI

⚠ Known stale (2026-08-20). The TUI predates the CLI rework and is not kept current with newer commands (e.g. cook-volatile, health, checksum, scan-vins, the schema-4.5 recipe format). It still works for the basics. The CLI is the current focus; the TUI will be reworked later. This page may be out of date.

OpenRemap ships with a full interactive Terminal User Interface built with Textual. It exposes every core feature — identify, scan, cook, tune, validate — without touching the command line.

Launch it:

openremap          # no arguments → opens the TUI
openremap-tui      # dedicated entry point (identical)

No server, no database, no internet connection required.

Layout

The screen is split into two regions:

Click a sidebar button or press 1–7 on your keyboard to switch panels.

Panels

⚡ Identify — 1

Single-file ECU binary identification.

Browse for a binary or type its path, then press IDENTIFY. The panel displays a result table with the following fields:

Below the identification fields the panel shows a confidence assessment:

• Tier badge — a four-dot indicator: ●●●● High, ●●●○ Medium, ●●○○ Low, ●○○○ Suspicious, ○○○○ Unknown
• Numeric score — the raw point total from signal analysis.
• Signal breakdown — each signal that contributed to the score, shown with a green ▲ (positive) or red ▼ (negative) marker and its point delta.
• Warnings — any ⚠ notes emitted by the confidence engine.

⬡ Scan — 2

Batch-scan an entire directory of ECU binaries.

Browse for a directory (or type its path), then press SCAN. Every file is identified and classified. Results appear in a DataTable with these columns:

Category colour coding:

Toggle buttons:

• By Manufacturer — groups organised output by manufacturer only (default).
• Detailed — groups by manufacturer and family, creating deeper subfolders.

ORGANISE button — enabled after a scan completes. Pressing it moves every scanned file into manufacturer/family subfolders under the ECUs/ working directory. Unmatched files go to <Manufacturer>/Unmatched, contested files to Contested/, unknowns to Unknown/, and unsupported files to Unsupported/.

⚗ Cook — 3

Diff two binaries to produce a .remap recipe file.

Three file inputs are arranged in columns:

Each input has a Browse button (or Save as… for the output). Press COOK to diff the two binaries. The result panel shows the generated recipe summary — number of instructions, byte ranges, and metadata.

⟳ Tune — 4

One-shot workflow: validate → apply → verify.

Three file inputs:

Press TUNE to run the full three-phase process:

1. Phase 1 — Pre-flight check (validate before): confirms that original bytes exist at the recorded offsets.
2. Phase 2 — Apply recipe: writes modified bytes into a copy of the target.
3. Phase 3 — Post-tune verification (validate after): confirms that modified bytes are now present at the expected offsets.

The result panel shows a phase checklist (✅ / ❌ / ○) at the top, followed by a status summary. On success the output path is displayed along with a prominent checksum warning — OpenRemap does not correct checksums, so the output must be processed by a dedicated tool (ECM Titanium, WinOLS, MPPS, Flex, etc.) before flashing.

If any phase fails, a diagnostic message explains the failure and suggests the appropriate Validate mode to investigate further.

✔ Validate — 5

Run individual validation steps against a binary and recipe pair.

Two file inputs:

Three mode buttons select the validation type:

The result panel shows per-instruction pass/fail status with offset, expected bytes, and actual bytes for any failures.

≡ Families — 6

Read-only reference panel listing every ECU family registered in the current installation. Displays a DataTable with columns:

The table is sorted by manufacturer and family. This is the same information printed by the openremap families CLI command.

ℹ About — 7

Project information panel showing:

• Version number
• Project description
• Registered extractor and family counts
• Links to GitHub and PyPI
• CLI quick-reference (every command with an example invocation)
• Checksum warning reminder

Keyboard shortcuts

These are standard Textual key bindings.

File dialogs

Browse buttons open a native file dialog appropriate for your platform:

The TUI tries zenity first, then falls back to kdialog. If neither is installed (and you are not on macOS or Windows), the dialog silently returns nothing and the panel displays a notice:

No file dialog available. Install zenity (Linux) or kdialog (KDE) and retry.

You can always type or paste a path directly into the text input and press Enter — the file dialog is a convenience, not a requirement.

File type filters are applied automatically:

• Binary inputs filter for *.bin, *.ori, *.hex (with an "All files" fallback).
• Recipe inputs filter for *.remap, *.json (with an "All files" fallback).
• Save-as dialogs use the same filters as their corresponding input type.

Working directories

On first launch the TUI creates a working directory tree for default file dialog locations:

Inside the base directory three subdirectories are created:

These directories are only used as starting points for file dialogs — you are free to browse anywhere on your filesystem.

← Back to documentation index