Onboarding: WerWolv/ImHex

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 4d ago
• 5 active contributors
• GPL-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 5 top contributors
• ⚠ Concentrated ownership — top contributor handles 72% of commits
• ⚠ GPL-2.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

ImHex is a feature-rich hex editor built in C++ targeting reverse engineers and low-level programmers. It provides a custom pattern language (similar to Kaitai/010 Editor templates) for declarative binary structure parsing, a disassembler via Capstone, and a plugin system (see PLUGINS.md and cmake/modules/ImHexPlugin.cmake) for extensibility. Core UI is rendered entirely with Dear ImGui via GLFW and OpenGL. Monorepo: the root CMakeLists.txt + cmake/build_helpers.cmake orchestrate a multi-plugin build. Core editor logic lives in the main app target; plugins are self-contained shared libraries built via cmake/modules/ImHexPlugin.cmake and the SDK template under cmake/sdk/. GLSL shaders sit in a small GLSL subtree (5884 bytes) and Objective-C code handles macOS-specific integration.

Who it's for

Reverse engineers, malware analysts, firmware hackers, and low-level programmers who need to inspect and annotate binary files. Also C++ plugin developers who want to extend the editor — see cmake/sdk/template/source/example_plugin.cpp for the plugin entry point pattern.

Maturity & risk

ImHex has tens of thousands of GitHub stars, a structured CI pipeline across .github/workflows/ (build.yml, tests.yml, analysis.yml, nightly_release.yml, release.yml), and a maintained changelog (changelog.md + VERSION file). It is production-ready for daily use, actively maintained by the primary author WerWolv with community contributions.

Primary risk is single-maintainer dependency — WerWolv drives most core decisions, though plugin contributions are welcome. The dependency surface is large: Capstone (disasm), YARA (pattern matching), mbedTLS (crypto), libssh2, LZ4, ZSTD, libmagic — all resolved via cmake/modules/ custom Find*.cmake scripts which can cause friction on non-standard systems. Breaking plugin API changes are possible across releases since the ABI is not formally versioned.

Active areas of work

Based on repo structure: nightly releases are automated via .github/workflows/nightly_release.yml, stale issue triage is automated (.github/workflows/stale_issues.yml), and a download-cache workflow (.github/workflows/dl-cache.yml) suggests active dependency caching work. The changelog.md and VERSION file indicate ongoing versioned releases.

Get running

git clone --recurse-submodules https://github.com/WerWolv/ImHex.git cd ImHex cmake --preset release -B build # see CMakePresets.json for available presets cmake --build build --parallel

On Linux ensure: libglfw3-dev, libcapstone-dev, libmagic-dev, libmbedtls-dev, libyara-dev, liblz4-dev, libzstd-dev are installed

Daily commands: cmake --preset release -B build && cmake --build build --parallel

Then run: ./build/ImHex

For debug: cmake --preset debug -B build_debug && cmake --build build_debug

Map of the codebase

• CMakeLists.txt — Root build definition that orchestrates all plugins, libraries, and platform-specific configurations — the entry point for every build.
• cmake/modules/ImHexPlugin.cmake — Defines the CMake macro for registering plugins, making it the contract every plugin author must understand to integrate correctly.
• cmake/build_helpers.cmake — Contains shared build utility functions (dependency resolution, platform detection, packaging) used throughout all CMakeLists files.
• dist/web/plugin-bundle.cpp.in — Template that bundles all plugins into the WebAssembly build, critical for understanding how the web port differs from native.
• cmake/sdk/CMakeLists.txt — Defines the public SDK interface that external plugin developers use to build out-of-tree plugins against ImHex.
• cmake/sdk/template/source/example_plugin.cpp — Canonical reference implementation showing the minimum viable plugin structure, lifecycle hooks, and registration pattern.
• PLUGINS.md — Documents the plugin architecture, API conventions, and contribution guidelines — required reading before adding any functionality.

How to make changes

Add a new ImHex plugin

1. Copy the SDK template directory and rename it for your plugin (cmake/sdk/template/CMakeLists.txt)
2. Implement plugin_init(), plugin_deinit(), and register your views/providers/handlers following the example (cmake/sdk/template/source/example_plugin.cpp)
3. Register the plugin target using add_imhex_plugin() macro with sources, includes, and dependencies (cmake/modules/ImHexPlugin.cmake)
4. Add the plugin subdirectory to the root CMakeLists so it is discovered and linked (CMakeLists.txt)
5. For WASM builds, ensure your plugin symbol is included in the static bundle template (dist/web/plugin-bundle.cpp.in)

Add a new target platform / packaging format

