Skip to content
asmjmp0Public

About

HarmonyOS ArkTS decompiler (.hap/.abc) & bytecode toolkit — decompile · patch · instrument / 鸿蒙 ArkTS 反编译器与字节码工具链:反编译 · 修改 · 动态注入

Topics

Resources

Stars

162 stars

Watchers

7 watching

Forks

Latest commit

 

History

188 Commits

Folders and files

Repository files navigation

xpanda

English | 简体中文

Web decompiler: https://tencent.jmp0.top/xpanda

"Holy crap — when he read it, he froze and said: with a HarmonyOS decompiler this good, why on earth didn't you tell me sooner?"

A decompiler for HarmonyOS .abc files (Panda / ArkCompiler bytecode), written in pure TypeScript. Node.js ≥ 18, zero native dependencies.

It turns .abc files back into readable JavaScript: classes, methods, functions, control flow and module import/export are restored, and an optimizer pipeline cleans up the register temporaries emitted by the compiler.

Supported bytecode versions: 24.0.0.0 (backward compatible with 13.0.1.0; ArkTS 12 packages, 12.0.2.0, decompile as well). ArkTS-Sta (static runtime) framework bytecode (0.1.0.7, fw_*.abc) is supported through a separate parser/ISA path.

xpanda web UI — decompiling a HarmonyOS app package entirely in the browser

Features

  • Pure TypeScript, zero native dependencies: parses .abc files and emits readable JavaScript that can run as-is;
  • Dynamic ArkTS and ArkTS-Sta: the standard Panda format plus the static runtime's 72-byte header / static ISA (fw_*.abc), with shared structure analysis and optimizer; compiler-generated LambdaN closure classes are folded back into arrow functions;
  • Classes and functions: class fields, accessors, prototype methods, closures and lexical environments (local / sendable env);
  • Control flow: if/else, while/do-while, for, try/catch/finally, and more; falls back to labeled linear output when structural analysis fails;
  • Modules: ES Module import / export;
  • Babel AST optimizer: register-temp copy propagation, dead-store elimination, function/class syntax recovery, call rewriting and compound-assignment folding;
  • MCP Server: lets AI clients such as Claude Code, OpenCode and Cursor analyze .abc files on demand;
  • Web UI: drag & drop a .abc / .hap file in the browser and decompile it entirely client-side — nothing is uploaded.

Requirements

  • Node.js ≥ 18

Monorepo layout

The project is split into six yarn-workspace packages under packages/:

Package Purpose
@asm-xpanda/core .abc / .hap parsing, disassembly, decompilation and the optimizer — the library everything else builds on
@asm-xpanda/cli command line interface (decompile / unpack-index / dump-asm / dump / gadget)
@asm-xpanda/mcp MCP server (stdio) for AI client integration
@asm-xpanda/web browser UI (React + esbuild, pure frontend)
@asm-xpanda/asm bytecode assembler plus load, modify (replace method code / add methods, strings), dump classes and re-emit .abc files
@asm-xpanda/gadget Frida-Gadget-style init injector: bytecode bootstrap + embedded NAPI gadget .so (socket messaging + JSVM execution)

Install and use

yarn install

# Compile the libraries, symlink @asm-xpanda/* into the global prefix, and put
# `xpanda` / `xpanda-mcp` on PATH. Points at this checkout, does not publish,
# and will not replace a real (non-symlink) install.
yarn install:global

Remove those links with yarn install:global -- --remove.

The library packages are linked from their built dist directories (JavaScript + .d.ts), so another project on this machine can use them from plain Node:

cd /path/to/other-project
npm link @asm-xpanda/core @asm-xpanda/asm @asm-xpanda/gadget
# or: yarn link @asm-xpanda/core @asm-xpanda/asm @asm-xpanda/gadget
const { PandaFile, PandaDecompiler } = require("@asm-xpanda/core");

yarn install:global builds the libraries before linking. After changing this checkout's sources, run yarn build:local; the global links point at dist, so no re-linking is needed. @asm-xpanda/cli and @asm-xpanda/mcp stay source-linked because their bins run through tsx.

CLI (run from the repository root, or as xpanda after the global install):

