{"id":50775626,"url":"https://github.com/nmbr7/turbohex","last_synced_at":"2026-06-11T23:02:22.497Z","repository":{"id":347439452,"uuid":"1194088270","full_name":"nmbr7/turbohex","owner":"nmbr7","description":"TUI based hex-viewer with customizable decode UI with Wasm plugin system.","archived":false,"fork":false,"pushed_at":"2026-04-08T21:14:25.000Z","size":258,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T16:25:12.437Z","etag":null,"topics":["decoder","decoder-utility","hexviewer","lua","ratatui","rust","terminal","tui","wasm"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nmbr7.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-27T22:54:19.000Z","updated_at":"2026-04-14T11:45:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nmbr7/turbohex","commit_stats":null,"previous_names":["nmbr7/turbohex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nmbr7/turbohex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmbr7%2Fturbohex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmbr7%2Fturbohex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmbr7%2Fturbohex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmbr7%2Fturbohex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nmbr7","download_url":"https://codeload.github.com/nmbr7/turbohex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nmbr7%2Fturbohex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34221150,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["decoder","decoder-utility","hexviewer","lua","ratatui","rust","terminal","tui","wasm"],"created_at":"2026-06-11T23:02:21.733Z","updated_at":"2026-06-11T23:02:22.489Z","avatar_url":"https://github.com/nmbr7.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eTurboHex\u003c/h1\u003e\n\n[![Rust](https://img.shields.io/badge/Rust-stable-orange)](https://www.rust-lang.org/)\n[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-blue)](#)\n[![UI](https://img.shields.io/badge/UI-Terminal%20TUI-6f42c1)](#)\n[![Decoders](https://img.shields.io/badge/Plugins-Lua%20%2B%20WASM-0ea5e9)](#)\n\n`turbohex` is an interactive terminal hex viewer for exploring binary files with\nlive decoding. It combines a fast hex/ASCII view, selection tools, and a decode\npanel that supports both built-in and plugin decoders (Lua + WASM).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"800\" alt=\"turbohex screenshot\" src=\"https://github.com/user-attachments/assets/c575f3bd-0ba8-4324-92b2-c48ea8bdb400\" /\u003e\n  \u003cbr\u003e\n  \u003cem\u003ePostgres heap page example.\u003c/em\u003e\n\u003c/p\u003e\n\n## Table of Contents\n\n- [Highlights](#highlights)\n- [Why turbohex](#why-turbohex)\n- [Installation](#installation)\n- [Basic Usage](#basic-usage)\n- [Keybindings](#keybindings)\n- [Plugin Decoders](#plugin-decoders)\n- [Decoder Examples](#decoder-examples)\n- [Development](#development)\n- [Dependencies](#dependencies)\n\n## Highlights\n\n- Fast TUI hex viewer with color-coded bytes and ASCII column\n- Byte and bit-level selection modes\n- Vim-style count prefix for movement multiplication (`5→` moves 5 bytes)\n- Byte pattern search: hex bytes (`/` then `FF D8 FF`) or ASCII text\n- Search by selection (`*`) with `n`/`N` to cycle matches\n- Chunk navigation: `n`/`N` strides through repeated structures by selection size\n- Live decode panel (integers, floats, strings, timestamps, and more)\n- Range-aware decode fields (`offset`/`length`) with byte highlighting\n- Decoder focus with `Tab` / `Shift+Tab` and visual markers in hex view\n- Stats panel with per-field entropy, compressibility, and byte statistics\n- Little-endian / big-endian toggle\n- Built-in + plugin decoders with runtime enable/disable settings\n- Memory-mapped I/O for large files\n\n## Why turbohex\n\n`xxd` and `hexdump` are excellent for quick dumps and scripting, but they are\nstatic output tools. `turbohex` is built for interactive reverse engineering and\nprotocol inspection.\n\n- Interactive cursoring and selection (byte and bit modes)\n- Live decode panel that updates as selection changes\n- Field-to-byte mapping via `offset`/`length` highlighting\n- Endianness toggling and decoder focus/navigation in the UI\n- Extensible decoders with Lua and WASM plugins\n\n## vs Other Hex Viewers\n\nMany hex viewers can inspect bytes well; `turbohex` is optimized for terminal-\nnative, decoder-driven analysis loops.\n\n- **Terminal-first workflow:** no GUI dependency, fast startup, scriptable usage\n- **Interactive decoding:** decode panel updates immediately as selection changes\n- **Field mapping:** decoder `offset`/`length` values highlight exact source bytes\n- **Plugin ergonomics:** lightweight Lua decoders plus high-performance WASM option\n- **LLM-friendly setup:** `turbohex --skills` provides agent-ready decoder ABI docs\n\n## Installation\n\n### From crates.io\n\n```sh\ncargo install turbohex\n```\n\n### From source\n\n```sh\ngit clone https://github.com/nmbr7/turbohex.git\ncd turbohex\ncargo install --path .\n```\n\n## Basic Usage\n\n```sh\n# Open a file\nturbohex \u003cfile\u003e\n\n# Open included sample/test data\nturbohex testdata/sample.json\nturbohex testdata/http_request.bin\n\n# Show CLI help\nturbohex --help\n```\n\n## Keybindings\n\n| Key | Action |\n|---|---|\n| Arrow keys | Move cursor |\n| `0-9` | Count prefix (multiplies next movement) |\n| `Page Up` / `Page Down` | Scroll one page |\n| `Shift+Up` / `Shift+Down` | Fast scroll (50 rows) |\n| `Home` / `End` | Jump to start / end |\n| `g` | Goto offset (hex `0x...` or decimal) |\n| `v` | Toggle select mode |\n| `n` / `N` | Next/prev search match or chunk |\n| `/` | Search for hex bytes or ASCII text |\n| `*` | Search for selected bytes / find next match |\n| `#` | Find previous match |\n| `Esc` | Clear search / selection / decode focus |\n| `b` | Toggle byte / bit mode |\n| `e` | Toggle LE / BE |\n| `w` | Toggle 16 / 32 bytes per row |\n| `s` | Toggle stats panel |\n| `d` | Open decoder settings (enable/disable decoders) |\n| `Tab` / `Shift+Tab` | Focus next/previous decoded field |\n| `[` / `]` | Shrink / grow decode panel |\n| `{` / `}` | Scroll stats panel up / down |\n| `?` | Show help |\n| `q` | Quit |\n\n## Plugin Decoders\n\nPlace decoder files in:\n\n```text\n~/.config/turbohex/decoders/\n```\n\n- `.lua` files are loaded as Lua decoders\n- `.wasm` files are loaded as WASM decoders\n\n### LLM Agent Setup (`--skills`)\n\n`turbohex --skills` prints a complete plugin development guide (Lua/WASM ABI,\nparameter support, examples, and usage) designed to be pasted into an LLM agent\nworkflow.\n\nWhy this helps:\n\n- Reduces back-and-forth by giving agents ABI details up front\n- Improves decoder correctness (expected JSON fields and endian semantics)\n- Makes outputs actionable with install/build instructions for decoder paths\n- Keeps generated plugins aligned with turbohex UI behavior\n\n```sh\n# Print guide in terminal\nturbohex --skills\n\n# Save and attach/paste to an agent\nturbohex --skills \u003e turbohex-skills.md\n```\n\nSuggested agent prompt starter:\n\n```text\nUse the attached turbohex skills guide to build a decoder plugin for \u003cformat\u003e.\nTarget Lua (or WASM), return fields as {label, value, optional offset, optional length},\nand include install/build steps for ~/.config/turbohex/decoders/.\n```\n\n### Lua Decoder ABI\n\nCreate a `.lua` file with a global `decode(bytes, endian, params)` function:\n\n```lua\nfunction decode(bytes, endian, params)\n    return {\n        {label = \"Field\", value = \"decoded\"},\n        {label = \"Header\", value = \"0xABCD\", offset = 0, length = 2},\n    }\nend\n```\n\nField contract:\n- `label` (string, required)\n- `value` (string, required)\n- `offset` (number, optional, 0-based from selection start)\n- `length` (number, optional)\n\n### WASM Decoder ABI\n\nWASM modules should export:\n\n| Export | Signature | Purpose |\n|---|---|---|\n| `memory` | linear memory | Shared memory |\n| `alloc` | `(i32) -\u003e i32` | Allocate input/output bytes |\n| `decode` | `(ptr: i32, len: i32, endian: i32) -\u003e i32` | Return pointer to NUL-terminated JSON |\n\nEndian values:\n- `0` = little-endian\n- `1` = big-endian\n\nDecode return JSON format:\n\n```json\n[{\"label\":\"...\",\"value\":\"...\",\"offset\":0,\"length\":4}]\n```\n\n## Decoder Examples\n\n| Path | Language | Description |\n|---|---|---|\n| `examples/wasm-decoder-rust/` | Rust | File magic detection, entropy, byte stats |\n| `examples/wasm-decoder-http/` | Rust | HTTP/1.x request/response parser |\n| `examples/wasm-decoder-c/` | C | RGB/RGBA color decoder |\n\nBuild and install the Rust example:\n\n```sh\ncd examples/wasm-decoder-rust\n./build.sh\n```\n\nOr manually:\n\n```sh\nrustup target add wasm32-unknown-unknown\ncargo build --target wasm32-unknown-unknown --release\ncp target/wasm32-unknown-unknown/release/decoder_example.wasm ~/.config/turbohex/decoders/\n```\n\n## Development\n\n```sh\n# Dev build\ncargo build\n\n# Release build\ncargo build --release\n\n# Run\ncargo run -- \u003cfile\u003e\n```\n\n## Development Setup\n\n- Rust toolchain (`cargo`, `rustc`)\n- Developed with Claude Code\n\n## Dependencies\n\n- [ratatui](https://github.com/ratatui/ratatui) + [crossterm](https://github.com/crossterm-rs/crossterm)\n- [clap](https://github.com/clap-rs/clap)\n- [memmap2](https://github.com/RazrFalcon/memmap2-rs)\n- [mlua](https://github.com/mlua-rs/mlua)\n- [wasmtime](https://github.com/bytecodealliance/wasmtime)\n\n## Feedback\n\nIf you find anything incorrect, unclear, or missing, or want to suggest a new\nfeature, please open a GitHub issue or submit a pull request.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmbr7%2Fturbohex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnmbr7%2Fturbohex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnmbr7%2Fturbohex/lists"}