1. Add a new platform preset (toolchain, install prefix, sysroot) to the presets file (CMakePresets.json)
2. Add platform-specific find_package logic and install() rules in the build helpers (cmake/build_helpers.cmake)
3. Create a packaging descriptor file (PKGBUILD / spec / control / yaml) under dist/ (dist/Arch/PKGBUILD)
4. Add a new workflow job matrix entry targeting the platform, referencing existing jobs as templates (.github/workflows/build.yml)

Add a new dependency / library

1. Create a FindXxx.cmake module mirroring the existing pattern (find_path, find_library, handle_standard_args) (cmake/modules/FindCapstone.cmake)
2. Add the vcpkg port entry for Windows CI consumption (dist/vcpkg.json)
3. Wire find_package() call and target_link_libraries() into the build helpers (cmake/build_helpers.cmake)
4. Update relevant package manifests (Flatpak, Arch, Debian, RPM) to declare the new runtime dependency (dist/flatpak/net.werwolv.ImHex.yaml)

Update or add an embedded font

1. Place the TTF font file in dist/fonts/ and remap any icon glyphs to the private-use area (dist/fonts/move_private_use_area.py)
2. Run the conversion script to produce a C++ header with the raw byte array (dist/fonts/ttf_to_header_file.py)
3. Reference the generated header in the CMake target that embeds resources (cmake/build_helpers.cmake)

Why these technologies

• Dear ImGui — Immediate-mode GUI renders every frame from scratch, trivially supports custom hex grid drawing, infinite-undo pattern editors, and GPU-accelerated overlays without a retained-mode widget hierarchy.
• C++23 — Template metaprogramming, RAII, and zero-cost abstractions are essential for safely wrapping raw byte manipulation; modern C++ features reduce boilerplate in the pattern language runtime.
• CMake + vcpkg — Cross-platform build portability across Windows/Linux/macOS/WASM with consistent dependency resolution; vcpkg manifests lock transitive dependency versions.
• Emscripten / WASM — Enables running the full hex editor in a browser with no install, sharing the exact same plugin and pattern language code via conditional compilation.
• Dynamic shared libraries for plugins — Decouples features from the core binary, allows community plugins to be distributed independently, and lets the core team ship a minimal executable.
• Capstone disassembly engine — Provides multi-architecture disassembly (x86, ARM, MIPS, etc.) through a single

Traps & gotchas

1. Must clone with --recurse-submodules or submodule-based dependencies will be missing and CMake will fail silently on some paths. 2) cmake/modules/ contains custom Find*.cmake scripts that override system ones — if you have non-standard install paths, set CMAKE_PREFIX_PATH explicitly. 3) The Objective-C source requires Apple Clang on macOS; cross-compiling for macOS from Linux is not supported. 4) CoreCLR embed (FindCoreClrEmbed.cmake) requires a .NET runtime to be present for scripting features to build; this is optional but the CMake detection can produce confusing errors if partially installed. 5) .clang-tidy is enforced in CI (analysis.yml) — clang-tidy must be installed locally or CI will catch issues you won't see in a plain build.

Architecture

Concepts to learn

• Dear ImGui immediate-mode GUI — ImHex renders every UI element — hex view, pattern editor, disassembler — using ImGui's immediate-mode paradigm; understanding retained vs. immediate mode is essential before touching any UI code.
• Memory-mapped file I/O — Hex editors must handle multi-gigabyte files efficiently; ImHex uses memory-mapped I/O so the OS page cache handles buffering rather than loading entire files into RAM.
• Capstone disassembly framework — ImHex's disassembler view is powered by Capstone, a multi-architecture disassembly library; knowing its API is required to extend or fix the disassembly plugin.
• YARA pattern matching — ImHex integrates YARA (cmake/modules/FindYara.cmake) to let analysts run signature-based detection rules directly on open binary files — a non-obvious but powerful feature.
• Shared library plugin architecture — ImHex loads plugins as runtime shared libraries (.so/.dll/.dylib); understanding dynamic linking, symbol visibility, and ABI stability is critical to writing compatible plugins.
• Binary template / pattern language — ImHex's core differentiator is a custom declarative language for describing binary structures (similar to 010 Editor templates); the parser and evaluator for this language are central to the codebase.
• CMake presets (CMakePresets.json) — The build system uses CMake Presets (CMakePresets.json) to standardize configure/build/test workflows across platforms — a modern CMake feature that replaces ad-hoc build scripts.

Related repos

