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 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.
@@ -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
- # Temporary Holding Version
1
+ # ltms-reader
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
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
+ }