How to use it

Before you start (one time only)

1. Make sure AFK Journey is installed and you've opened it at least once (so its data is downloaded).

2. Open the Terminal app: press ⌘ Space, type Terminal, press Enter.

3. Copy this box and paste it into Terminal, then press Enter. It installs three small helper libraries.

python3 -m pip install --user pycryptodome lz4 lupa

That's it for setup. You won't need to do this again.

Get everything (the full extraction)

Copy the whole box, paste into Terminal, press Enter. This pulls all the hero/skill tables and every language you have installed. It takes a few minutes (it processes around 800 skill files).

cd ~/git-repos/afkj-parser
./afkj-extract

When it finishes you'll see DONE and how long it took. Your files are in the out folder.

Update the feed for stargazer (after a game update)

With the game closed, paste this box. It reads the game (including all 17 languages from the game's server), then builds the feed stargazer imports and checks it.

cd ~/git-repos/afkj-parser
./afkj-extract --locales-from cdn
./afkj-parse build

The last line says PASSED or FAILED. Above it, one line per check, and a summary of what changed since the last time stargazer imported, such as new heroes or a new season's artifacts. Lines starting with ! are worth a read; lines starting with ✗ are why it failed, with the fix suggested on the line under them. When it fails, the feed stargazer reads is left as it was.

To see exactly what changed for one hero (old text above new, changed words marked):

./afkj-parse diff --hero karma

Then import in stargazer as usual (npm run import:seasonal there). Once that's done, come back and record this feed as the one stargazer has, so the next update is compared against it:

cd ~/git-repos/afkj-parser
./afkj-parse accept

Update while away from the local machine

Travelling with only a tablet? The update works without the local machine and without the game. A Claude Code session on the web does it from a public copy of the game data. On claude.ai/code, start a session with both afkj-parser and stargazer selected, and send it this:

Update stargazer from the fallback data and push a branch: follow docs/integrations.html section 2.3.

It builds the feed, imports it into stargazer and pushes a branch there. Read the changes on that branch, then merge it. Text and numbers update this way. New pictures, a new hero's page and the filter check wait until you are home, because they need the game installed on the local machine. The full steps, and what has not been tried yet, are in Integrations §2.3.

Check stargazer's filters (after a game update or a new hero)

With the game closed, paste this box. It reads every hero's battle code, compares the filter tags with stargazer, rebuilds the Debuff and Haste sweeps and the review page, and lists any debuff or Haste the rows don't cover yet.

cd ~/git-repos/afkj-parser
make audit
open out/tools/stargazer-filter-audit.html

Start at Needs review at the top. It lists heroes new since the last review, heroes in the game data that aren't on stargazer yet, a note if the game data changed, rows the code check found that nobody has reviewed, and Debuff or Haste sweep sites with no row. Treat those rows as a starting point and check them before changing stargazer. Details: Battle scripts §8.

Once everything is reviewed and stargazer is updated, record it so the next check compares against it:

python3 tools/stargazer_filter_audit.py --mark-reviewed

Open the results folder

To see what came out, paste this — it opens the folder in Finder:

open ~/git-repos/afkj-parser/out

Inside raw you'll find locales (the game text, one file per language) and tables (heroes, skills, and more). api is the feed stargazer imports, once you've built it (next section).

Other things you can do

Preview first, without saving anything

Shows what it would do — which languages you have, what's missing — and writes nothing.

cd ~/git-repos/afkj-parser
./afkj-extract --list

Get just the text / languages (fast)

cd ~/git-repos/afkj-parser
./afkj-extract --only loc

Get just a few specific tables (fast)

Example: only heroes and their status effects.

cd ~/git-repos/afkj-parser
./afkj-extract --only tables --tables Unit,SkillBuff

Add another language

The tool can only save languages your game has actually downloaded. To add one: open AFK Journey, switch to that language in Settings (let it download), quit the game, then run:

cd ~/git-repos/afkj-parser
./afkj-extract --only loc

Tip: run the Preview box above first — it lists which languages are present vs missing.

Or skip selecting languages: this downloads all 17 straight from the game's servers, checking each file as it arrives. It first checks that the servers have the same game version you have installed; if not, open the game, let it update, quit it, and run it again.

cd ~/git-repos/afkj-parser
./afkj-extract --only loc --locales-from cdn

Either way the languages land in out/raw/locales/.

Get the images (hero icons / art)

The game's pictures can be saved as normal PNG files. There are a lot (~12,000), so this is separate and you'll usually want to grab just some. First, one extra one-time install:

python3 -m pip install --user Pillow texture2ddecoder

Then, for example, just the hero head icons:

cd ~/git-repos/afkj-parser
./afkj-extract --only textures --textures "*herohead*"

They land in out/raw/textures. Leave off --textures "*herohead*" to get everything (slow — thousands of files). Change the text in quotes to match other names (e.g. "*avatar*").

Get one hero's pictures

Type the hero's name as it appears in the game (capital letters don't matter). This saves every picture of that hero: their portrait, the big recruitment art, skins, and small icons. Needs the image install above.

cd ~/git-repos/afkj-parser
./afkj-extract --only textures --hero Karma

It prints which hero it found (e.g. Karma -> #132 Karma (codename 'doublehead')). Inside the game's files, heroes go by a number and a codename rather than their name, so the file names use those. Where to look in out/raw/textures/icon:

For several heroes at once, separate the names with commas: --hero "Karma,Ravion".

Get hero portraits for stargazer

This saves every hero's portrait (the picture on the hero card) with the same file names stargazer uses, plus each hero's skin portrait. Needs the image install above.

cd ~/git-repos/afkj-parser
./afkj-extract --only portraits --reference ../stargazer/src/assets/images/character

What you get in out/images/heroes:

A full portrait run replaces the folder after extraction succeeds. A run with --hero updates only those heroes and keeps the other pictures. Failed extraction preserves the previous folder. To copy the pictures into stargazer:

cd ~/git-repos/afkj-parser
python3 -c "import csv, shutil; [shutil.copy('out/images/heroes/' + r['file'], '../stargazer/src/assets/images/character/') for r in csv.DictReader(open('out/images/heroes/manifest.csv')) if r['in_reference'] == 'yes']"

That copies only the heroes stargazer already has (in_reference is yes).

Get artifact pictures (for a new season)

This saves the artifact pictures with the file names stargazer and chaldea use. Needs the image install above.

cd ~/git-repos/afkj-parser
./afkj-extract --only artifacts

What you get in out/images/artifacts:

When a new season starts, tools/seasonal_icons.py picks this season's pictures out by that column and makes the .webp and .avif copies. You don't need to replace the six permanent ones or the current season's: stargazer's six are cleaner copies than the game's, and chaldea's match. The checks behind that are in Architecture → Artifact & icon export, which also covers stargazer's other icons (class, faction and so on). The game's copies of those aren't better either.

Get Phantimal pictures (for a new season)

cd ~/git-repos/afkj-parser
./afkj-extract --only phantimals

You get out/images/phantimals/: one picture per Phantimal this season (gervan.png, …), named like chaldea's dist/img/seasonal/phantimal/, plus a manifest.csv. A Phantimal that fights as two units (Wedge of Matter and Wedge of Power) gets two pictures.

If something goes wrong