• solemnwarning/rehex — Direct alternative: another open-source hex editor with structure parsing, written in C++/wxWidgets targeting the same reverse engineering use case.
• WerWolv/ImHex-Patterns — Companion repo containing the community library of ImHex pattern language (.hexpat) files for common binary formats — users of ImHex will want this immediately.
• ocornut/imgui — The Dear ImGui library that ImHex's entire UI is built on — understanding ImGui is prerequisite for contributing any UI code.
• aquynh/capstone — The multi-arch disassembly engine integrated via cmake/modules/FindCapstone.cmake — ImHex's disassembler view depends directly on this.
• kaitai-io/kaitai_struct — Predecessor/inspiration for the declarative binary structure description concept that ImHex's pattern language implements natively.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add a GitHub Actions workflow for automated plugin build validation using ImHexPlugin.cmake

The repo has cmake/modules/ImHexPlugin.cmake and cmake/sdk/template/ for third-party plugin development, but there is no dedicated CI workflow (under .github/workflows/) that builds and validates the SDK template plugin against multiple platforms. This would catch regressions in the plugin API/CMake integration before releases and give contributors a reference build to verify their plugins against.

• [ ] Create .github/workflows/plugin_sdk.yml that checks out the repo and runs cmake with cmake/sdk/CMakeLists.txt pointing at cmake/sdk/template/ as the plugin source
• [ ] Configure the workflow matrix to cover ubuntu-latest, windows-latest, and macos-latest runners
• [ ] Use cmake/modules/ImHexPlugin.cmake as the find_package target inside the workflow to ensure the SDK export works end-to-end
• [ ] Add a step that verifies the built plugin artifact exists and is a valid shared library (.so/.dll/.dylib) using a simple shell check
• [ ] Document the new workflow in CONTRIBUTING.md under a 'Plugin Development CI' section

Expand .github/ISSUE_TEMPLATE with a 'Plugin Compatibility Report' template referencing PLUGINS.md

PLUGINS.md exists and describes the plugin system, but the issue templates under .github/ISSUE_TEMPLATE/ only contain bug_report.yaml and feature_request.yaml. There is no structured template for reporting broken or incompatible plugins, which is a distinct and common category of issues for a tool with a plugin ecosystem. This causes plugin issues to be filed as generic bugs, making triage harder.

• [ ] Read PLUGINS.md to understand the plugin versioning and ABI compatibility guarantees currently documented
• [ ] Create .github/ISSUE_TEMPLATE/plugin_compatibility.yaml with structured fields: ImHex version, plugin name/source, OS, observed vs expected behavior, and crash log
• [ ] Add a 'validations' section in the YAML requiring the reporter to confirm they checked PLUGINS.md for known incompatibilities
• [ ] Reference the new template from CONTRIBUTING.md so contributors know which template to use for plugin-related reports
• [ ] Test the template renders correctly on GitHub by opening a draft issue

Add a distro-agnostic installation smoke-test script and wire it into the existing tests.yml workflow

The repo has .github/workflows/tests.yml for automated testing and dist/ contains packaging artifacts for AppImage, Arch, and Debian, but there is no automated test that installs the packaged binary and verifies basic startup (e.g., --help or --version exits cleanly). This means packaging regressions are only caught by users post-release. A lightweight smoke-test using the AppImage artifact is the lowest-friction entry point.

• [ ] Add a shell script at .github/scripts/smoke_test.sh that downloads the AppImage artifact from the build job, makes it executable, and runs ./ImHex.AppImage --help asserting exit code 0
• [ ] Inspect dist/AppImage/AppImageBuilder.yml to identify the correct AppImage filename pattern produced by the build
• [ ] Add a new job 'smoke-test' in .github/workflows/tests.yml that depends on the build job, downloads the AppImage artifact using actions/download-artifact, and executes .github/scripts/smoke_test.sh
• [ ] Ensure the job runs only on ubuntu-latest since AppImage is Linux-specific, and add a comment explaining how to extend it for the .deb artifact using dist/DEBIAN/control.in
• [ ] Update INSTALL.md with a note that automated smoke tests validate each AppImage build

Good first issues

1. The cmake/modules/ Find*.cmake scripts lack pkg-config fallback for several libraries (e.g. FindLZ4.cmake, FindZSTD.cmake) — adding pkg_check_modules() fallback would improve Linux distro compatibility. 2) .github/ISSUE_TEMPLATE/ has bug and feature templates but no 'plugin development question' template — adding one would reduce noise in bug reports from plugin authors. 3) cmake/sdk/template/source/example_plugin.cpp is minimal; adding a second template demonstrating a file format parser plugin with the pattern language API would significantly help new plugin contributors.

Top contributors

• @WerWolv — 68 commits
• @paxcut — 20 commits
• @shewitt-au — 3 commits
• @WerWolvTranslationBot — 3 commits
• @nwvh — 1 commits

Recent commits

