HEXAW: a tiny time machine for WebAssembly

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

I once wrote a Z80 game on a Videoton TV Computer. I still miss typing an instruction and seeing the exact bytes it becomes.

WebAssembly brought back the possibility. WAT brought me a parenthesis jungle. My brain wanted an assembler listing.

So I started building HEXAW: a new, experimental text format for WASM, with readable mnemonics and a retro assembler feeling.

It is still totally beta. The syntax and tooling are evolving. Expect rough edges.

The CLI can assemble HEXAW into .wasm, dump binaries back into readable instructions, and step through code forwards and backwards. There is also an AI mentor you can ask when the bytes stop making sense.

Clone the repository, run npm ci, and save the example below as factorial.hexaw in the repository folder. Then:

npm run shell -- factorial.hexaw

Inside the shell:

CALL factorial 5
G
BACK

That computes 5! = 120, then reverses the last execution step.

The shell also has an SST-inspired A mode: type an instruction, press Enter, see its hex bytes, and continue at the next address. An empty Enter applies the completed draft.

Here is the factorial loop:

EXP "factorial" 0
FN 0
  PAR 0       ; n
  RES
  LOC 1       ; result

  CONST 1
  SET 1
  BLOCK
    LOOP
      GET 0
      EQZ
      BRIF 1  ; leave the outer block when n = 0

      GET 1
      GET 0
      MUL
      SET 1

      GET 0
      CONST 1
      SUB
      SET 0
      BR 0    ; repeat the loop
    END
  END
  GET 1
END

The default numeric type is i32. Prefixes L, F, and D select i64, f32, and f64. This is still WASM: a typed stack, locals, and structured control flow.

The dump keeps the bytes beside the instructions:

00000032 : 20 00 : GET 0
00000034 : 45    : EQZ
00000035 : 0D 01 : BRIF 1

Source: https://github.com/Pengeszikra/hexaw

I built it with Codex, using my TS+|> TypeScript fork for the CLI and a shared assembly/debugging engine.

The mentor uses the open-weight gpt-oss-120b model through Groq, carried over from my Terminal Is Your Friend project. Its teaching material now focuses on HEXAW and WASM, grounded in the actual opcode table and a limited snapshot of the current code, assembly draft, VM state, and recent errors.

With GROQ_API_KEY set before starting the shell, I can ask:

// What does BRIF 1 mean here?
AI ERROR

The reply arrives while I keep working. Suggested code stays an example until I enter it myself.

I can change the language, the compiler fork, and the mentor’s teaching material. Anyone else can too: HEXAW is MIT-licensed.

An open-weight model leaves a future route to self-hosting. Today the mentor uses Groq’s hosted API; the assembler and debugger work locally.

Less manual byte decoding. Fewer trips between code, documentation, and a separate AI chat.

Apparently I am lazy enough to want all of that in one terminal. Just not lazy enough to leave assembly alone.