How werwolv/imhex works
1. What this repo builds
- ImHex is a cross-platform hex editor with a plugin-based architecture.
- The primary deliverable is the desktop GUI app; there is also a WebAssembly/browser build under dist/web, plus packaging targets for Windows, Linux, macOS, Flatpak, Snap, AppImage, etc.
2. Top-level runtime split
- main/gui is the user-facing application process.
- main/updater is a separate updater executable.
- main/forwarder is a small helper/entry process used to launch or forward into the main app in some environments.
- Most shared behavior lives in lib/libimhex, which is the core SDK/runtime used by the app and plugins.
3. Core application foundation: lib/libimhex
- This is the central architecture layer: managers, registries, event bus, plugin manager, task manager, workspace/layout/theme/localization managers, shortcut handling, and project file management.
- It also defines the stable plugin-facing API under hex/api, so plugins do not talk directly to the GUI internals.
- The library includes provider abstractions, undo/redo, data processor graph primitives, helpers, and MCP client/server support.
4. Plugin system as the main extension boundary
- Plugins are first-class modules in plugins/*, each with its own CMake target and often its own bundled resources in romfs.
- Plugins register content through the core content registry: views, tools, providers, formatters, disassemblers, data processors, settings, and commands.
- This is the key architecture boundary: core app + libimhex provide services, plugins contribute features.
5. Built-in plugin is the feature backbone
- plugins/builtin contains most default user functionality: hex editor behavior, file handlers, recent files, settings, tutorials, reports, popups, command palette actions, and core views.
- It also registers the default data processors, pattern-language integration, import/export formats, themes, workspaces, and out-of-box experience.
- In practice, many visible app features are not in the GUI executable itself but are registered by this plugin at startup.
6. Data model and data-source pipeline
- The app centers on a Provider abstraction: files, raw disks, process memory, GDB, UDP, Base64, Intel HEX/SREC, SSH/SFTP, and other sources are all exposed through provider implementations.
- Views like the hex editor, data inspector, bookmarks, search, patches, and pattern parser read through the active provider rather than directly from files.
- Undo/redo and patching operate on provider-backed data, so modifications flow through the provider layer instead of being hardwired to a single storage type.
7. Pattern Language and data processor graph
- Pattern Language is the custom C-like parser/descriptor system used to interpret file structure and generate highlights, types, and visualizations.
- The node-based data processor is a preprocessing pipeline that can transform, decrypt, or decode data before it reaches the editor/visualizers.
- These two subsystems are central to analysis: one describes structure, the other can transform input data.
8. Feature plugins are mostly self-contained modules
- plugins/diffing, disassembler, hashes, remote, script_loader, ui, visualizers, windows, yara_rules, decompress, and fonts each add a coherent feature set.
- Examples of external integrations that materially shape architecture:
- Capstone for disassembly
- YARA for signature scanning
- SSH/SFTP for remote file access
- .NET scripting loader for plugin scripting
- ImGui/ImPlot/ImNodes for UI, plotting, and node graphs
- These plugins generally register their own views and helpers, but still rely on the same provider/content-registry core.
9. UI and rendering stack
- The GUI is built on Dear ImGui with OpenGL rendering and GLFW-style platform integration.
- plugins/ui provides shared UI widgets and editors used by many plugins, while plugins/fonts manages bundled font assets and font selection.
- Platform-specific window/messaging code lives under main/gui/source/window/platform/* and main/gui/source/messaging/* for Windows, macOS, Linux, and Web.
10. Startup and platform glue
- main/gui handles application startup, splash screen, crash handling, window creation, and per-platform messaging.
- It branches into CLI/desktop/web startup paths under main/gui/source/init/run/*, which is where environment-specific launch logic is separated.
- This layer is the bridge between the OS and the plugin-driven core runtime.
11. Resources and bundled content
- romfs directories throughout the repo contain embedded runtime assets: themes, layouts, icons, localization JSON, shaders, splash assets, templates, and default workspaces.
- resources/ contains packaging assets such as Windows installer resources, macOS app metadata, and logo artwork.
- The app depends heavily on these embedded resources for first-run experience, theming, and plugin-provided UI/content.
12. Build, packaging, and dependency structure
- The repository is organized around CMake with many helper modules and third-party libraries vendored under lib/third_party.
- This layout is important architecturally because the project is meant to be built into multiple binaries and packaging formats from the same source tree.
- dist/ contains release engineering, distro packaging, dependency bootstrap scripts, and web build assets.
13. Tests and verification
- tests/ covers common helpers, algorithms, plugin behavior, and language-related checks.
- Tests are split by concern rather than by app layer, which matches the repo’s modular design: core helpers, algorithms, and plugin integration are validated separately.
14. Diagram-friendly mental model
- The cleanest architecture diagram is: OS/web entrypoints → GUI bootstrap → core libimhex services → content registry/plugin manager → plugins → providers/views/data processors.
- Data flows from providers into the hex editor, pattern language, inspector, diffing, disassembler, hashing, and visualizer features; user actions flow back through events, undo/redo, and task managers.
Main entry points: libimhex libimhex · builtin Builtin plugin · content_registry Registry · plugins Feature plugins
Components 19
Entrypoints
Desktop, updater, and web startup paths.
Core runtime
Shared SDK, managers, providers, events, and analysis primitives.
- libimhex · Central shared runtime and plugin-facing API used by the application and extensions.
lib/libimhex - Registry · Registers views, tools, providers, formatters, processors, settings, and commands.
lib/libimhex/include/hex/api/content_registry - Events · Lifecycle, GUI, interaction, provider, and request event routing.
lib/libimhex/include/hex/api/event_manager.hpp - Plugins core · Loads plugins and mediates their integration with the application runtime.
lib/libimhex/include/hex/api/plugin_manager.hpp - Managers · Workspace, theme, localization, layout, shortcuts, tasks, project files, tutorials, and achievements.
lib/libimhex/include/hex/api - Providers · Abstraction for files, disks, memory, network, remote access, and decoded sources.
lib/libimhex/include/hex/providers - Undo/patch · Provider-backed edit history and patch operations.
lib/libimhex/include/hex/providers/undo_redo - Processors · Graph-based preprocessing pipeline for decode, transform, and analysis stages.
lib/libimhex/include/hex/data_processor - Pattern language · C-like pattern descriptor system for structure, types, highlights, and visualizations.
lib/external/pattern_language
Plugins
Built-in and feature plugins registered into the core content system.
- Builtin plugin · Registers core editor behavior, file handlers, views, processors, themes, workspaces, tutorials, and commands.
plugins/builtin - UI plugin · Common widgets, editors, markdown, pattern UI, and text editor components used by other plugins.
plugins/ui - Fonts plugin · Manages bundled fonts and font selection.
plugins/fonts - Feature plugins · Diffing, disassembler, hashes, remote, script loader, visualizers, windows, yara rules, and decompression features.
plugins
Assets & packaging
Embedded resources, release packaging, and web bundle assets.
- Web build · Browser/WebAssembly runtime and bundled web assets.
dist/web - ROMFS assets · Themes, layouts, icons, localization, shaders, workspaces, splash assets, and plugin-provided content.
plugins/builtin/romfs - Packaging · Desktop and distro packaging for Windows, Linux, macOS, Flatpak, Snap, AppImage, and related formats.
dist
Connections 26
- Forwarder → GUI app: launches · Forwarder hands off into the main GUI app.
- GUI app → libimhex: uses · GUI bootstrap depends on the shared runtime and API.
- Updater → libimhex: shares core · Updater reuses shared infrastructure where needed.
- libimhex → Registry: exposes · Core library publishes the extension registration surface.
- libimhex → Events: routes · Shared event bus coordinates runtime and plugin communication.
- libimhex → Plugins core: hosts · Plugin manager is part of the core host layer.
- libimhex → Managers: bundles · Core runtime includes workspace, theme, task, shortcut, and project managers.
- libimhex → Providers: defines · Provider abstraction is central to data access.
- libimhex → Undo/patch: tracks · Mutation history and patching live on the provider layer.
- libimhex → Processors: defines · Node-based preprocessing pipeline is a core primitive.
- libimhex → Pattern language: integrates · Pattern language is part of the analysis and visualization stack.
- Builtin plugin → Registry: registers · Builtin plugin contributes most default views, providers, processors, and commands.
- Builtin plugin → Providers: implements · Builtin plugin ships the standard provider implementations.
- Builtin plugin → Processors: adds · Builtin plugin provides the default processing nodes.
- Builtin plugin → Pattern language: extends · Builtin plugin wires built-in types, functions, pragmas, and visualizers.
- Builtin plugin → ROMFS assets: ships · Default themes, layouts, locales, shaders, and workspaces are embedded here.
- UI plugin → Registry: registers · Shared UI contributes widgets and editors.
- Fonts plugin → Registry: registers · Font management is exposed through the content registry.
- Feature plugins → Registry: registers · Feature plugins add views, tools, providers, and analyzers through the registry.
- Feature plugins → Providers: uses · Feature plugins operate on the same provider abstraction.
- Feature plugins → UI plugin: builds on · Many feature plugins reuse shared UI components.
- Web build → GUI app: targets · Web build follows the GUI startup path in a browser runtime.
- Packaging → GUI app: packages · Release engineering bundles the desktop app into platform-specific distributions.
- Packaging → Updater: packages · Updater is packaged as a separate binary where needed.
- ROMFS assets → Builtin plugin: feeds · Embedded assets are consumed by the builtin plugin at startup.
- Feature plugins → ROMFS assets: localizes · Plugins commonly ship their own embedded assets and translations.