• c6045c7 — patterns: update pattern language (paxcut)
• 245803c — fix: Crash when closing empty delimiters (#2730) (paxcut)
• d62dbd4 — fix: typo on menu (paxcut)
• 58cde7a — fix: small typo in welcome screen (#2704) (nwvh)
• 316318a — fix: crashes from delimiter matching (#2725) (paxcut)
• bc5887a — fix: dos date and time in big endian (#2724) (paxcut)
• 595df51 — build: update libwolv (paxcut)
• c661dae — fix: logs with utf-8 multibyte chars. (#2722) (paxcut)
• 0c2e881 — Fix nullptr deref when opening ImHex without a provider on frame 1 (#2718) (neptuwunium)
• be7b7a8 — Fix/utf8 log alignment (#2717) (paxcut)

Security observations

• High · Insecure Vulnerability Reporting Channel — SECURITY.md. The SECURITY.md file instructs users to report critical vulnerabilities via a public Discord server (direct message to @werwolv). This is an insecure disclosure channel as it lacks encryption, formal tracking, SLA commitments, or CVE coordination processes. Sensitive vulnerability details could be exposed or lost. Fix: Implement a formal responsible disclosure process using GitHub's private security advisories (Security > Advisories) or a dedicated encrypted email address (e.g., security@domain.com with a published PGP key). Adhere to coordinated vulnerability disclosure best practices.
• High · Limited Supported Version Policy Increases Attack Surface — SECURITY.md. The security policy only supports the latest release, leaving users on older versions without security patches. This is particularly concerning for a tool used by security researchers who may process untrusted binary files. Malformed or malicious binary files could exploit parsing vulnerabilities in unsupported versions. Fix: Maintain at minimum the current stable and previous major release with security backports. Clearly document EOL timelines and provide automated update notifications within the application.
• Medium · No Formal Bug Bounty or CVE Assignment Process — SECURITY.md. There is no documented process for CVE assignment, severity rating (e.g., CVSS scoring), or coordinated public disclosure timelines. This means vulnerabilities in a widely-used security tool may not receive proper public tracking, leaving the community uninformed about risks. Fix: Register with MITRE or a CNA (CVE Numbering Authority) to enable CVE assignment. Define a disclosure timeline (e.g., 90-day coordinated disclosure) and publish security advisories through GitHub Security Advisories.
• Medium · Potentially Unsafe Processing of Untrusted Binary Files — cmake/modules/ImHexPlugin.cmake, cmake/modules/FindYara.cmake, cmake/modules/FindCapstone.cmake, cmake/modules/FindMagic.cmake. ImHex is a hex editor designed to open and parse arbitrary binary files, including potentially malicious ones. Based on the file structure (pattern language parsing, plugin system via ImHexPlugin.cmake, Yara/Capstone/Magic integration), there is significant attack surface for memory corruption, integer overflows, or parser exploits when processing crafted malicious files. The tool is commonly used to analyze malware, making this a high-risk scenario. Fix: Ensure all file parsers use memory-safe practices (bounds checking, fuzzing with AFL++/libFuzzer). Consider sandboxing file parsing operations. Keep all third-party parsing libraries (Capstone, Yara, libmagic) pinned to latest patched versions with automated dependency update tooling (e.g., Dependabot, Renovate).
• Medium · Plugin System Introduces Arbitrary Code Execution Risk — PLUGINS.md, cmake/modules/ImHexPlugin.cmake, cmake/sdk/. The plugin architecture (PLUGINS.md, cmake/modules/ImHexPlugin.cmake, cmake/sdk/) allows loading of third-party plugins. If plugins are loaded from untrusted sources without signature verification, this creates a vector for arbitrary code execution in the context of the application. The SDK template further lowers the barrier for plugin creation. Fix: Implement plugin signature verification (code signing). Establish an official plugin repository with security review. Sandbox plugin execution where feasible. Document clearly that users should only install plugins from trusted sources.
• Medium · Docker Build Files May Expose Build Environment Risks — dist/AppImage/Dockerfile, dist/Arch/Dockerfile, dist/macOS/arm64.Dockerfile. Multiple Dockerfiles exist (dist/AppImage/Dockerfile, dist/Arch/Dockerfile, dist/macOS/arm64.Dockerfile) without visible content review. Build containers that are not hardened (running as root, using latest/unversioned base images, or containing secrets) can compromise CI/CD pipeline integrity and supply chain security. Fix: Ensure all Dockerfiles use pinned, specific base image digests (not 'latest'), run as non-root users, minimize installed packages, and do not embed secrets. Use Docker layer scanning tools (Trivy, Snyk) in CI/CD pipelines.
• Medium · GitHub Actions Workflow Security Not Verified — undefined. Multiple GitHub Actions workflows exist (.github/workflows/). Without reviewing their Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.