ltms-reader 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +399 -0
- package/LICENSE +21 -0
- package/LICENSE-UNICODE +49 -0
- package/README.md +335 -2
- package/bin/ltms-reader.mjs +16 -0
- package/package.json +32 -4
- package/src/app.mjs +415 -0
- package/src/bidi-table.mjs +354 -0
- package/src/bidi.mjs +252 -0
- package/src/engine.mjs +505 -0
- package/src/guard.mjs +117 -0
- package/src/helper.mjs +127 -0
- package/src/layout.mjs +181 -0
- package/src/lines.mjs +18 -0
- package/src/main.mjs +133 -0
- package/src/reading.mjs +165 -0
- package/src/screen-process.mjs +6 -0
- package/src/screen.mjs +143 -0
- package/src/sources.mjs +134 -0
- package/src/start.mjs +126 -0
- package/src/text.mjs +716 -0
- package/src/view.mjs +337 -0
- package/src/views.mjs +518 -0
- package/src/width-table.mjs +101 -0
package/README.md
CHANGED
|
@@ -1,3 +1,336 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ltms-reader
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A full-screen reader of your own Claude Code sessions, in the terminal: the projects, a project's sessions, a
|
|
4
|
+
session's turns, a turn's prompt, replies and tool calls, and the text behind every address. Read-only, local, no
|
|
5
|
+
network. It is built on [ltms](https://github.com/long-term-memory-structure/long-term-memory-structure)
|
|
6
|
+
(`long-term-memory-structure`), its one dependency: the sessions, turns, calls and hits it
|
|
7
|
+
lists are the ones `ltms index`, `ltms search` and `ltms skeleton` print, with their addresses and counts, so an
|
|
8
|
+
address on its screen is one an agent can be given as it is. Beside them it shows the transcript's own text: a
|
|
9
|
+
prompt's first line, a call's input, and a channel's or a tool's name where ltms prints `(withheld)`, made visible.
|
|
10
|
+
|
|
11
|
+
## Run it
|
|
12
|
+
|
|
13
|
+
Node.js 20 or newer, and a terminal.
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npx ltms-reader # the projects under ~/.claude/projects (or $CLAUDE_CONFIG_DIR/projects)
|
|
17
|
+
npx ltms-reader <projects folder> # another folder of project folders
|
|
18
|
+
npx ltms-reader <file.jsonl> # one transcript
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
A project's own folder (one of those under `~/.claude/projects`) given where its parent was meant opens as that
|
|
22
|
+
project. Or install it once: `npm install -g ltms-reader`, which gives the command `ltms-reader`.
|
|
23
|
+
|
|
24
|
+
It runs on a terminal only: when stdin or stdout is not one (a pipe, a file), it reads nothing and says so. For lines to
|
|
25
|
+
read, to pipe or to give an agent, `ltms` is the command (`npx long-term-memory-structure index|search|skeleton ...`;
|
|
26
|
+
installing `ltms-reader` does not put `ltms` on the PATH, `npm install -g long-term-memory-structure` does).
|
|
27
|
+
|
|
28
|
+
## What it shows
|
|
29
|
+
|
|
30
|
+
| view | its rows | from |
|
|
31
|
+
|---|---|---|
|
|
32
|
+
| Projects | each project folder, with the count of transcripts `ltms index` reads in it, newest first | ltms's walk of the folder |
|
|
33
|
+
| Sessions | one per session, newest first: when it started, its turns, calls, failed calls, compactions, agents | `ltms index` |
|
|
34
|
+
| A session | its turns: the channel (the transcript's own word, made visible, where `ltms skeleton` prints `(withheld)`), the prompt's first line, calls, failed calls; each compaction a row of its own, with its summary's address | the library, as `ltms skeleton` |
|
|
35
|
+
| A turn | its prompt, replies, tool calls (ok, or failed and the error class `ltms skeleton` gives), results, the harness's own notes, each with its address | the library, as `ltms skeleton` |
|
|
36
|
+
| A record | its text, a page at a time, part by part (text, thinking, a tool call's input, a result); its address, kind, time, length and place in the file; `j` shows it as JSON | the transcript's line |
|
|
37
|
+
| Search | a query, then the matching turns by session, with what was searched and what was not (one line, which a narrow screen cuts: at 80 columns, before what was not searched); Enter opens the turn at its first match's row, or at its first row where that match is a thinking block, which a turn's view has no row for | `ltms search` |
|
|
38
|
+
| Open | `:` and an address, as ltms prints it: `<prefix>:L<line>` opens that record (above the turn that lists it as a row; a record no turn lists, as a thinking block, above its session), `<prefix>:T<turn>` that turn | the address rule |
|
|
39
|
+
|
|
40
|
+
A row's address is at the start of the row (Search's lines of coverage and of more turns have none), whole where the row
|
|
41
|
+
is wide enough for it (at 20 columns an agent's is cut with …), and the selected row's is on the last line: a session's
|
|
42
|
+
prefix (the first 8 characters of its file's name; `agent-` and 8 for an agent's), a turn's id (`1a2b3c4d:T003`), a
|
|
43
|
+
record's line (`1a2b3c4d:L120`). Search covers the project on screen, or every project from Projects. An agent's
|
|
44
|
+
transcript is opened by its address, or from a search.
|
|
45
|
+
|
|
46
|
+
It draws from 20 columns and 5 rows. The last line is always the status line (the selected row's address, then `? keys`
|
|
47
|
+
and `q quits` as far as they fit: `q quits` is cut on a screen narrower than the address and 18 columns more), or a
|
|
48
|
+
message in its place: on a screen too low for every line, the line of details above it gives way
|
|
49
|
+
first, then a list's column headings. Under 20 x 5 it says the size it needs, wrapped over the lines it has (on a
|
|
50
|
+
screen too small for all of it, its first lines), and `q` still quits.
|
|
51
|
+
|
|
52
|
+
## Keys
|
|
53
|
+
|
|
54
|
+
| key | does |
|
|
55
|
+
|---|---|
|
|
56
|
+
| ↑ ↓ | move one row (in a record, one line) |
|
|
57
|
+
| PgUp PgDn | move one page |
|
|
58
|
+
| Home End | the first row, the last |
|
|
59
|
+
| Enter or → | open the row |
|
|
60
|
+
| Esc or ← | go back |
|
|
61
|
+
| `/` | search: type the words, Enter runs `ltms search` |
|
|
62
|
+
| `:` | open an address |
|
|
63
|
+
| `r` | in Projects and in a project's Sessions: read the list again, the selection kept on the same row while it is there |
|
|
64
|
+
| `j` | in a record: its JSON, and back |
|
|
65
|
+
| `?` | the keys |
|
|
66
|
+
| `q` or Ctrl-C | quit |
|
|
67
|
+
|
|
68
|
+
While a line is typed: Backspace, Ctrl-U to clear it, Enter, Esc to leave it. A paste is text, never keys (the reader
|
|
69
|
+
turns on the terminal's bracketed paste), but for two things in it: a Ctrl-C character quits, in a line too, though not
|
|
70
|
+
right after an ESC, which is read with it as one key; and an ESC [201~ ends the paste there, what follows it acting as
|
|
71
|
+
keys. Pasted into a line, its new lines become spaces and do not run it. What reaches the reader is the terminal's to
|
|
72
|
+
say: by their sources (read, not run), Alacritty 0.17.0 takes ESC and Ctrl-C out of a paste, Konsole 26.08.3 takes ESC
|
|
73
|
+
out and asks before it pastes a control character, Ctrl-C among them, and the xterm.js of VS Code 1.147.0 writes ESC as
|
|
74
|
+
`␛` and passes Ctrl-C.
|
|
75
|
+
|
|
76
|
+
## Your transcripts, and who sees them
|
|
77
|
+
|
|
78
|
+
- **It shows their text**, prompts, replies, tool inputs and outputs included, to you, on the alternate screen of the
|
|
79
|
+
terminal that is its stdout: it starts only when stdin and stdout are terminals, and draws every frame on stdout. It
|
|
80
|
+
writes their text to no file, pipe or log; a program that records that terminal records what it draws (measured with
|
|
81
|
+
util-linux `script` and tmux's `pipe-pane`). When it quits, it leaves the alternate screen, and nothing of it stays
|
|
82
|
+
(measured with a run's bytes replayed into the xterm.js of VS Code 1.147.0). (ltms itself prints no text of a
|
|
83
|
+
transcript but a call's tool name and a word taken from its input, `grep` or `README` say, which reach the reader
|
|
84
|
+
through the pipes of the ltms commands it runs; this reader is for the person whose transcripts they are.)
|
|
85
|
+
- **It writes no file and uses no network.** It reads the transcripts under the folder it is given, and runs ltms's
|
|
86
|
+
commands (`index`, `search`, `skeleton`) as local processes, which read the same files and write only to the reader.
|
|
87
|
+
Run through `npx`, npm writes files of its own: a log of each run under `~/.npm/_logs`, which names the folder or file
|
|
88
|
+
given (npm 12.2.2 writes a UUID in a path as `***`, a transcript's name among them), and a compile cache under
|
|
89
|
+
`$TMPDIR`; installed (`npm install -g ltms-reader`, then `ltms-reader`), it runs without npm, and without them.
|
|
90
|
+
- An error inside it, in the screen's process or in the command's own, is printed after the terminal is restored, by
|
|
91
|
+
its kind and where in this package it happened, not by its message, which could quote a transcript.
|
|
92
|
+
|
|
93
|
+
## Text on the screen
|
|
94
|
+
|
|
95
|
+
- **Control characters are shown, never sent.** A transcript can hold escape sequences (colours, cursor moves, a
|
|
96
|
+
window's title, OSC 52, which writes the clipboard). Every C0 and C1 control character and DEL is shown as a visible
|
|
97
|
+
escape: ESC as `␛`, the others as `\x07`, `\x9b` and so on; in a text, tabs become spaces and new lines become
|
|
98
|
+
lines, and in a name (a tool's, a channel's) they are shown as `\t` and `\n`; a tool's input is shown as JSON, with
|
|
99
|
+
JSON's escapes. Nothing a transcript holds can move the cursor, set the title, write the clipboard or leave the
|
|
100
|
+
terminal in another mode. A path, `CLAUDE_CONFIG_DIR` or an option it refuses before the screen opens is written the
|
|
101
|
+
same way.
|
|
102
|
+
- **So is what reorders or hides text:** the bidirectional embeddings, overrides and isolates (U+202A to U+202E, U+2066
|
|
103
|
+
to U+2069), the byte order mark (U+FEFF), the line and paragraph separators (U+2028, U+2029) and the tag characters
|
|
104
|
+
(U+E0000 to U+E007F), as `\u202e`, `\u{e0041}` and so on: an override in a transcript cannot reorder the rest of its
|
|
105
|
+
row. The light marks Hebrew and Arabic text use (U+200E, U+200F, U+061C) are written as they are.
|
|
106
|
+
- **Width by grapheme cluster** (`Intl.Segmenter`): combining marks, niqqud and cantillation take no column of their
|
|
107
|
+
own; East Asian wide characters and emoji take two. A line is cut by columns, never inside a cluster, and a space
|
|
108
|
+
where it is cut stays at the end of the line before; a no-break space or a non-breaking hyphen (U+00A0, U+2007,
|
|
109
|
+
U+202F, U+2011: UAX #14's class GL) where it would be cut goes to the next line with the character before it, as UAX
|
|
110
|
+
#14 gives no break before one but after a space or a hyphen, a hyphen-minus only where it does not follow a Hebrew
|
|
111
|
+
letter (LB21a; where that would leave the line before empty, or the next too wide, as on a line of one column, it
|
|
112
|
+
begins the line all the same). What UAX #14 takes as part of the character before it (LB9: its class CM, the marks
|
|
113
|
+
and LRM, RLM, ALM and ZWNJ among it, and ZWJ) is read so: between a Hebrew letter and its hyphen, after the hyphen,
|
|
114
|
+
and on the line it goes to. The figure space (U+2007) is such a no-break space, not a space that hangs at a
|
|
115
|
+
break: a line begins with it where UAX #14 breaks before it, after a space, and, as with the others, where moving it
|
|
116
|
+
would leave a line empty or the next too wide. The wide characters come from a
|
|
117
|
+
table generated from Unicode's `EastAsianWidth.txt`, version 17.0.0 (`src/width-table.mjs`, which names the file's
|
|
118
|
+
sha256; `scripts/width-table.mjs` writes it). Characters of ambiguous width take one column.
|
|
119
|
+
- **Right to left** (Hebrew, Arabic): one layout for every terminal. The reader lays out each line itself (mode
|
|
120
|
+
`reader`, the default), by the Unicode Bidirectional Algorithm (UAX #9, Unicode 17.0.0, written in this package: the
|
|
121
|
+
implicit algorithm with paired brackets, its lines reordered and mirrored, a paragraph's direction from its first
|
|
122
|
+
strong character), and writes it in visual order. A line that holds right-to-left text (a character of UAX #9's class
|
|
123
|
+
R, AL or AN) is written inside a left-to-right override: a left-to-right mark (U+200E, LRM) and U+202D (LRO), in that
|
|
124
|
+
order, right after its first grapheme cluster that takes a column (never at the line's first column: after any ZWSP,
|
|
125
|
+
lone mark or RLM that begins the line, after the first cluster that takes one), and U+202C (PDF) at its end, so that a
|
|
126
|
+
terminal that lays bidirectional text out itself with a left-to-right base for each line (Konsole at its default bidi
|
|
127
|
+
settings) keeps the reader's order instead of reordering it a second time; one that takes a line's base from its first
|
|
128
|
+
strong character (Konsole with "force LTR line direction" unchecked; not measured) would still draw a first cluster
|
|
129
|
+
that is right to left at the line's other end. Nothing else is written (no isolate), and a line without right-to-left
|
|
130
|
+
text, or with no cluster that takes a column, is written as it is. No terminal is detected.
|
|
131
|
+
- Measured on four terminals (on 2026-11-16, and again with 0.1.1's own output on 2026-11-21 and 22): Alacritty
|
|
132
|
+
0.17.0, Konsole 26.08.3, tmux 3.6 and the xterm.js of VS Code's terminal (1.146.0's, 6.1.0-beta.304, run in a
|
|
133
|
+
headless browser, not in VS Code's window: on 2026-11-16 with xterm.js's own Unicode 6 widths, on 2026-11-21 with
|
|
134
|
+
those and with Unicode 11's, VS Code's default; 1.147.0's, 6.1.0-beta.337, gave the same). There, after a line's
|
|
135
|
+
first column, LRM, LRO and PDF take no column where they follow a character, as the reader writes its LRM and LRO;
|
|
136
|
+
xterm.js gives one that follows an escape sequence a column of its own, as it does the reader's PDF after a styled
|
|
137
|
+
segment, the last thing on its row, so that no text moves. Konsole, at its default bidi settings, lays text out
|
|
138
|
+
itself with a left-to-right base for each line, and applies the override from a line's second column on; at the
|
|
139
|
+
first column an LRO is not applied by Konsole, dropped by tmux and given a column of its own by xterm.js (hence
|
|
140
|
+
after the first cluster), and xterm.js with its own Unicode 6 widths gives an isolate (LRI, RLI, PDI) a column
|
|
141
|
+
anywhere (with Unicode 11's, none after a character, one at the first column and after an escape sequence).
|
|
142
|
+
Alacritty, and xterm.js's WebGL renderer (the one VS Code 1.147.0 loads at its default settings), draw the text in
|
|
143
|
+
the order it is written; xterm.js's DOM renderer (VS Code's where WebGL fails to load, or with GPU acceleration off)
|
|
144
|
+
puts a run of cells of one style whose glyphs need the same spacing into one span, which the browser lays out itself
|
|
145
|
+
(measured on 2026-11-22 in headless Chromium with 6.1.0-beta.304 and beta.337: with the Hebrew from a proportional
|
|
146
|
+
font, a span for each letter, both versions in order; with Liberation Mono or Courier New, one span for the row,
|
|
147
|
+
0.1.0's first letter at the row's other end and 0.1.1's row in order; with the Hebrew from a second monospace font,
|
|
148
|
+
a span for each word, and 0.1.1's words after the first reversed in place: a known limit). tmux keeps a mark in the
|
|
149
|
+
cell of the character before it, and redraws that cell to the terminal outside it (with VS Code's xterm.js outside,
|
|
150
|
+
the cells came out as without tmux; with Konsole 26.08.3 outside, measured on 2026-11-22 with tmux's status line
|
|
151
|
+
off, the screen came out pixel for pixel as without tmux). No other terminal was measured (kitty, VTE's, as in GNOME
|
|
152
|
+
Terminal, mlterm, WezTerm, foot, iTerm2, Windows Terminal, GNU screen and the rest are not): one that gives LRM or
|
|
153
|
+
LRO a column shifts such a line, from its second cluster on, by that column; one that gives PDF a column shifts
|
|
154
|
+
nothing, the column falling after the line's end, and on a line as wide as the screen (wrapping is off) taking the
|
|
155
|
+
place of its last character (both modelled on xterm.js with that width changed, not run on such a terminal). Not
|
|
156
|
+
measured either: how Konsole joins Arabic letters that come to it in visual order, under the override and across the
|
|
157
|
+
LRM after the first one. A line whose first cluster that takes a column is itself right to left keeps that cluster
|
|
158
|
+
outside the override; the LRM after it keeps it first on Konsole (measured with the reader in Konsole 26.08.3, its
|
|
159
|
+
default bidi settings, on two Hebrew first letters without points, a vav and a final nun: 0.1.0 drew it at the
|
|
160
|
+
line's other end, 0.1.1 at column 0; a pointed or an Arabic first letter was not run).
|
|
161
|
+
- `LTMS_READER_BIDI=terminal` writes the text as stored instead (mode `terminal`), with a right-to-left mark (RLM) at
|
|
162
|
+
the end of each line of a right-to-left paragraph (before the whitespace that ends the line; none after the lines of
|
|
163
|
+
a left-to-right paragraph, though they hold Hebrew), for a terminal that lays bidirectional text out itself (on
|
|
164
|
+
Konsole, measured after a Hebrew letter, the RLM puts the paragraph's end punctuation where it belongs, though its
|
|
165
|
+
brackets are not mirrored; after a left-to-right word or a path it would not, by a model of Konsole's layout
|
|
166
|
+
calibrated on its measured rows); `LTMS_READER_BIDI=reader` is the default; a value it does not take is refused.
|
|
167
|
+
Konsole is not detected: it gets the reader's layout, as every terminal does, over ssh too, where `KONSOLE_VERSION`
|
|
168
|
+
does not reach the reader.
|
|
169
|
+
|
|
170
|
+
A paragraph is a cell of a list, the reader's own words before a transcript's text being a paragraph of their own, or
|
|
171
|
+
a text wrapped into lines: a line of a record's text (its lines share its direction), a message, an error. A wrapped
|
|
172
|
+
paragraph's levels are resolved once, and each of its lines is reordered from them, as UAX #9 lays out a paragraph
|
|
173
|
+
broken into lines (its section 3.4): a line reads as its words do in the whole paragraph, the comma that ends a line
|
|
174
|
+
where the sentence has it. Each such line is laid out whole, its spaces at either end with the rest: a space that ends
|
|
175
|
+
a line takes the paragraph's direction (L1), so that in a right-to-left paragraph it is drawn at the line's left. A
|
|
176
|
+
record's text is cut into lines by columns: the whitespace where a line breaks stays at the end of the line before, as
|
|
177
|
+
UAX #14 has it, drawn there where the line has room for it, and past the screen's edge, not drawn, where it does not.
|
|
178
|
+
A message is broken at its spaces, and the space where a line breaks hangs, as UAX #14 has the whitespace at a break:
|
|
179
|
+
it is in no line, and is not drawn, though the line has room for it; whitespace that ends a message after a break
|
|
180
|
+
hangs too, and makes no line of its own. Either way no line but a paragraph's first begins with whitespace that hangs
|
|
181
|
+
(the figure space, a no-break space, does not hang). A long line of a list is cut in logical order, its beginning
|
|
182
|
+
kept, then laid out by itself, the spaces at its ends (a cell's padding) where they are. A path or a URL in a line
|
|
183
|
+
(`/home/...`, `~/...`, `src/...`, `https://...`) that begins the line or follows a space, an opening bracket or quote,
|
|
184
|
+
`=` or a hyphen is laid out as one left-to-right unit, up to the next space, its parts in order and a Hebrew name in
|
|
185
|
+
it reading right (UAX #9's higher-level protocol HL4), in pieces where a line breaks inside it, as an isolate is; one
|
|
186
|
+
right after Markdown's opening backtick, `**` or `*`, or right after a colon or a comma, is not (in a right-to-left
|
|
187
|
+
line, `/home/user/x.txt` in backticks reads `home/user/x.txt/`); one right after an opening `_` or `__` is one, the
|
|
188
|
+
markers in it, where that marker begins the line or follows a space, an opening bracket or quote, `=` or a hyphen
|
|
189
|
+
(inside bold, `**_/home/x_**`, it is not); and one that follows a space inside any of these markers is one, the
|
|
190
|
+
closing marker with it when it follows the path directly, which a right-to-left line lays out on the path's right (a
|
|
191
|
+
known limit); a path with a space in it is laid out as two, in a right-to-left line in the other order. Each cluster
|
|
192
|
+
is kept whole, its marks after its letter, as a terminal draws them, and so is a mark after characters UAX #9 removes
|
|
193
|
+
(a soft hyphen, ZWSP, WJ: clusters of their own), with the letter before them; the text is aligned left, so the
|
|
194
|
+
columns stay. Checked against Unicode's conformance test (BidiCharacterTest.txt: every case without an explicit
|
|
195
|
+
formatting character, which the reader shows as an escape and never applies) and against GNU FriBidi: its command for
|
|
196
|
+
a line, its library for a paragraph wrapped into lines.
|
|
197
|
+
- Colour follows [NO_COLOR](https://no-color.org): set, there is none; the selected row is still drawn in reverse.
|
|
198
|
+
|
|
199
|
+
## Limits
|
|
200
|
+
|
|
201
|
+
- A transcript is read into memory whole, in the reader's own process. One over a tenth of Node's memory limit is
|
|
202
|
+
refused with its size and that limit (the size rounded up, the limit down, so that the two differ) and the
|
|
203
|
+
`NODE_OPTIONS=--max-old-space-size=...` that would let it be read (the rule ltms's commands follow, so the lists and
|
|
204
|
+
the reader agree on which files can be read while Node's memory limit is the same for both: the reader runs ltms's
|
|
205
|
+
commands without its own `NODE_OPTIONS` or flags); one over 480 MB cannot be read at all.
|
|
206
|
+
Node's memory limit is its heap's, or, where `--max-old-space-size` or `--max-old-space-size-percentage` sets the old
|
|
207
|
+
space (in `NODE_OPTIONS` or on node's command line), the old space's: a transcript's parse is kept there, and the
|
|
208
|
+
heap's limit holds beside it a reserve for new objects that the old space does not size (with
|
|
209
|
+
`--max-old-space-size=16`, measured in containers or a scope of 3 GB: a heap limit of 64 MB on Node 20 and 22, 208 MB
|
|
210
|
+
on Node 24, 112 MB on Node 26; the same for Node 20 and 24 under 6 GB, and for Node 24 on machines of 16 and 25 GB).
|
|
211
|
+
By the heap's limit, under an old space of 16 MB, Node 24 took in a transcript of 12 MB and ran out of memory.
|
|
212
|
+
- A record is shown when its view (up to 16 times the record's size) fits beside the transcript's (up to 8 times the
|
|
213
|
+
file's) in nine tenths of Node's memory limit, and so does what writing the JSON the view writes of it takes, with
|
|
214
|
+
12 MB beside it, the reader's own: JSON is indented once more at each level a value is nested in, so that a record
|
|
215
|
+
nested deep writes JSON hundreds of times its size (a list nested 990 deep, on a line of 0.8 MB: 381 MB). That JSON is
|
|
216
|
+
measured by walking the record, before any of it is written, and writing it is taken to need 1.5 times its size.
|
|
217
|
+
Both were measured against the old space, on Node 20, 22, 24 and 26: the reader alone needed 7 to 9 MB, and writing
|
|
218
|
+
a list nested deep up to 1.04 times its JSON on Node 22, 24 and 26 and up to 1.41 times on Node 20. A record that does
|
|
219
|
+
not fit is refused before it is drawn, with its size and the `NODE_OPTIONS` that would show it. Its lines are laid out
|
|
220
|
+
a page at a time.
|
|
221
|
+
- The screen runs in a process of its own, which the command waits for. If that process ends without restoring the
|
|
222
|
+
terminal (Node's memory running out aborts it), the command restores it, then prints what Node said and what happened.
|
|
223
|
+
An error in the command's own process (a module loaded through `NODE_OPTIONS` or `--import` that throws, say) ends the
|
|
224
|
+
screen by its own way out (SIGTERM; if it has not ended within 2 s, SIGKILL, and the command restores the terminal),
|
|
225
|
+
then is printed after the restore, and the command exits with 1. If the command's own process is killed (SIGKILL),
|
|
226
|
+
the screen's process learns of it (an IPC channel between the two closes), restores the terminal and ends; if both
|
|
227
|
+
are killed at once (a whole cgroup, as systemd-oomd does), nothing is left to restore it (reasoned, not run).
|
|
228
|
+
- Under an interactive shell with job control, that shell takes the terminal back as soon as the command's process is
|
|
229
|
+
killed, racing the screen's process. The screen's process then writes the leave sequence and leaves the terminal's
|
|
230
|
+
modes to the shell (it puts back the modes it started with only where they are still the screen's raw ones, as
|
|
231
|
+
under a shell that sets none).
|
|
232
|
+
Measured on 2026-11-16, beside the shells a stand-in for a job-control shell that sets no modes: a pseudo-terminal
|
|
233
|
+
of 80 x 24, the shell at its prompt, the reader started from it,
|
|
234
|
+
SIGKILL to the command's process once its frame is up; 10 runs for each of bash 5.3.20, zsh 5.9.2 (`-f`, and `-f`
|
|
235
|
+
with `ttyctl -f` typed first), fish 4.9.3 and the stand-in. The modes 1.5 s after were the shell's own, as at its
|
|
236
|
+
prompt, 10 of 10 for bash, zsh with `ttyctl -f`, fish and the stand-in; a line typed then came back once, 10 of 10,
|
|
237
|
+
for bash, both zsh and the stand-in. What stays: bash, both zsh and the stand-in wrote their prompt before the leave
|
|
238
|
+
sequence, 10 of 10 each (fish 0 of 10), on the alternate screen, where it is not seen (bash 4.0 to 4.9 ms after the
|
|
239
|
+
kill, zsh 4.1 to 9.2, zsh with `ttyctl -f` 3.9 to 5.1, the stand-in 3.7 to 5.1): the shell waits at it, and the next
|
|
240
|
+
line given to it brings a prompt back. And zsh without `ttyctl -f` took the modes the killed command left as its own
|
|
241
|
+
(10 of 10: its iflag and lflag not those at its prompt), so that the commands it ran next had the keyboard's signals
|
|
242
|
+
(Ctrl-C) and flow control off, `-isig -ixon`, 10 of 10; with `ttyctl -f` (in `.zshrc`) they had them on, 10 of 10.
|
|
243
|
+
- A list of sessions waits for `ltms index` to read every transcript of the project (on one machine, 39 s for a project
|
|
244
|
+
of 385 sessions, by ltms's own README), and a search for `ltms search`; the screen says what is being read and for
|
|
245
|
+
how long. A list that took 3 s or more is kept: opened again after its files changed, it is shown as it was read, and
|
|
246
|
+
says when that was and how many files changed since; `r` reads it again (as it reads Projects again), and so does
|
|
247
|
+
`ltms-reader` started again.
|
|
248
|
+
- Some clusters are drawn wider by some terminals than by the cluster rule (an Indic conjunct, an emoji sequence a
|
|
249
|
+
terminal does not join): the rest of the row is drawn that much further right, and a row that then reaches past the
|
|
250
|
+
screen's edge stops there, each character past it written over the last column (measured on VS Code 1.147.0's
|
|
251
|
+
xterm.js, its headless build).
|
|
252
|
+
- On a narrow screen some rows are wider than it: the line that says what is being read
|
|
253
|
+
(`reading the sessions with ltms index`, a transcript's name, `searching with ltms search`), which is not cut to the
|
|
254
|
+
screen's width, and the search line where its prompt, which names what is searched, fills the screen (the text typed
|
|
255
|
+
and the cursor go past it); measured at 25 columns, the first 38 columns wide, or 30 with a transcript's name, and the
|
|
256
|
+
search line 26, and at 30 columns, 38 and 31. The reader turns wrapping at the last column off, so a terminal
|
|
257
|
+
stops such a row at its edge, the edge's cell holding the last character written to the row (measured on VS Code
|
|
258
|
+
1.147.0's xterm.js, its headless build; on the other terminals reasoned, not measured). A known limit, left as it is.
|
|
259
|
+
- A paragraph's levels are resolved once, when a line of it is first drawn, and kept for the last two drawn of 4,096
|
|
260
|
+
UTF-16 code units or more (a character past U+FFFF counts two). For a record of one paragraph of 4,000,000
|
|
261
|
+
characters (`אבג ` 1,000,000 times), measured on 2026-11-22 on one machine, the first frame of a page in its middle
|
|
262
|
+
took 157 to 190 ms on Node 26.13.1 (6 runs), and the 20 frames after it a median of 11.6 to 12.0 ms at 200 x 60 and
|
|
263
|
+
6.9 to 7.0 at 80 x 24; the levels alone 141 to 149 ms (3 runs), and 144 to 148 on Node 20.20.2 (2 runs). A line finds
|
|
264
|
+
the paths in it by a binary search of its paragraph's: in a right-to-left paragraph of 200,000 paths (3,200,004
|
|
265
|
+
characters), the first frame took 160 to 173 ms at 80 x 24 (3 runs), and a page at its start, its middle and its end
|
|
266
|
+
1.5 to 2.3 ms at 80 x 24 and 4.6 to 7.6 at 200 x 60.
|
|
267
|
+
- On Node 20, a long line of text that is not ASCII is laid out about three times slower than on Node 26: Node 20's
|
|
268
|
+
grapheme segmenter is slower, and walked over one long string it costs more at each cluster the longer the string is
|
|
269
|
+
(on Node 20.20.2, 4.7 to 4.9 us a cluster at 10,000 units and 118 to 121 at 80,000 for Hebrew, mixed or CJK text; 4.3
|
|
270
|
+
and 28 for ASCII), so the reader walks a long line 256 units at a time. Measured on the record of 4,000,000 characters
|
|
271
|
+
above, at 80 columns: its lines counted in 3.6 to 3.9 s on Node 20.20.2, against 1.15 to 1.23 s on Node 26.13.1 (a
|
|
272
|
+
record of the same size in ASCII: 15 to 16 and 16 to 20 ms).
|
|
273
|
+
|
|
274
|
+
Exit status: 0 after `q`; 130 after Ctrl-C or SIGINT; 129 after SIGHUP; 143 after SIGTERM; 1 after an internal error;
|
|
275
|
+
2 when it is refused before the screen opens (not a terminal, a usage error, a path that is not a folder or a `.jsonl`);
|
|
276
|
+
128 and a signal's number when a signal the screen cannot handle ended its process (134, SIGABRT, when Node's memory ran
|
|
277
|
+
out), the terminal restored all the same.
|
|
278
|
+
|
|
279
|
+
## Development
|
|
280
|
+
|
|
281
|
+
```sh
|
|
282
|
+
npm install
|
|
283
|
+
npm test
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
`npm test` runs `node --test test/*.test.mjs`, the pattern expanded by the shell, which runs the test files on Node 20,
|
|
287
|
+
22, 24 and 26 alike. Given the folder `test/` instead, Node 20 runs every module under it as a test, the fixtures too,
|
|
288
|
+
and Node 22 and 24 run none: they take the folder for a module, and fail. The whole suite was run on five Node lines on
|
|
289
|
+
2026-11-22, at this release's code, by default with no failure: Node 26.13.1, 444 tests, 444 passed (GNU FriBidi 1.0.18
|
|
290
|
+
there, its command and its library); Node 24.18.0 on a second machine, 444 tests, 444 passed (GNU FriBidi 1.0.18 there
|
|
291
|
+
too); Node 24.22.3, 22.23.3 and 20.20.2 in docker (the images node:24-slim, node:22-slim and node:20-slim, as a user who
|
|
292
|
+
is not root), 444 tests each, 436 passed and 8 skipped, as there is no GNU FriBidi, no python3 (which the five tests of
|
|
293
|
+
FriBidi's library run) and no Electron in them. Each with the pinned Unicode files named (`LTMS_READER_UCD`,
|
|
294
|
+
`LTMS_READER_EAW`). So it was under `NODE_OPTIONS=--max-old-space-size=500` on each line, and under `=100` on each but
|
|
295
|
+
Node 20 (no test reads the environment's `NODE_OPTIONS` where it means none, and the test of a turn of 33,000 calls
|
|
296
|
+
reads it in a process of its own): on Node 20 under `=100`, the process of the record view's tests was ended by
|
|
297
|
+
SIGABRT in some runs, on 2026-11-22 in 2 of 5 runs of the whole suite and 9 of 20 of that file alone, in a second set 3
|
|
298
|
+
of 5 and 6 of 20, and in a third, at this release's code, 2 of 5 and 5 of 20 (Node's heap ran out in its test of a
|
|
299
|
+
record nested 990 deep, a test that gives the record rule more memory than its process has, after the file's test of a
|
|
300
|
+
paragraph of 200,000 paths: the CHANGELOG's Tests line). The tests run the session, turn and record views (as text and
|
|
301
|
+
as JSON) at 80 x 24 and 200 x 60 over ltms's
|
|
302
|
+
own synthetic transcripts (`test/fixtures/ltms`) and the reader's (`test/fixtures/hebrew-english.jsonl`, `escapes.jsonl`
|
|
303
|
+
and `channels.jsonl`, written by `node test/fixtures/make-fixtures.mjs`), Projects and Sessions at both sizes and Search
|
|
304
|
+
at 80 x 24, compare what each row says with ltms's own commands, read every byte the reader writes for a transcript full
|
|
305
|
+
of escape sequences, and run it end to end in a pseudo-terminal (`script`, on Linux). `LTMS_READER_FIXTURES=<folder>`
|
|
306
|
+
adds every `.jsonl` under a folder to the views' test (the core's own `test/fixtures`, say). The width table's
|
|
307
|
+
regeneration is checked when `LTMS_READER_EAW` names the pinned `EastAsianWidth.txt`; the bidirectional table's
|
|
308
|
+
regeneration, and Unicode's conformance test of the algorithm (`test/bidi.test.mjs`, which reports how many cases passed
|
|
309
|
+
and failed), when `LTMS_READER_UCD` names a folder holding the pinned files (`scripts/bidi-table.mjs` names each with
|
|
310
|
+
its sha256); GNU FriBidi's layout of the right-to-left page and fixtures is compared with the reader's where `fribidi`
|
|
311
|
+
is on the PATH (or `LTMS_READER_FRIBIDI` names it); and each line of paragraphs wrapped into lines (the fixtures', and
|
|
312
|
+
random ones) with its library's, where `python3` can load `libfribidi` (`test/fribidi-lines.py`;
|
|
313
|
+
`LTMS_READER_LIBFRIBIDI` names the library, `LTMS_READER_PYTHON` the Python); and its command with a left-to-right base
|
|
314
|
+
(`fribidi --ltr`, standing for a terminal that lays each line out with one, as Konsole does at its default settings)
|
|
315
|
+
over the reader's own rows whose first cluster is right to left, a pointed and an Arabic one among them. GNU FriBidi
|
|
316
|
+
1.0.18 lays some paragraphs out otherwise than UAX #9 (brackets next to a nonspacing mark): a line on which the reader
|
|
317
|
+
and FriBidi's library differ is laid out by the tests' own reference of UAX #9 too (`test/uba-reference.mjs`, checked on
|
|
318
|
+
`BidiCharacterTest.txt`, every case, and on `BidiTest.txt` when the folder holds it), and counts as FriBidi's
|
|
319
|
+
difference, said and not failed, where FriBidi differs from the reference and the reader does not:
|
|
320
|
+
|
|
321
|
+
```sh
|
|
322
|
+
curl -sS --fail -o EastAsianWidth.txt https://www.unicode.org/Public/17.0.0/ucd/EastAsianWidth.txt
|
|
323
|
+
mkdir ucd && for f in extracted/DerivedBidiClass.txt UnicodeData.txt BidiBrackets.txt BidiMirroring.txt BidiCharacterTest.txt BidiTest.txt; do
|
|
324
|
+
curl -sS --fail -o "ucd/${f##*/}" "https://www.unicode.org/Public/17.0.0/ucd/$f"; done
|
|
325
|
+
LTMS_READER_EAW=EastAsianWidth.txt LTMS_READER_UCD=ucd npm test
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
`src/view.mjs`, `src/layout.mjs`, `src/engine.mjs`, `src/lines.mjs` and `src/helper.mjs` are the view layer the LTMS
|
|
329
|
+
Reader extension for VS Code shares: it takes them from this package.
|
|
330
|
+
|
|
331
|
+
## License
|
|
332
|
+
|
|
333
|
+
MIT (`LICENSE`). `src/width-table.mjs` and `src/bidi-table.mjs` are derived from the Unicode Character Database, version
|
|
334
|
+
17.0.0 (`EastAsianWidth.txt`; `DerivedBidiClass.txt`, `UnicodeData.txt`, `BidiBrackets.txt` and `BidiMirroring.txt`;
|
|
335
|
+
© 2025 Unicode, Inc.), under the Unicode License v3: its copyright and permission notice is in `LICENSE-UNICODE`, which
|
|
336
|
+
the package ships, and at the head of each table.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// bin/ltms-reader.mjs — the reader's command: a full-screen reader of Claude Code transcripts, on a terminal only. What
|
|
3
|
+
// it does before the screen opens (the help, the version, a usage error, the refusals) it does here (src/main.mjs's
|
|
4
|
+
// before); the screen runs in a process of its own, which this one waits for, and the terminal is restored here when
|
|
5
|
+
// that process ends without restoring it, as a heap run out ends it (src/guard.mjs), and its own errors are reported
|
|
6
|
+
// here after the restore. The exit code is the screen's, or 1 when this process failed itself; it exits as soon as the
|
|
7
|
+
// screen's process has ended and the restore and the reports are written (whatever an error left running here).
|
|
8
|
+
import { isatty } from 'node:tty';
|
|
9
|
+
import { guard } from '../src/guard.mjs';
|
|
10
|
+
import { before } from '../src/main.mjs';
|
|
11
|
+
|
|
12
|
+
const argv = process.argv.slice(2);
|
|
13
|
+
// only whether they are terminals is read of stdin and stdout here: this process never reads the terminal
|
|
14
|
+
const b = before(argv, { stdin: { isTTY: isatty(0) }, stdout: process.stdout, stderr: process.stderr, env: process.env });
|
|
15
|
+
if (typeof b === 'number') process.exitCode = b;
|
|
16
|
+
else process.exit(await guard(argv));
|
package/package.json
CHANGED
|
@@ -1,6 +1,34 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ltms-reader",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "A terminal reader of your own Claude Code sessions: the turns, the tool calls, the compactions, and the text behind every address ltms prints. Read-only, local, no network.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"ltms-reader": "bin/ltms-reader.mjs"
|
|
8
|
+
},
|
|
9
|
+
"imports": {
|
|
10
|
+
"#ltms": "long-term-memory-structure",
|
|
11
|
+
"#ltms/cli": "long-term-memory-structure/dist/cli.js",
|
|
12
|
+
"#ltms/package.json": "long-term-memory-structure/package.json"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"bin/",
|
|
16
|
+
"src/",
|
|
17
|
+
"CHANGELOG.md",
|
|
18
|
+
"LICENSE-UNICODE"
|
|
19
|
+
],
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=20"
|
|
22
|
+
},
|
|
23
|
+
"scripts": {
|
|
24
|
+
"test": "node --test test/*.test.mjs"
|
|
25
|
+
},
|
|
26
|
+
"dependencies": {
|
|
27
|
+
"long-term-memory-structure": "^0.3.0"
|
|
28
|
+
},
|
|
29
|
+
"license": "MIT",
|
|
30
|
+
"repository": {
|
|
31
|
+
"type": "git",
|
|
32
|
+
"url": "git+https://github.com/long-term-memory-structure/ltms-reader.git"
|
|
33
|
+
}
|
|
34
|
+
}
|