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.
- Pure TypeScript, zero native dependencies: parses
.abcfiles 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-generatedLambdaNclosure classes are folded back into arrow functions; - Classes and functions: class fields, accessors, prototype methods, closures and lexical environments (
local/sendableenv); - 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
.abcfiles on demand; - Web UI: drag & drop a
.abc/.hapfile in the browser and decompile it entirely client-side — nothing is uploaded.
- Node.js ≥ 18
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) |
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:globalRemove 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/gadgetconst { 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 savegadget 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
.hapinput (HarmonyOS ability package, a ZIP container), every.abcentry inside is extracted and decompiled; class files go tooutDir/<abc entry path>/(e.g.ets/modules.abc→out/ets/modules/), andresources.indexis unpacked tooutDir/resources.json; - The
unpack-indexsubcommand can also unpack a standaloneresources.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 --quietdump-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 --stdoutdump 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 outThe 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 --quietimport * 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).
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.tsGeneric 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.
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.abcentry 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.
- Keep improving structured output. Region reduction still falls back to labeled
linear output on irreducible graphs and a few
try/finallyshapes still end as atry/finally not restorednote; the work is inStructureAnalysis.tsandTryFinally.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 = v0spill chains and materialized-condition temporaries that the optimizer currently has to pattern-match.
Bytecode format, instruction semantics, and the resources.index layout follow the official OpenHarmony repositories:
- arkcompiler_runtime_core — ISA definitions (
isa/isa.yaml), bytecode file format, and verifier; - arkcompiler_ets_runtime — the dynamic-language interpreter implementation (execution semantics of each instruction, e.g. the
callthis*withnamefamily); - developtools_global_resource_tool — the
restoolimplementation (ResourceTable::LoadResTable), used to parseresources.index.
See LICENSE.