yarn tsx packages/xpanda-cli/src/cli.ts decompile <file.abc|file.hap> [-o outDir] [--no-simplify] [--stdout] [--quiet] [-j N] [--timeout SEC]
yarn tsx packages/xpanda-cli/src/cli.ts dump-asm <file.abc|file.hap> [-o outDir] [--stdout]
yarn tsx packages/xpanda-cli/src/cli.ts dump <file.abc|file.hap> -c <class> [-c ...] [-o out.abc|outDir]
yarn tsx packages/xpanda-cli/src/cli.ts gadget <file.abc|file.hap> [-o outDir] [--port N] [--entry CLASS] [--so PATH] [--no-so]
yarn tsx packages/xpanda-cli/src/cli.ts gadget shell [-p N] [-t serial]   # interactive JS shell (auto hdc fport)
yarn tsx packages/xpanda-cli/src/cli.ts gadget file <script.js> [--once]  # run on start + every save

gadget injects an xpanda-gadget init bootstrap into the entry func_main_0, embeds libxpanda_gadget.so into the HAP (libs/<abi>/) and rebuilds the package; re-sign before installing. gadget shell forwards tcp:<port> to the gadget's abstract socket over hdc and opens a REPL; evaluation runs on the app's JS thread in the gadget's own JSVM (--jitless). See packages/xpanda-gadget/README.md for the socket protocol and JS runtime.

Option Description
-o outDir Output directory, defaults to out
--no-simplify Skip the optimizer and emit raw decompiler output; faster
--stdout Print the result to stdout instead of writing files
--quiet Suppress progress logs
-j, --jobs N Number of workers that run simplify per class; 0 = auto (CPU-1, max 4)
--timeout SEC Stop a class's simplify after SEC seconds and keep that class's raw output. Timed-out classes are listed in a warning at the end. 0 disables (the default)

HAP support:

  • Given a .hap input (HarmonyOS ability package, a ZIP container), every .abc entry inside is extracted and decompiled; class files go to outDir/<abc entry path>/ (e.g. ets/modules.abc → out/ets/modules/), and resources.index is unpacked to outDir/resources.json;
  • The unpack-index subcommand can also unpack a standalone resources.index.

Examples:

# Full decompilation (with optimizer)
yarn tsx packages/xpanda-cli/src/cli.ts decompile app.abc -o out --quiet

# Per-class parallelism for large files (worker_threads)
yarn tsx packages/xpanda-cli/src/cli.ts decompile app.abc -o out -j 4 --quiet

# Cap each class's simplify at 30 seconds; timed-out classes keep raw output
yarn tsx packages/xpanda-cli/src/cli.ts decompile app.abc -o out -j 4 --timeout 30 --quiet

# Inspect raw output without optimization
yarn tsx packages/xpanda-cli/src/cli.ts decompile app.abc -o out --no-simplify --quiet

# Print to the terminal
yarn tsx packages/xpanda-cli/src/cli.ts decompile app.abc --stdout --quiet

Dump bytecode assembly

dump-asm disassembles every method of every class to bytecode assembly (.asm files, one per class, same per-class layout as decompile) — handy for inspecting the bytecode that a decompiled method came from. Per-method output shows vregs / args / code size / try-block count, followed by labeled basic blocks; jump instructions print their resolved target label ([label_221]).

# Write .asm files (out/<abc entry path>/<class path>.asm for haps)
yarn tsx packages/xpanda-cli/src/cli.ts dump-asm app.hap -o out

# Or print everything to the terminal
yarn tsx packages/xpanda-cli/src/cli.ts dump-asm app.abc --stdout

Dump selected classes to a new abc

dump copies one or more classes (plus the classes/methods they reference) out of a .abc/.hap and writes a new .abc — useful for isolating a class before inspecting or patching it with @asm-xpanda/asm. Class names accept Lpkg/Name;, pkg/Name, or a unique name suffix.

# One class to a new abc
yarn tsx packages/xpanda-cli/src/cli.ts dump app.abc -c 'Lpkg/Name;' -o out/Name.abc

# Several classes (repeat -c or use positional/comma-separated names)
yarn tsx packages/xpanda-cli/src/cli.ts dump app.abc -c Foo -c Bar -o out/foo-bar.abc

# hap input: one <entry>.dump.abc per .abc entry containing matches
yarn tsx packages/xpanda-cli/src/cli.ts dump app.hap -c Foo -o out

The dumped abc is meant for analysis/patching: module imports are preserved in the class metadata, but the imported modules themselves are not bundled.

