Let an AI coding agent derive the layout of an unknown binary format from sample files, with evidence for every claim, and emit artifacts that other tools can use.
probeeach sample.comparethe samples to separate constant and variable regions.infercandidate fields.hypothesize: the agent writes a candidate layout.verifythe layout against every sample.- Repeat 3 to 5 until every sample parses.
emitthe specification,.ksy, parser and tests.
Every tool is available through MCP and through the CLI with the same input and output shapes.
| Tool | Input | Output |
|---|---|---|
probe |
one file, optional byte range | size, magic candidates, entropy per block, printable strings with offsets, alignment, repeated patterns |
compare |
two or more files | regions that are identical, regions that differ, regions whose length tracks file size |
infer_fields |
files, optional region | candidate lengths, counts, offsets, endianness and version fields, each with a confidence score and the samples that support it |
detect_compression |
file, offset | detected standard compression and the decompressed size; decompressed bytes are written to a work directory |
verify_layout |
files and a layout in hexsleuth layout JSON | per sample: parsed tree, first failing field, unread bytes |
read_bytes |
file, offset, length | hex and ASCII view, with optional interpretation as integers or floats |
emit |
verified layout | Markdown spec, Kaitai Struct .ksy, TypeScript parser, Vitest tests that parse every sample |
A small description language that maps one to one onto Kaitai Struct:
- sequences of fields with types
u1,u2,u4,u8, signed variants,f4,f8, fixed and length-prefixed byte strings, and strings with an encoding - endianness per layout or per field
size,repeatandrepeat-exprfrom earlier fieldsinstancesat absolute offsets for offset tables- nested types
Every finding carries:
- the sample files and byte ranges that support it
- the check that produced it, for example "value equals remaining length in 5 of 5 samples"
- a confidence score from 0 to 1
- known limits, for example "only one sample has a non-empty table"
- High entropy that does not match a supported compression is reported as
possibly-encryptedwith its range. - No tool attempts decryption, key search, XOR guessing or any bypass of protection. This is a hard boundary for the project.
- TypeScript, Node.js 22 or later, ESM.
- MCP server through the official TypeScript SDK.
- Decompression through Node.js built-ins where possible. Add libraries only for LZ4 and Zstandard.
- Tests with Vitest. Fixtures are generated by scripts in the repository, in open formats or formats designed for the tests.
Write each showcase as a step-by-step agent session on an open format:
- PNG chunks
- ZIP local headers and central directory
- WAV RIFF chunks
- A sample format designed for this repository, with an offset table, a string pool and a compressed section
- Executable code analysis. Tools such as REA already cover it.
- A graphical hex editor.