Talaria

Winged tools for Hermes bytecode.

Talaria is a Python command-line tool and library for disassembling, editing, and assembling Hermes bytecode bundles used by React Native applications.

Talaria is named after the winged sandals of Mercury, the Roman counterpart to Hermes.

Hermes Bytecode Support

Talaria supports the Hermes bytecode (HBC) versions listed below. Hermes does not publish separate end-user documentation for each bytecode version; the closest authoritative references are the Hermes source files that define the bytecode file format and opcode list. General background is available in the React Native Hermes guide and the Bundled Hermes architecture notes.

HBC version	Opcodes	Talaria metadata	Upstream reference	Test fixture
59	177	hbc59	facebook/hermes@v0.1.0	bundle
62	177	hbc62	facebook/hermes@v0.2.1	bundle
74	180	hbc74	facebook/hermes@v0.5.0	bundle
76	180	hbc76	facebook/hermes@v0.7.0	bundle
84	199	hbc84	facebook/hermes@v0.8.1	bundle
85	201	hbc85	facebook/hermes@RN 0.69	bundle
90	204	hbc90	facebook/hermes@RN 0.71	bundle
94	206	hbc94	facebook/hermes@RN 0.72	bundle
96	206	hbc96	facebook/hermes@RN 0.73	bundle
98	219	hbc98	facebook/hermes@hermes-v250829098.0.10	bundle

Unsupported bundle versions fail explicitly before parsing. The source tag registry lives in specs.json, including the compiler package used for generated fixtures. Fixtures for HBC 84, 85, 90, 94, 96, and 98 are compiled from hbc_fixture.js. HBC 59 and 62 are retained sample bundles because the matching npm packages do not ship a usable Linux hermesc binary; HBC 74 and 76 are retained sample bundles that are verified against their source-era metadata.

Install

python -m pip install talaria

Usage

talaria disasm index.android.bundle workspace/
talaria asm workspace/ index.android.bundle

For APKs that contain the usual React Native bundle path:

talaria apk disasm app.apk app-workspace/
# edit app-workspace/tasm/functions.tasm
talaria apk asm app-workspace/

talaria apk disasm runs apktool d -r, so APK resources are kept raw. The decoded APK tree is written to app-workspace/apk, and the TASM workspace is written to app-workspace/tasm. talaria apk asm updates app-workspace/apk/assets/index.android.bundle.

Use talaria --help for the complete command reference.

Workspace Format

talaria disasm writes a Talaria workspace:

• talaria.json: workspace manifest and format version
• bundle.json: raw Hermes bytecode metadata needed for reassembly
• strings.json: editable string table view
• functions.tasm: Talaria assembly text

Function blocks in functions.tasm use a smali-inspired line-oriented syntax:

.function @45154
    .name "?anon_0_"
    .params 1
    .registers 12
    .symbols 0

    .hints
        kind generator_body
        wrapped_by fn@45153
        exported_as "resetTrialStarted"
        yield_points :L002f
        flags generator_state_machine reads_environment
    .end hints

    StartGenerator
    ResumeGenerator r0, r1
    JmpTrue :L002f, r1
    LoadConstUndefined r1
    CompleteGenerator
    Ret r1

:L002f
    CompleteGenerator
    Ret r0
.end function

Common operand forms are r0 for registers, plain integers for opcode-typed unsigned immediates, i32:-1 for signed immediates, s@18 "value" for editable string table references, fn@4 for function references, and labels such as :L002f for branch targets. Cache slots and similar common operands render with aliases such as cache:2, slot:0, param:1, and argc:3.

The optional .hints block contains generated annotations for reverse engineering. Hints are ignored by the assembler; editing or removing them does not change the bytecode. Each hint line starts with a key followed by values. Repeated keys are allowed. Current hints cover common structure such as parent closures, Metro module factories, export getters, methods, async/generator wrappers, selector/projector relationships, callbacks, captured environment slots, dependency imports, property writes, and compact flags.

VS Code Syntax Highlighting

This repository includes a local VS Code language extension for functions.tasm and other .tasm files.

Install it from the talaria repository root:

mkdir -p ~/.vscode/extensions
ln -s "$PWD/vscode/talaria-tasm" ~/.vscode/extensions/talaria-tasm

Reload VS Code, then open a .tasm file. If VS Code does not detect the language automatically, choose Talaria TASM from the language mode picker.

To install by copying instead of symlinking:

mkdir -p ~/.vscode/extensions/talaria-tasm
cp -R vscode/talaria-tasm/. ~/.vscode/extensions/talaria-tasm/

Development

python -m pip install -e ".[dev]"
python -m pytest
python tools/check_hbc_specs.py
python -m ruff check src/talaria/cli.py src/talaria/commands.py tools tests

The bytecode parsers are data-driven by the versioned Hermes structure and opcode metadata under src/talaria/hbc/hbc*/data. Use tools/check_hbc_specs.py after updating any BytecodeList.def or opcode.json file.