The CLI raises its own heap to 8 GiB unless --max-old-space-size is already set (on the command line or in NODE_OPTIONS). For large files, enable per-class parallelism:

yarn tsx packages/xpanda-cli/src/cli.ts decompile app.abc -o out -j 4 --quiet

Programmatic API

import * as fs from "fs";
import { PandaFile, PandaDecompiler } from "@asm-xpanda/core";

const pandaFile = new PandaFile(new Uint8Array(fs.readFileSync("app.abc")));
const decompiler = new PandaDecompiler();

for (const cls of pandaFile.getAllClasses()) {
    const js = decompiler.decompileClass(cls);       // with simplify
    // const js = decompiler.decompileClassRaw(cls); // without simplify
}

To import it from another project on this machine, link the built package first (see Install and use).

MCP Server

xpanda ships a built-in Model Context Protocol server, so AI clients such as Claude Code, OpenCode and Cursor can drive the decompiler — letting an agent analyze .abc and .hap files (HarmonyOS app packages containing bytecode and resources) on demand: load → browse classes → inspect metadata → decompile a single class → cross-check disassembly → search strings → query resources.

yarn mcp             # start it (stdio transport)
yarn test:mcp        # end-to-end test
Tool Purpose
abc_load Parse an .abc or .hap file and return a fileId; for haps, a package summary plus the list of .abc entries
hap_read_abc Extract an .abc entry from a hap into an abc session; the returned abcFileId works with every abc_* tool
hap_resources Parse the hap's resources.index and query resources by name / type / limit key / id
abc_list_classes Page through classes (name / method count / field count) with substring filtering
abc_get_class Class metadata: superclass, fields, methods (shorty prototypes), import/export
abc_decompile_class Decompile a single class to JavaScript, with a degradation flag
abc_disassemble_method Method-level disassembly (basic blocks + jump targets + try-catch membership)
abc_search_strings Search the string pool (substring or regex) to locate URLs, keys and other leads
abc_export Decompile everything to disk (equivalent to the CLI decompile)
abc_close Release the session's memory (abc or hap)

Client integration:

# Claude Code
claude mcp add xpanda -- npx tsx /absolute/path/to/xpanda/packages/xpanda-mcp/src/server.ts

# OpenCode
opencode mcp add xpanda -- npx tsx /absolute/path/to/xpanda/packages/xpanda-mcp/src/server.ts

Generic JSON config (Claude Desktop / Cursor, etc.):

{
  "mcpServers": {
    "xpanda": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/xpanda/packages/xpanda-mcp/src/server.ts"]
    }
  }
}

See docs/MCP.md for the full tool reference.

Web UI

xpanda also ships a browser UI that decompiles .abc files and .hap app packages entirely in the browser — nothing is ever uploaded.

yarn web             # esbuild dev server (watch + live reload) → http://localhost:5173
  • Drag & drop anywhere or pick files (.abc / .hap, multiple supported); haps are unpacked in-memory and every .abc entry gets its own class list;
  • Class list with search and package grouping; click a class to decompile it, or run "decompile all" with a live progress bar (cancellable);
  • Copy / download single classes, or pack every result into a .zip; output mode toggle Optimized / Raw AST;
  • Zero-dependency syntax highlighting with line numbers.

See packages/xpanda-web/README.md for details.

Roadmap

  • Keep improving structured output. Region reduction still falls back to labeled linear output on irreducible graphs and a few try/finally shapes still end as a try/finally not restored note; the work is in StructureAnalysis.ts and TryFinally.ts, with every new rule measured against the whole sample set.
  • Add an SSA layer. Build def-use chains and φ nodes on the CFG — following the design of the React Compiler — so dead stores, copy propagation and accumulator folding run once on the IR, before structuring, instead of being re-derived from the generated AST. That should remove the vN = v0 spill chains and materialized-condition temporaries that the optimizer currently has to pattern-match.

References

Bytecode format, instruction semantics, and the resources.index layout follow the official OpenHarmony repositories:

License

See LICENSE.

About

HarmonyOS ArkTS decompiler (.hap/.abc) & bytecode toolkit — decompile · patch · instrument / 鸿蒙 ArkTS 反编译器与字节码工具链:反编译 · 修改 · 动态注入

Topics

Resources

Stars

162 stars

Watchers

7 watching

Forks

Releases

Packages

Contributors

Languages