6diss / 6dcli

6dcli — reading and editing a .6diss from a script

6dcli is the console front end, in the 6diss download. What it prints is the listing the GUI draws, from the same disassembler, with the same knowledgebase annotations and the same cross-file xrefs.

It exists for the round trip in Claude integration, Step 3: read a file the way the window reads it, reason about it somewhere else, write the answers back without hand-editing JSON.

Reach for --live first. With it, every command below goes to a running 6diss over the control channel instead of to a file — same verbs, no project argument, and the answers include everything not yet saved. This page is the file-based half: for when nothing is running, or when the project is not the one that is open.

Commands

Addresses are hex, with or without $. rename takes --role sub\|loc\|data and --origin user\|assistant; comment takes --block for a line above rather than beside.

files also takes --pattern 'MON*' and --summary. On a project with more than about fifty files, start with --summary: it groups by name family and reports how many of each, what sizes they come in and where they load, which is the shape of the release. The list of eight hundred names is the least useful true thing 6diss can say about it.

Answers onto disk, and the analyses

These work against the file with no window running.

run is not a C64 — no VIC, no SID, no interrupts, $D000-$DFFF is plain RAM. It runs a routine against a snapshot of the project's memory and tells you what it wrote. Everything that needs a real machine still needs VICE, and that is a boundary rather than a shortfall.

dump --all deserves a note. A project imported from eight disk sides already holds every byte; re-extracting them from the D64s to run a format decoder over them is doing work 6diss has already done, and it throws away the load addresses the project worked out. The manifest carries those.

--live only

The rest of the menu needs a window to run it in — an undo stack, a listing to redraw, and a user watching — so these exist under --live and nowhere else:

find-code, detect and brain print an indexed proposal list and apply nothing. Read it, then run the same command with --apply --accept 0,3,7. That is the review dialog the window opens, kept rather than dropped.

Any <module> above also accepts a glob. region 'MON*' $7c00 $7c0f TextAscii is one decision, so it is one call and one Ctrl+Z rather than sixty-nine of each. The undo depth is what makes this matter rather than the process count: the stack is a hundred steps deep, so a sweep applied one step at a time did not merely make undo tedious, it swallowed every step in front of it. rename, comment and split also take --path, so a list a session has just written is a list 6diss can read.

The note commands are exempt from the rule below, because they never touch the .6diss: a note is a .md in <project>.docs/ beside it, and the project reads whatever is in that folder when it opens. Writing one under a running 6diss is safe, and write-doc on a title the project does not know creates the file and says it will be listed the next time the project is opened. To have it appear now, use --live.

The one rule

6diss writes the whole project file when it saves. A write underneath a running 6diss is gone the moment the user hits Ctrl+S. So rename and comment:

• ask every running instance over the control channel whether it has this project open, and refuse if one does — pointing at --live, which has no such problem;
• copy the project to <name>.6diss.bak before saving.

If no instance answers — an older build, the channel switched off — nothing is known to be at risk and the write goes ahead. --force overrides the refusal, and still means the user must reopen the project rather than save over it.

Reading a listing without drowning

— unclaimed on a line means "this address is inside several files' ranges and none of them owns it" — noise when the address is RAM that overlays share, which in an overlay-based game is most of it. It used to be worse than noise: the note named every candidate, so on an 820-file project an address touched by 250 of them put 250 file names on every line referring to it, and a 24-instruction routine rendered as about 15,000 tokens. The disassembler now names three and counts the rest, and drops the note entirely past a couple of dozen candidates.

If you still want it gone entirely:

6dcli list game.6diss LIBRARY \
  | sed -E 's/ *; (in|also in) [A-Z_0-9, ]*— unclaimed//; s/ +; TBUFFR\+[0-9]+.*//'

The better answer for a long listing is dump, which writes it to a file — then grep it rather than reading it through a pipe.