AGENTS.md

1# AFL++ Fuzzer for Libghostty
2 
3- Build all fuzzer with `zig build`
4- The list of available fuzzers is in `build.zig` (search for `fuzzers`).
5- Run a specific fuzzer with `zig build run-<name>` (e.g. `zig build run-parser`)
6- Corpus directories follow the naming convention `corpus/<fuzzer>-<variant>`
7  (e.g. `corpus/parser-initial`, `corpus/stream-cmin`).
8- Do NOT run `afl-tmin` unless explicitly requested — it is very slow.
9- After running `afl-cmin`, run `corpus/sanitize-filenames.sh`
10  before committing to replace colons with underscores (colons are invalid
11  on Windows NTFS).
12 
13## Important: stdin-based input
14 
15The instrumented binaries (`afl.c` harness) read fuzz input from **stdin**,
16not from a file argument. This affects how you invoke AFL++ tools:
17 
18- **`afl-fuzz`**: Uses shared-memory fuzzing automatically; `@@` works
19  because AFL writes directly to shared memory, bypassing file I/O.
20- **`afl-showmap`**: Must pipe input via stdin, **not** `@@`:
21 
22```sh
23  cat testcase | afl-showmap -o map.txt -- zig-out/bin/fuzz-stream
24```
25 
26- **`afl-cmin`**: Do **not** use `@@`. Requires `AFL_NO_FORKSRV=1` with
27  the bash version due to a bug in the Python `afl-cmin` (AFL++ 4.35c):
28 
29```sh
30  AFL_NO_FORKSRV=1 /opt/homebrew/Cellar/afl++/4.35c/libexec/afl-cmin.bash \
31    -i afl-out/fuzz-stream/default/queue -o corpus/stream-cmin \
32    -- zig-out/bin/fuzz-stream
33```
34 
35If you pass `@@` or a filename argument, `afl-showmap`/`afl-cmin`
36will see only ~4 tuples (the C main paths) and produce useless results.
37 
38## Replaying crashes
39 
40Use `replay-crashes.nu` (Nushell) to list or replay AFL++ crash files.
41 
42- **List all crash files:** `nu replay-crashes.nu --list`
43- **JSON output (for structured processing):** `nu replay-crashes.nu --json`
44  Returns an array of objects with `fuzzer`, `file`, `binary`, and `replay_cmd`.
45- **Filter by fuzzer:** `nu replay-crashes.nu --list --fuzzer stream`
46- **Replay all crashes:** `nu replay-crashes.nu`
47  Pipes each crash file into its fuzzer binary via stdin and exits non-zero
48  if any crashes still reproduce.
49