ltms-reader 0.0.0-stage → 0.1.0
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 +136 -0
- package/LICENSE +21 -0
- package/LICENSE-UNICODE +49 -0
- package/README.md +284 -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 +251 -0
- package/src/engine.mjs +505 -0
- package/src/guard.mjs +116 -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 +127 -0
- package/src/sources.mjs +134 -0
- package/src/start.mjs +123 -0
- package/src/text.mjs +712 -0
- package/src/view.mjs +337 -0
- package/src/views.mjs +518 -0
- package/src/width-table.mjs +101 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0 (2026-11-18)
|
|
4
|
+
|
|
5
|
+
The first version: a full-screen terminal reader of Claude Code transcripts, on ltms 0.3 (`long-term-memory-structure`
|
|
6
|
+
`^0.3.0`, its one runtime dependency).
|
|
7
|
+
|
|
8
|
+
- Three ways in: no argument (the projects under `$CLAUDE_CONFIG_DIR/projects`, else `~/.claude/projects`), a folder of
|
|
9
|
+
project folders (a project's own folder opens as that project), one `.jsonl` transcript. When stdin or stdout is not a
|
|
10
|
+
terminal it reads nothing, exits 2, and names `ltms` as the command for lines. What it refuses before the screen
|
|
11
|
+
opens (a path, `CLAUDE_CONFIG_DIR`, an option) is written with its control characters shown, as on the screen.
|
|
12
|
+
- The views: Projects; Sessions (`ltms index`); a session (its turns and compactions); a turn (its prompt, replies, tool
|
|
13
|
+
calls with their error classes from `ltms skeleton`, results, notes); a record (its text a page at a time, or its JSON
|
|
14
|
+
on `j`); Search (`ltms search`, with what was searched and what was not, on one line that a narrow screen cuts); Open
|
|
15
|
+
(`:` and an address, as ltms prints it). Every row but Search's lines of coverage and of more turns starts with its
|
|
16
|
+
address (cut with … on a screen narrower than it); the selected row's is on the last line.
|
|
17
|
+
- The keys: ↑ ↓ PgUp PgDn Home End move, Enter or → opens, Esc or ← goes back, `/` searches, `:` opens an address,
|
|
18
|
+
`r` reads Projects or a project's Sessions again (the selection kept on its row), `j` shows a record's JSON, `?` the
|
|
19
|
+
keys, `q` or Ctrl-C quits.
|
|
20
|
+
- The screen, with no library: raw mode, keypress events, the alternate screen, the cursor hidden, wrapping at the last
|
|
21
|
+
column off, bracketed paste on (a paste is text, never keys, but for a Ctrl-C character in it, which quits); each
|
|
22
|
+
frame drawn whole, each row erased first, again on a resize; from 20 x 5, the status line (the selected row's address,
|
|
23
|
+
then `? keys` and `q quits` as far as they fit) or a message in its place always the last line drawn; under it, the
|
|
24
|
+
size it needs, wrapped over the lines there are. The terminal is restored on every way out: `q` (exit 0), Ctrl-C and
|
|
25
|
+
SIGINT (130), SIGHUP (129), SIGTERM (143), an uncaught error (1, printed after the restore by its kind and its place,
|
|
26
|
+
not its message). `NO_COLOR` honoured.
|
|
27
|
+
- Text: every C0 and C1 control character and DEL shown as a visible escape (ESC as `␛`, the rest as `\xNN`), so a
|
|
28
|
+
transcript's escape sequences (OSC 52 among them) never reach the terminal as such; and what reorders or hides text
|
|
29
|
+
(bidirectional embeddings, overrides and isolates, the byte order mark, the line and paragraph separators, tag
|
|
30
|
+
characters) as `\uXXXX` (past U+FFFF, as the tag characters are, `\u{XXXXX}`), while LRM, RLM and ALM are written as
|
|
31
|
+
they are. Width by grapheme cluster, wide characters and emoji two columns, from a table generated from Unicode's
|
|
32
|
+
`EastAsianWidth.txt` 17.0.0 (its sha256 in the table); lines cut by columns, never inside a cluster, a space where a
|
|
33
|
+
line breaks staying at the end of the line before (UAX #14), so that no line but a paragraph's first begins with one,
|
|
34
|
+
nor, where UAX #14 gives no break before one, with a no-break space or a non-breaking hyphen (the figure space among
|
|
35
|
+
them, and after a Hebrew letter's hyphen-minus, what UAX #14's LB9 folds into the letter or the hyphen passed over,
|
|
36
|
+
LRM, RLM, ALM and ZWNJ among it: LB21a), but where moving the character before it would leave a line empty or the next
|
|
37
|
+
too wide, as in a run of them longer than the line; a message's space at a break hangs, and a message ends with its
|
|
38
|
+
last word. Right to left, one layout for every terminal (measured on Alacritty, Konsole, tmux and VS Code's terminal):
|
|
39
|
+
the reader lays out each line itself, by the Unicode Bidirectional Algorithm (UAX #9, written here from Unicode
|
|
40
|
+
17.0.0's data, generated and pinned as the width table is; a letter's marks kept after it, a mark after a soft hyphen,
|
|
41
|
+
ZWSP or WJ too; a path or a URL laid out as one left-to-right unit; a paragraph wrapped into lines, a record's text
|
|
42
|
+
line or a message, resolved once and each line reordered from its levels, whole, its spaces at either end too), and
|
|
43
|
+
writes a line that holds right-to-left text inside a left-to-right override (LRO after its first grapheme cluster that
|
|
44
|
+
takes a column, never at the line's first column; PDF at its end), so that a terminal that lays text out itself keeps
|
|
45
|
+
that order; `LTMS_READER_BIDI=terminal` writes the text as stored instead, with an RLM at the end of each
|
|
46
|
+
right-to-left paragraph.
|
|
47
|
+
- A transcript is read in the reader's own process; one over a tenth of Node's memory limit (its heap's, or the old
|
|
48
|
+
space's where `--max-old-space-size` or `--max-old-space-size-percentage` sets one) is refused with its size and the
|
|
49
|
+
`NODE_OPTIONS` that would let it be read, in the command `npx ltms-reader` with the path given (so too when it was
|
|
50
|
+
started as `ltms-reader`). A record is refused the same way when its view would not fit beside the transcript in
|
|
51
|
+
Node's memory, by its size and by the JSON its view would write (measured by walking the record, before any is
|
|
52
|
+
written: a record nested deep writes JSON hundreds of times its size), and its lines are laid out a page at a time.
|
|
53
|
+
The screen runs in a process of its own: when it ends without restoring the terminal (Node's memory ran out), the
|
|
54
|
+
command restores it, and exits with 128 and the signal's number; an error in the command's own process ends the screen
|
|
55
|
+
by its own way out first, and is printed after the restore (exit 1); when the command's own process is killed, the
|
|
56
|
+
screen's process learns of it, restores the terminal and ends.
|
|
57
|
+
- The view layer (`src/view.mjs`, `layout.mjs`, `engine.mjs`, `lines.mjs`, `helper.mjs`) moved here from the LTMS
|
|
58
|
+
Reader extension, with its tests; the extension takes it from this package. Since the move, a prompt whose channel is
|
|
59
|
+
an empty word reads `none`, as `ltms skeleton` prints it (the view layer gave an empty string; found by running the
|
|
60
|
+
views over the core's own test transcripts, `test/fixtures/review/pb-labels.jsonl`); and a turn of more line numbers
|
|
61
|
+
than a call takes arguments (about 31,000 tool calls in one turn, on Node 26) no longer stops its session's view with
|
|
62
|
+
a RangeError; and a text the view layer clips (a prompt, an input, a result, a reply) is cut where a grapheme cluster
|
|
63
|
+
begins, never between a letter and its marks, and its row ends with … when the clip cut its first line.
|
|
64
|
+
- Tests: 435 (Node 26.13.1: 435 passing; Node 24.22.3, 22.23.3 and 20.20.2 in docker: 428 passing, 0 failing,
|
|
65
|
+
7 skipped, as their images have no GNU FriBidi and no Electron).
|
|
66
|
+
|
|
67
|
+
### Known limits
|
|
68
|
+
|
|
69
|
+
Each was run on 2026-11-17 with a synthetic input, on this release's code before its last fix (of the refusals before
|
|
70
|
+
the screen opens, which touches none of them). Most need characters a transcript seldom holds, records nested hundreds
|
|
71
|
+
deep, or an old space set small (`--max-old-space-size`, in `NODE_OPTIONS` or on node's command line); the first does
|
|
72
|
+
not.
|
|
73
|
+
|
|
74
|
+
- A line whose first cluster that takes a column is right to left keeps that cluster outside the left-to-right
|
|
75
|
+
override, and a terminal that lays each line out with a left-to-right base would move that cluster to the line's
|
|
76
|
+
other end: the record row of the prompt `שלום עולם ומלואו` is written ו, LRO, the rest, PDF (read back from a
|
|
77
|
+
pseudo-terminal, Node 26.13.1, 80 x 24), and GNU FriBidi 1.0.18 with a left-to-right base (`fribidi --ltr`),
|
|
78
|
+
standing for such a terminal, puts the ו at the right end. Konsole itself was not run (the README's Right to left
|
|
79
|
+
says so too).
|
|
80
|
+
- A no-break space that does not fit after a hyphen of UAX #14's class HH (U+2010, U+2013, U+058A, U+05BE) or a
|
|
81
|
+
character of class BA that is not a space (U+0F0B, U+1361, U+2027) takes that character with it to the next line,
|
|
82
|
+
where UAX #14 (LB12a) breaks before the no-break space: 'ab', U+2013, U+00A0, 'x' at 3 columns is cut into 'ab' and
|
|
83
|
+
U+2013 U+00A0 'x', where ICU 78.3's line breaker (Unicode 17.0) breaks at 0, 3 and 5; so for each of the seven, in a
|
|
84
|
+
record's text and in a message (Node 26.13.1).
|
|
85
|
+
- After ZWSP or WJ before a no-break space, the line is cut before the ZWSP or WJ: 'אב-', U+200B, U+00A0, 'x' at 3
|
|
86
|
+
columns is cut into 'אב-' and U+200B U+00A0 'x', where ICU 78.3 breaks only after the ZWSP (0, 4, 6); with U+2060,
|
|
87
|
+
around which ICU gives no break (0, 6), the next line begins with the WJ and the no-break space; so too after a Latin
|
|
88
|
+
letter's hyphen and after a space (Node 26.13.1).
|
|
89
|
+
- After a space of class BA that hangs at a break (U+3000), what UAX #14's LB9 folds into that space (ALM, LRM, RLM)
|
|
90
|
+
begins the next line, before a no-break space: 'ab', U+3000, U+061C, U+00A0, 'x' at 3 columns is cut into 'ab' and
|
|
91
|
+
U+061C U+00A0 'x', where ICU 78.3 breaks after the U+061C (0, 4, 6); with ZWNJ, which joins the space's grapheme
|
|
92
|
+
cluster, the next line begins with the U+3000 itself (Node 26.13.1).
|
|
93
|
+
- Of UAX #14's class GL (41 code points in ICU 78.3) the reader keeps four with the character before them (U+00A0,
|
|
94
|
+
U+2007, U+202F, U+2011); the class's Tibetan marks that take a column (U+0F08, U+0F0C, U+0F12, U+0FD9, U+0FDA) begin a
|
|
95
|
+
line where UAX #14 gives no break: 'abc', U+0F08, 'def' at 3 columns is cut into 'abc', U+0F08 'de' and 'f', where
|
|
96
|
+
ICU 78.3 gives no break in it (Node 26.13.1).
|
|
97
|
+
- In a line whose first cluster that takes a column is a letter followed by WJ and a mark, which the reader keeps with
|
|
98
|
+
the letter, the LRO is written between the letter and the WJ: 'שלום', U+2060, U+05B7 in a cell is written U+05DD,
|
|
99
|
+
U+202D, U+2060, U+05B7, the rest, U+202C (Node 26.13.1). Whether a terminal then draws the mark on the letter's cell
|
|
100
|
+
was not measured.
|
|
101
|
+
- Under an old space set by `NODE_OPTIONS` or a flag, the Sessions list (`ltms index`, which the reader runs without
|
|
102
|
+
its `NODE_OPTIONS`) lists transcripts the reader then refuses: with `NODE_OPTIONS=--max-old-space-size=16` on Node
|
|
103
|
+
26.13.1, a project's transcript of 4,001,388 bytes was listed and, opened, refused ("it is 4 MB, and this process
|
|
104
|
+
reads a transcript of up to 1 MB"); on Node 24.22.3 under `--max-old-space-size=16` the list read one of 10,001,388
|
|
105
|
+
bytes, which `ltms index` under that flag does not survive.
|
|
106
|
+
- A transcript whose parse takes more than the 8 times its size the size rules allow for can be admitted and run Node's
|
|
107
|
+
memory out, and so can a record of it that the record rule shows: under `--max-old-space-size=64`, where the
|
|
108
|
+
transcript rule admits up to 6,710,886 bytes, a tool result of empty objects (3 bytes an object) of 1,000,000 objects
|
|
109
|
+
(3,001,951 bytes) ended the screen's process by SIGABRT as the transcript was read, and one of 700,000 (2,101,951
|
|
110
|
+
bytes) when its record was opened, on Node 26.13.1, 24.22.3 and 20.20.2 (400,000 objects: shown).
|
|
111
|
+
- A record of tabs that the record rule shows can run Node's memory out when it is opened: under
|
|
112
|
+
`--max-old-space-size=64`, a tool result of 1,100,000 tabs (a line of 2,200,433 bytes) ended the screen's process by
|
|
113
|
+
SIGABRT when its record was opened, on Node 26.13.1, 24.22.3 and 20.20.2 (600,000 tabs: shown); run as the command in
|
|
114
|
+
a pseudo-terminal on Node 26, it restored the terminal, said Node's heap ran out, named
|
|
115
|
+
`NODE_OPTIONS=--max-old-space-size=512`, and exited 134.
|
|
116
|
+
- The record rule is one rule for every Node line, writing a record's JSON taken to need 1.5 times its size (Node 20's
|
|
117
|
+
measure), so that on Node 22 to 26 a record nested deep is refused at old spaces where it would open: a list nested
|
|
118
|
+
200 deep of 1,000,000 ones (a file of 2,002,359 bytes, 613,124,378 bytes of JSON) is refused at `--max-old-space-size`
|
|
119
|
+
600 to 1004 (as tried) and shown at 1005, and with the size rules set aside it opened as JSON at 640 on Node 26.13.1
|
|
120
|
+
(at 600 Node's heap ran out).
|
|
121
|
+
- On Node 20 the old space a deep record's JSON view needs is not the same from run to run: with the size rules set
|
|
122
|
+
aside, a list nested 600 deep of 60,000 four-letter Hebrew strings (663,159 bytes, 220,943,956 bytes of JSON) opened
|
|
123
|
+
at `--max-old-space-size=240` once and ran out at 240 once, ran out at 242 (twice), 246 and 252, and opened at 300
|
|
124
|
+
(Node 20.20.2). The record rule refuses it at 240 to 360 and shows it at 400, where it opened on Node 20.
|
|
125
|
+
- ltms's own commands (`long-term-memory-structure` 0.3.1, the dependency) read a file of up to a tenth of Node's heap
|
|
126
|
+
limit, not of the old space set: `ltms index` under `--max-old-space-size=16` on Node 24.22.3 read a 4 MB transcript,
|
|
127
|
+
ended by SIGABRT on 10 and 18 MB ones ("Reached heap limit"), and skipped one of 22 MB. The reader's own lists, under
|
|
128
|
+
the same flag, read the 10 MB one.
|
|
129
|
+
- `src/helper.mjs`, the reading process the LTMS Reader extension takes from this package, reads a transcript of up to a
|
|
130
|
+
tenth of Node's heap limit, not of the old space set: under `--max-old-space-size=16` on Node 24.22.3 it gave its
|
|
131
|
+
limit as 21,810,380 bytes, and a transcript of 10,001,388 bytes ended it by SIGABRT ("Reached heap limit"), where the
|
|
132
|
+
reader refuses it. Not run under the extension's own runtime.
|
|
133
|
+
- The rest are in the README's Limits, each run again on this code: the transcript rule (a tenth of Node's memory limit:
|
|
134
|
+
under `--max-old-space-size=16` on Node 26.13.1, transcripts of 2 to 10 MB were refused that opened with the rule set
|
|
135
|
+
aside), the first frame of a long right-to-left paragraph (158 to 188 ms on Node 26.13.1 for one of 200,000 paths),
|
|
136
|
+
and the rows wider than a narrow screen (at 25 columns: the loading line, 38 columns, and the search line, 26).
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ohav Ben Yanai
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/LICENSE-UNICODE
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
Two files of this package are derived from the Unicode Character Database, version 17.0.0, whose files' headers say
|
|
2
|
+
"© 2025 Unicode®, Inc.":
|
|
3
|
+
- src/width-table.mjs from EastAsianWidth.txt (https://www.unicode.org/Public/17.0.0/ucd/EastAsianWidth.txt, sha256
|
|
4
|
+
ea7ce50f3444a050333448dffef1cadd9325af55cbb764b4a2280faf52170a33);
|
|
5
|
+
- src/bidi-table.mjs from DerivedBidiClass.txt, UnicodeData.txt, BidiBrackets.txt and BidiMirroring.txt
|
|
6
|
+
(https://www.unicode.org/Public/17.0.0/ucd/, each named with its sha256 at the head of the table).
|
|
7
|
+
They are used under this licence, the Unicode License v3 (https://www.unicode.org/license.txt):
|
|
8
|
+
|
|
9
|
+
UNICODE LICENSE V3
|
|
10
|
+
|
|
11
|
+
COPYRIGHT AND PERMISSION NOTICE
|
|
12
|
+
|
|
13
|
+
Copyright © 2025 Unicode, Inc.
|
|
14
|
+
|
|
15
|
+
NOTICE TO USER: Carefully read the following legal agreement. BY
|
|
16
|
+
DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
|
|
17
|
+
SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
|
|
18
|
+
TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
|
|
19
|
+
DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
|
|
20
|
+
|
|
21
|
+
Permission is hereby granted, free of charge, to any person obtaining a
|
|
22
|
+
copy of data files and any associated documentation (the "Data Files") or
|
|
23
|
+
software and any associated documentation (the "Software") to deal in the
|
|
24
|
+
Data Files or Software without restriction, including without limitation
|
|
25
|
+
the rights to use, copy, modify, merge, publish, distribute, and/or sell
|
|
26
|
+
copies of the Data Files or Software, and to permit persons to whom the
|
|
27
|
+
Data Files or Software are furnished to do so, provided that either (a)
|
|
28
|
+
this copyright and permission notice appear with all copies of the Data
|
|
29
|
+
Files or Software, or (b) this copyright and permission notice appear in
|
|
30
|
+
associated Documentation.
|
|
31
|
+
|
|
32
|
+
THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
|
|
33
|
+
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
34
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
|
|
35
|
+
THIRD PARTY RIGHTS.
|
|
36
|
+
|
|
37
|
+
IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
|
|
38
|
+
BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
|
|
39
|
+
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
|
|
40
|
+
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
|
|
41
|
+
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
|
|
42
|
+
FILES OR SOFTWARE.
|
|
43
|
+
|
|
44
|
+
Except as contained in this notice, the name of a copyright holder shall
|
|
45
|
+
not be used in advertising or otherwise to promote the sale, use or other
|
|
46
|
+
dealings in these Data Files or Software without prior written
|
|
47
|
+
authorization of the copyright holder.
|
|
48
|
+
|
|
49
|
+
SPDX-License-Identifier: Unicode-3.0
|
package/README.md
CHANGED
|
@@ -1,3 +1,285 @@
|
|
|
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 (the reader turns on
|
|
69
|
+
the terminal's bracketed paste): pasted into a line, its new lines become spaces and do not run it; elsewhere, nothing
|
|
70
|
+
pasted acts as a key. A Ctrl-C character in a paste is the one exception: it quits, in a line too.
|
|
71
|
+
|
|
72
|
+
## Your transcripts, and who sees them
|
|
73
|
+
|
|
74
|
+
- **It shows their text**, prompts, replies, tool inputs and outputs included, to you, on this terminal's alternate
|
|
75
|
+
screen. Nothing it shows is written to stdout, a pipe or a log, and nothing stays on the screen when it quits. (ltms
|
|
76
|
+
itself prints no text of a transcript but a call's tool name and a word taken from its input, `grep` or `README`
|
|
77
|
+
say; this reader is for the person whose transcripts they are.)
|
|
78
|
+
- **It writes no file and uses no network.** It reads the transcripts under the folder it is given, and runs ltms's
|
|
79
|
+
commands (`index`, `search`, `skeleton`) as local processes, which read the same files and write only to the reader.
|
|
80
|
+
Run through `npx`, npm writes files of its own: a log of each run under `~/.npm/_logs`, which names the folder or file
|
|
81
|
+
given (npm 12.2.2 writes a UUID in a path as `***`, a transcript's name among them), and a compile cache under
|
|
82
|
+
`$TMPDIR`; installed (`npm install -g ltms-reader`, then `ltms-reader`), it runs without npm, and without them.
|
|
83
|
+
- An error inside it, in the screen's process or in the command's own, is printed after the terminal is restored, by
|
|
84
|
+
its kind and where in this package it happened, not by its message, which could quote a transcript.
|
|
85
|
+
|
|
86
|
+
## Text on the screen
|
|
87
|
+
|
|
88
|
+
- **Control characters are shown, never sent.** A transcript can hold escape sequences (colours, cursor moves, a
|
|
89
|
+
window's title, OSC 52, which writes the clipboard). Every C0 and C1 control character and DEL is shown as a visible
|
|
90
|
+
escape: ESC as `␛`, the others as `\x07`, `\x9b` and so on; in a text, tabs become spaces and new lines become
|
|
91
|
+
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
|
|
92
|
+
JSON's escapes. Nothing a transcript holds can move the cursor, set the title, write the clipboard or leave the
|
|
93
|
+
terminal in another mode. A path, `CLAUDE_CONFIG_DIR` or an option it refuses before the screen opens is written the
|
|
94
|
+
same way.
|
|
95
|
+
- **So is what reorders or hides text:** the bidirectional embeddings, overrides and isolates (U+202A to U+202E, U+2066
|
|
96
|
+
to U+2069), the byte order mark (U+FEFF), the line and paragraph separators (U+2028, U+2029) and the tag characters
|
|
97
|
+
(U+E0000 to U+E007F), as `\u202e`, `\u{e0041}` and so on: an override in a transcript cannot reorder the rest of its
|
|
98
|
+
row. The light marks Hebrew and Arabic text use (U+200E, U+200F, U+061C) are written as they are.
|
|
99
|
+
- **Width by grapheme cluster** (`Intl.Segmenter`): combining marks, niqqud and cantillation take no column of their
|
|
100
|
+
own; East Asian wide characters and emoji take two. A line is cut by columns, never inside a cluster, and a space
|
|
101
|
+
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,
|
|
102
|
+
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
|
|
103
|
+
#14 gives no break before one but after a space or a hyphen, a hyphen-minus only where it does not follow a Hebrew
|
|
104
|
+
letter (LB21a; where that would leave the line before empty, or the next too wide, as on a line of one column, it
|
|
105
|
+
begins the line all the same). What UAX #14 takes as part of the character before it (LB9: its class CM, the marks
|
|
106
|
+
and LRM, RLM, ALM and ZWNJ among it, and ZWJ) is read so: between a Hebrew letter and its hyphen, after the hyphen,
|
|
107
|
+
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
|
|
108
|
+
break: a line begins with it where UAX #14 breaks before it, after a space, and, as with the others, where moving it
|
|
109
|
+
would leave a line empty or the next too wide. The wide characters come from a
|
|
110
|
+
table generated from Unicode's `EastAsianWidth.txt`, version 17.0.0 (`src/width-table.mjs`, which names the file's
|
|
111
|
+
sha256; `scripts/width-table.mjs` writes it). Characters of ambiguous width take one column.
|
|
112
|
+
- **Right to left** (Hebrew, Arabic): one layout for every terminal. The reader lays out each line itself (mode
|
|
113
|
+
`reader`, the default), by the Unicode Bidirectional Algorithm (UAX #9, Unicode 17.0.0, written in this package: the
|
|
114
|
+
implicit algorithm with paired brackets, its lines reordered and mirrored, a paragraph's direction from its first
|
|
115
|
+
strong character), and writes it in visual order. A line that holds right-to-left text (a character of UAX #9's class
|
|
116
|
+
R, AL or AN) is written inside a left-to-right override, U+202D (LRO) right after its first grapheme cluster that
|
|
117
|
+
takes a column (never at the line's first column: after ZWSP, a lone mark or an RLM that begins it, the next) and
|
|
118
|
+
U+202C (PDF) at its end, so that a terminal that lays bidirectional text out itself keeps the reader's order instead
|
|
119
|
+
of reordering it a second time; nothing else is written (no isolate), and a line without right-to-left text, or with
|
|
120
|
+
no cluster that takes a column, is written as it is. No terminal is detected.
|
|
121
|
+
- Measured on four terminals (S378): Alacritty 0.17.0, Konsole 26.08.3, tmux 3.6 and VS Code 1.146.0's terminal
|
|
122
|
+
(xterm.js 6.1.0-beta.304). There, after a line's first column, LRO and PDF take no column. Konsole lays text out
|
|
123
|
+
itself, with a left-to-right base for each line, and applies the override from a line's second column on; at the
|
|
124
|
+
first column an LRO is not applied by Konsole, dropped by tmux and given a column of its own by xterm.js (hence
|
|
125
|
+
after the first cluster), and xterm.js gives an isolate (LRI, RLI, PDI) a column anywhere. Alacritty and xterm.js
|
|
126
|
+
draw the text in the order it is written; tmux passes it on. No other terminal was measured (kitty, VTE's, as in
|
|
127
|
+
GNOME Terminal, mlterm, WezTerm, foot, iTerm2, Windows Terminal, GNU screen and the rest are not): one that gives
|
|
128
|
+
LRO or PDF a column shifts such a line by it. Not measured either: how Konsole joins Arabic letters that come to it
|
|
129
|
+
in visual order under the override; and a line whose first cluster that takes a column is itself right to left,
|
|
130
|
+
which the override leaves out (laid out by UAX #9 with a left-to-right base, as Konsole lays a line out, that
|
|
131
|
+
cluster would go to the line's other end). That is a known limit, left as it is.
|
|
132
|
+
- `LTMS_READER_BIDI=terminal` writes the text as stored instead (mode `terminal`), with a right-to-left mark (RLM) at
|
|
133
|
+
the end of each right-to-left paragraph, for a terminal that lays bidirectional text out itself (on Konsole the RLM
|
|
134
|
+
puts the paragraph's end punctuation where it belongs, though its brackets are not mirrored); `LTMS_READER_BIDI=reader`
|
|
135
|
+
is the default; a value it does not take is refused. Konsole is not detected: it gets the reader's layout, as
|
|
136
|
+
every terminal does, over ssh too, where `KONSOLE_VERSION` does not reach the reader.
|
|
137
|
+
|
|
138
|
+
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
|
|
139
|
+
a text wrapped into lines: a line of a record's text (its lines share its direction), a message, an error. A wrapped
|
|
140
|
+
paragraph's levels are resolved once, and each of its lines is reordered from them, as UAX #9 lays out a paragraph
|
|
141
|
+
broken into lines (its section 3.4): a line reads as its words do in the whole paragraph, the comma that ends a line
|
|
142
|
+
where the sentence has it. Each such line is laid out whole, its spaces at either end with the rest: a space that
|
|
143
|
+
ends a line takes the paragraph's direction (L1), so that in a right-to-left paragraph it is drawn at the line's
|
|
144
|
+
left. A record's text is cut into lines by columns: the whitespace where a line breaks stays at the end of the line
|
|
145
|
+
before, as UAX #14 has it, drawn there where the line has room for it, and past the screen's edge, not drawn, where
|
|
146
|
+
it does not. A message is broken at its spaces, and the space where a line breaks hangs, as UAX #14 has the
|
|
147
|
+
whitespace at a break: it is in no line, and is not drawn, though the line has room for it; whitespace that ends a
|
|
148
|
+
message after a break hangs too, and makes no line of its own. Either way no line but a paragraph's first begins with
|
|
149
|
+
whitespace that hangs (the figure space, a no-break space, does not hang). A long line of a list is cut in logical
|
|
150
|
+
order, its beginning kept, then laid out by itself, the spaces at its ends (a cell's padding) where they are.
|
|
151
|
+
A path or a URL in a line (`/home/...`, `~/...`, `src/...`, `https://...`) is laid out as one left-to-right unit, its
|
|
152
|
+
parts in order and a Hebrew name in it reading right (UAX #9's higher-level protocol HL4), in pieces where a line
|
|
153
|
+
breaks inside it, as an isolate is. Each cluster is kept whole, its marks after its letter, as a terminal draws them,
|
|
154
|
+
and so is a mark after characters UAX #9 removes (a soft hyphen, ZWSP, WJ: clusters of their own), with the letter
|
|
155
|
+
before them; the text is aligned left, so the columns stay. Checked against Unicode's conformance test
|
|
156
|
+
(BidiCharacterTest.txt: every case without an explicit formatting character, which the reader shows as an escape and
|
|
157
|
+
never applies) and against GNU FriBidi: its command for a line, its library for a paragraph wrapped into lines.
|
|
158
|
+
- Colour follows [NO_COLOR](https://no-color.org): set, there is none; the selected row is still drawn in reverse.
|
|
159
|
+
|
|
160
|
+
## Limits
|
|
161
|
+
|
|
162
|
+
- A transcript is read into memory whole, in the reader's own process. One over a tenth of Node's memory limit is
|
|
163
|
+
refused with its size and that limit (the size rounded up, the limit down, so that the two differ) and the
|
|
164
|
+
`NODE_OPTIONS=--max-old-space-size=...` that would let it be read (the rule ltms's commands follow, so the lists and
|
|
165
|
+
the reader agree on which files can be read while Node's memory limit is the same for both: the reader runs ltms's
|
|
166
|
+
commands without its own `NODE_OPTIONS` or flags); one over 480 MB cannot be read at all.
|
|
167
|
+
Node's memory limit is its heap's, or, where `--max-old-space-size` or `--max-old-space-size-percentage` sets the old
|
|
168
|
+
space (in `NODE_OPTIONS` or on node's command line), the old space's: a transcript's parse is kept there, and the
|
|
169
|
+
heap's limit holds beside it a reserve for new objects that is sized from the machine's memory, not from the old space
|
|
170
|
+
(with `--max-old-space-size=16`, measured: a heap limit of 64 MB on Node 20 and 22, 208 MB on Node 24, 112 MB on Node
|
|
171
|
+
26). By the heap's limit, under an old space of 16 MB, Node 24 read a transcript of 12 MB and ran out of memory.
|
|
172
|
+
- 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
|
|
173
|
+
file's) in nine tenths of Node's memory limit, and so does what writing the JSON the view writes of it takes, with
|
|
174
|
+
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
|
|
175
|
+
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
|
|
176
|
+
measured by walking the record, before any of it is written, and writing it is taken to need 1.5 times its size.
|
|
177
|
+
Both were measured against the old space, on Node 20, 22, 24 and 26: the reader alone needed 7 to 9 MB, and writing
|
|
178
|
+
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
|
|
179
|
+
not fit is refused before it is drawn, with its size and the `NODE_OPTIONS` that would show it. Its lines are laid out
|
|
180
|
+
a page at a time.
|
|
181
|
+
- The screen runs in a process of its own, which the command waits for. If that process ends without restoring the
|
|
182
|
+
terminal (Node's memory running out aborts it), the command restores it, then prints what Node said and what happened.
|
|
183
|
+
An error in the command's own process (a module loaded through `NODE_OPTIONS` or `--import` that throws, say) ends the
|
|
184
|
+
screen by its own way out (SIGTERM; if it has not ended within 2 s, SIGKILL, and the command restores the terminal),
|
|
185
|
+
then is printed after the restore, and the command exits with 1. If the command's own process is killed (SIGKILL),
|
|
186
|
+
the screen's process learns of it (an IPC channel between the two closes), restores the terminal and ends; if both
|
|
187
|
+
are killed at once (a whole cgroup, as systemd-oomd does), nothing is left to restore it.
|
|
188
|
+
- Under an interactive shell with job control, that shell takes the terminal back as soon as the command's process is
|
|
189
|
+
killed, racing the screen's process. The screen's process then writes the leave sequence and leaves the terminal's
|
|
190
|
+
modes to the shell (it puts back the modes it started with only where they are still the screen's raw ones, as
|
|
191
|
+
under a shell that sets none).
|
|
192
|
+
Measured on 2026-11-16 with round 3's check's probe, `shellkill.py`, and its stand-in for a job-control shell that
|
|
193
|
+
sets no modes, `standin.py`: a pseudo-terminal of 80 x 24, the shell at its prompt, the reader started from it,
|
|
194
|
+
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`
|
|
195
|
+
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
|
|
196
|
+
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,
|
|
197
|
+
for bash, both zsh and the stand-in. What stays: bash, both zsh and the stand-in wrote their prompt before the leave
|
|
198
|
+
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
|
|
199
|
+
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
|
|
200
|
+
line given to it brings a prompt back. And zsh without `ttyctl -f` took the modes the killed command left as its own
|
|
201
|
+
(10 of 10: its iflag and lflag not those at its prompt), so that the commands it ran next had the keyboard's signals
|
|
202
|
+
(Ctrl-C) and flow control off, `-isig -ixon`, 10 of 10; with `ttyctl -f` (in `.zshrc`) they had them on, 10 of 10.
|
|
203
|
+
- A list of sessions waits for `ltms index` to read every transcript of the project (on one machine, 39 s for a project
|
|
204
|
+
of 385 sessions), and a search for `ltms search`; the screen says what is being read and for how long. A list that
|
|
205
|
+
took 3 s or more is kept: opened again after its files changed, it is shown as it was read, and says when that was
|
|
206
|
+
and how many files changed since; `r` reads it again (as it reads Projects again), and so does `ltms-reader` started
|
|
207
|
+
again.
|
|
208
|
+
- Some clusters are drawn wider by some terminals than by the cluster rule (an Indic conjunct, an emoji sequence a
|
|
209
|
+
terminal does not join); a row then ends early, at the screen's edge.
|
|
210
|
+
- On a narrow screen some rows are wider than it (round 6's check measured them at 25 and 30 columns): the line that
|
|
211
|
+
says what is being read (`reading the sessions with ltms index`, a transcript's name, `searching with ltms search`),
|
|
212
|
+
which is not cut to the screen's width, and the search line where its prompt, which names what is searched, fills
|
|
213
|
+
the screen (the text typed and the cursor go past it). The reader turns wrapping at the last column off, so a
|
|
214
|
+
terminal stops such a row at its edge (reasoned, not measured). A known limit, left as it is.
|
|
215
|
+
- 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
|
|
216
|
+
characters or more. For R's record (one paragraph of 4,000,000 Hebrew characters), measured on 2026-11-16 on one
|
|
217
|
+
machine, its first frame took 150 to 239 ms on Node 26.13.1 (11 runs), where it took 12 to 23 ms before (11 runs);
|
|
218
|
+
the levels alone 137 to 147 ms (6 runs), and 143 to 145 on Node 20.20.2 (2 runs); the frames after it as before (a
|
|
219
|
+
page at 200 x 60: 9.4 to 14.4 ms in 7 runs, 10.4 to 14.2 before). A line finds the paths in it by a binary search of
|
|
220
|
+
its paragraph's: in a right-to-left paragraph of 200,000 paths (3,200,004 characters), measured on 2026-11-17 (2 runs
|
|
221
|
+
each), the first frame took 163 to 171 ms (21 to 22 when each line was laid out by itself), and a page at its start,
|
|
222
|
+
its middle and its end 5.8 to 6.4 ms at 200 x 60 (13.6 to 16.5 before), 1.1 to 1.7 at 80 x 24 (2.1 to 2.8 before).
|
|
223
|
+
- 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
|
|
224
|
+
grapheme segmenter is slower, and walked over one long string it costs more at each cluster the longer the string is
|
|
225
|
+
(3.4 us a cluster at 10,000 units, 115 at 80,000), so the reader walks a long line 256 units at a time. Measured on
|
|
226
|
+
R's record of 4,000,000 Hebrew characters at 80 columns: its lines counted in 6.7 s on Node 20.20.2, against 2.0 s on
|
|
227
|
+
Node 26.13.1 (an ASCII record of the same size: 57 and 61 ms).
|
|
228
|
+
|
|
229
|
+
Exit status: 0 after `q`; 130 after Ctrl-C or SIGINT; 129 after SIGHUP; 143 after SIGTERM; 1 after an internal error;
|
|
230
|
+
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`);
|
|
231
|
+
128 and a signal's number when a signal the screen cannot handle ended its process (134, SIGABRT, when Node's memory ran
|
|
232
|
+
out), the terminal restored all the same.
|
|
233
|
+
|
|
234
|
+
## Development
|
|
235
|
+
|
|
236
|
+
```sh
|
|
237
|
+
npm install
|
|
238
|
+
npm test
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
`npm test` runs `node --test test/*.test.mjs`, the pattern expanded by the shell, which runs the test files on Node 20,
|
|
242
|
+
22, 24 and 26 alike. Given the folder `test/` instead, Node 20 runs every module under it as a test, the fixtures too,
|
|
243
|
+
and Node 22 and 24 run none: they take the folder for a module, and fail. The whole suite was run on four Node lines on
|
|
244
|
+
2026-11-17, at this release's code, with no failure on any: Node 26.13.1, 435 tests, 435 passed (GNU FriBidi 1.0.18
|
|
245
|
+
there, its command and its library); Node 24.22.3, 22.23.3 and 20.20.2 in docker (the images node:24-slim, node:22-slim
|
|
246
|
+
and node:20-slim, as a user who is not root), 435 tests each, 428 passed and 7 skipped, as there is no GNU FriBidi and
|
|
247
|
+
no Electron in them. Each with the pinned Unicode files named (`LTMS_READER_UCD`, `LTMS_READER_EAW`). So it was under
|
|
248
|
+
`NODE_OPTIONS=--max-old-space-size=100` and `=500` too, once on each line: no test reads the environment's
|
|
249
|
+
`NODE_OPTIONS` where it means none, and the test of a turn of 33,000 calls reads it in a process of its own. On Node 20
|
|
250
|
+
under `=100`, `test/record-view.test.mjs` run alone ended by SIGABRT in 6 of 10 runs (Node's heap ran out in its test of
|
|
251
|
+
a record nested 990 deep, in the test's own process): the irregularity on Node 20 that the CHANGELOG's Known limits
|
|
252
|
+
name. The tests run the session, turn and record views (as text and as JSON) at 80 x 24 and 200 x 60 over ltms's own
|
|
253
|
+
synthetic transcripts (`test/fixtures/ltms`) and the reader's (`test/fixtures/hebrew-english.jsonl`, `escapes.jsonl` and
|
|
254
|
+
`channels.jsonl`, written by `node test/fixtures/make-fixtures.mjs`), Projects and Sessions at both sizes and Search at
|
|
255
|
+
80 x 24, compare what each row says with ltms's own commands, read every byte the reader writes for a transcript full of
|
|
256
|
+
escape sequences, and run it end to end in a pseudo-terminal (`script`, on Linux). `LTMS_READER_FIXTURES=<folder>` adds
|
|
257
|
+
every `.jsonl` under a folder to the views' test (the core's own `test/fixtures`, say). The width table's regeneration
|
|
258
|
+
is checked when `LTMS_READER_EAW` names the pinned `EastAsianWidth.txt`; the bidirectional table's regeneration, and
|
|
259
|
+
Unicode's conformance test of the algorithm (`test/bidi.test.mjs`, which reports how many cases passed and failed), when
|
|
260
|
+
`LTMS_READER_UCD` names a folder holding the pinned files (`scripts/bidi-table.mjs` names each with its sha256); GNU
|
|
261
|
+
FriBidi's layout of the right-to-left page and fixtures is compared with the reader's where `fribidi` is on the PATH (or
|
|
262
|
+
`LTMS_READER_FRIBIDI` names it); and each line of paragraphs wrapped into lines (the fixtures', and random ones) with
|
|
263
|
+
its library's, where `python3` can load `libfribidi` (`test/fribidi-lines.py`; `LTMS_READER_LIBFRIBIDI` names the
|
|
264
|
+
library, `LTMS_READER_PYTHON` the Python). GNU FriBidi 1.0.18 lays some paragraphs out otherwise than UAX #9 (brackets
|
|
265
|
+
next to a nonspacing mark): a line on which the reader and FriBidi's library differ is laid out by the tests' own
|
|
266
|
+
reference of UAX #9 too (`test/uba-reference.mjs`, checked on `BidiCharacterTest.txt`, every case, and on `BidiTest.txt`
|
|
267
|
+
when the folder holds it), and counts as FriBidi's difference, said and not failed, where FriBidi differs from the
|
|
268
|
+
reference and the reader does not:
|
|
269
|
+
|
|
270
|
+
```sh
|
|
271
|
+
curl -sS --fail -o EastAsianWidth.txt https://www.unicode.org/Public/17.0.0/ucd/EastAsianWidth.txt
|
|
272
|
+
mkdir ucd && for f in extracted/DerivedBidiClass.txt UnicodeData.txt BidiBrackets.txt BidiMirroring.txt BidiCharacterTest.txt BidiTest.txt; do
|
|
273
|
+
curl -sS --fail -o "ucd/${f##*/}" "https://www.unicode.org/Public/17.0.0/ucd/$f"; done
|
|
274
|
+
LTMS_READER_EAW=EastAsianWidth.txt LTMS_READER_UCD=ucd npm test
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
`src/view.mjs`, `src/layout.mjs`, `src/engine.mjs`, `src/lines.mjs` and `src/helper.mjs` are the view layer the LTMS
|
|
278
|
+
Reader extension for VS Code shares: it takes them from this package.
|
|
279
|
+
|
|
280
|
+
## License
|
|
281
|
+
|
|
282
|
+
MIT (`LICENSE`). `src/width-table.mjs` and `src/bidi-table.mjs` are derived from the Unicode Character Database, version
|
|
283
|
+
17.0.0 (`EastAsianWidth.txt`; `DerivedBidiClass.txt`, `UnicodeData.txt`, `BidiBrackets.txt` and `BidiMirroring.txt`;
|
|
284
|
+
© 2025 Unicode, Inc.), under the Unicode License v3: its copyright and permission notice is in `LICENSE-UNICODE`, which
|
|
285
|
+
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.0",
|
|
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
|
+
}
|