# rea_session

> **Tool `tools/rea/rea_session.py`** (program, REA). REA on a game's binary from a script, with the project's labels and a saved snapshot.

Run it with `./gameframe run rea_session ARGS` or `python3 tools/rea/rea_session.py`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/rea/rea_session.py).

## Its own help

This is the help text in the tool itself, as `./gameframe tool rea_session` prints it.

```text
REA on a game's binary from a script, with the project's labels and a saved snapshot.

    rea_session.py snapshot BINARY [ADDR ...] [--file F] [--fresh]
    rea_session.py fn BINARY ADDR ... [--file F] [--snapshot-only] [--json]
    rea_session.py labels BINARY [--chunk N]

Common options: --labels FILE (repeatable; the first file wins for an address), --out DIR
(default analysis/rea in the project), --server CMD (default: the `rea` server of the
project's .mcp.json; enable it with ./gameframe mcp --enable rea).

`snapshot` opens BINARY with REA's Ghidra provider (from the old snapshot, unless --fresh), asks
for the dossier (`analyze_function`) of each address, and saves REA's analysis snapshot to
OUT/<binary>.snapshot.json, so the answers add up over runs.

`fn` opens BINARY from that snapshot when there is one, gives REA the project's labels with
`set_addresses_names`, and asks for each address's dossier. It writes each dossier to
OUT/fn/<binary>/<address>.json and prints a short summary with the labels: the function's size,
what refers to it (a vtable slot shows as data), what it calls and its memory reads and writes.
`--snapshot-only` leaves REA's names alone, so warmed functions come from the snapshot.

`labels` writes the labels as `set_addresses_names` input, in chunks, to
OUT/<binary>-names-N.json, for an agent that wants them in its own REA session.

The labels default to labels/names.tsv, labels/names-from-port.tsv and labels/library.tsv in
the project, those that exist, in that order. Only addresses inside BINARY's image (its PE
ImageBase and SizeOfImage) are used, so one labels file can cover several binaries. Ghidra
reads `::` as a namespace, so `::` becomes `__`; a name used twice gets its address appended.

REA 6.7.0, measured on a 2 MB x64 game: the first question of a session waits about 50 s while
Ghidra imports and analyses the binary. A question asked before, in the session or in the
snapshot, takes 0.1 s. A snapshot holds answers to questions, not Ghidra's database: a new
question costs the 50 s again. Each dossier adds 2 to 3 MB to it. Renaming in REA makes the
snapshot's answers stale, and a session with renames cannot save a snapshot. So `snapshot`
renames nothing, and `fn` renames after it opens. Everything this writes describes the game's
code: keep OUT in an ignored folder.
```

## Named by

Skills: [re-rea](/skills/re-rea).