turbohex 0.1.0

turbohex is an interactive terminal hex viewer for exploring binary files with live decoding. It combines a fast hex/ASCII view, selection tools, and a decode panel that supports both built-in and plugin decoders (Lua + WASM).

Table of Contents

• Highlights
• Why turbohex
• Installation
• Basic Usage
• Keybindings
• Plugin Decoders
• Decoder Examples
• Development
• Dependencies

Highlights

• Fast TUI hex viewer with color-coded bytes and ASCII column
• Byte and bit-level selection modes
• Live decode panel (integers, floats, strings, timestamps, and more)
• Range-aware decode fields (offset/length) with byte highlighting
• Decoder focus with Tab / Shift+Tab and visual markers in hex view
• Little-endian / big-endian toggle
• Built-in + plugin decoders with runtime enable/disable settings
• Memory-mapped I/O for large files

Why turbohex

xxd and hexdump are excellent for quick dumps and scripting, but they are static output tools. turbohex is built for interactive reverse engineering and protocol inspection.

• Interactive cursoring and selection (byte and bit modes)
• Live decode panel that updates as selection changes
• Field-to-byte mapping via offset/length highlighting
• Endianness toggling and decoder focus/navigation in the UI
• Extensible decoders with Lua and WASM plugins

vs Other Hex Viewers

Many hex viewers can inspect bytes well; turbohex is optimized for terminal- native, decoder-driven analysis loops.

• Terminal-first workflow: no GUI dependency, fast startup, scriptable usage
• Interactive decoding: decode panel updates immediately as selection changes
• Field mapping: decoder offset/length values highlight exact source bytes
• Plugin ergonomics: lightweight Lua decoders plus high-performance WASM option
• LLM-friendly setup: turbohex --skills provides agent-ready decoder ABI docs

Installation

Prerequisite: Rust toolchain (cargo, rustc).

# Build a release binary
cargo build --release

# Run without installing
./target/release/turbohex <file>

# Or install to your PATH
cargo install --path .
turbohex <file>

Basic Usage

# Open a file
turbohex <file>

# Open included sample/test data
turbohex testdata/sample.json
turbohex testdata/http_request.bin

# Show CLI help
turbohex --help

Keybindings

Plugin Decoders

Place decoder files in:

~/.config/turbohex/decoders/

• .lua files are loaded as Lua decoders
• .wasm files are loaded as WASM decoders

LLM Agent Setup (--skills)

turbohex --skills prints a complete plugin development guide (Lua/WASM ABI, parameter support, examples, and usage) designed to be pasted into an LLM agent workflow.

Why this helps:

• Reduces back-and-forth by giving agents ABI details up front
• Improves decoder correctness (expected JSON fields and endian semantics)
• Makes outputs actionable with install/build instructions for decoder paths
• Keeps generated plugins aligned with turbohex UI behavior

# Print guide in terminal
turbohex --skills

# Save and attach/paste to an agent
turbohex --skills > turbohex-skills.md

Suggested agent prompt starter:

Use the attached turbohex skills guide to build a decoder plugin for <format>.
Target Lua (or WASM), return fields as {label, value, optional offset, optional length},
and include install/build steps for ~/.config/turbohex/decoders/.

Lua Decoder ABI

Create a .lua file with a global decode(bytes, endian, params) function:

function decode(bytes, endian, params)
    return {
        {label = "Field", value = "decoded"},
        {label = "Header", value = "0xABCD", offset = 0, length = 2},
    }
end

Field contract:

• label (string, required)
• value (string, required)
• offset (number, optional, 0-based from selection start)
• length (number, optional)

WASM Decoder ABI

WASM modules should export:

Endian values:

• 0 = little-endian
• 1 = big-endian

Decode return JSON format:

[{"label":"...","value":"...","offset":0,"length":4}]

Decoder Examples

Build and install the Rust example:

cd examples/wasm-decoder-rust
./build.sh

Or manually:

rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --release
cp target/wasm32-unknown-unknown/release/decoder_example.wasm ~/.config/turbohex/decoders/

Development

# Dev build
cargo build

# Release build
cargo build --release

# Run
cargo run -- <file>

Development Setup

• Rust toolchain (cargo, rustc)
• Developed with Claude Code

Dependencies

• ratatui + crossterm
• clap
• memmap2
• mlua
• wasmtime

Feedback

If you find anything incorrect, unclear, or missing, or want to suggest a new feature, please open a GitHub issue or submit a pull request.