Commands: read-range & read-page
Relevant source files
The following files were used as context for generating this wiki page:
The read-range and read-page commands constitute the "progressive read" stage of the cxs retrieval pipeline. Following the initial discovery of session candidates via the find or list commands, these utilities allow users and agents to extract specific message content from indexed SQLite records without the overhead of parsing raw JSONL files.
Sources: AGENTS.md:12-14, README.md:10-12
Architectural Role and Logic
In the cxs architecture, retrieval follows a specific chain: message/session recall -> session heuristic rerank -> progressive read. Both commands are strictly read-only and operate against the SQLite index created during the sync process.
Sources: AGENTS.md:12-25, skill-packages/cxs/references/cli-surface.md:11-14
Progressive Retrieval Flow
The following diagram illustrates how these commands fit into the standard user workflow to minimize token consumption and cognitive load.
This flow ensures that users only read deep into session transcripts after narrowing down the search space via metadata and snippets.
Sources: skill-packages/cxs/references/progressive-workflow.md:3-9, README.md:10-12
read-range
The read-range command is designed for targeted context extraction. It retrieves a small "window" of messages centered around a specific anchor point within a session.
Anchor Mechanics
A sessionUuid is mandatory for this command. The anchor point must be defined using one of two mutually exclusive methods:
- Sequence Number (
--seq): Centered around a specific message index (often obtained from afindresult). - Sub-query (
--query): Relocates the anchor by performing a local search within the specified session.
Sources: src/cli.ts:107-133, skill-packages/cxs/references/cli-surface.md:73-82
Configuration Parameters
| Option | Type | Default | Description |
|---|---|---|---|
<sessionUuid> | Positional | N/A | The UUID of the session to read. |
--seq <n> | Integer | N/A | Message sequence number to use as the anchor. |
--query <text> | String | N/A | Query string to find the anchor within the session. |
--before <n> | Integer | 2 | Number of messages to retrieve before the anchor. |
--after <n> | Integer | 2 | Number of messages to retrieve after the anchor. |
Sources: src/cli.ts:110-117, skill-packages/cxs/references/cli-surface.md:78-82
Execution Logic and Sequence
read-page
The read-page command provides sequential pagination. It is primarily used when a search hit occurs at the "session-level" (e.g., matching a title or summary) rather than a specific message, or when a user needs to scroll through a long conversation linearly.
Sources: skill-packages/cxs/references/json-schema.md:27-29, README.md:118-121
Configuration Parameters
| Option | Type | Default | Description |
|---|---|---|---|
<sessionUuid> | Positional | N/A | The UUID of the session to read. |
--offset <n> | Integer | 0 | The starting index for the page. |
--limit <n> | Integer | 20 | The number of messages to return in the page. |
Sources: src/cli.ts:135-141, skill-packages/cxs/references/cli-surface.md:86-88
Output Characteristics
When executed with the --json flag, read-page provides metadata for handling large transcripts, including totalCount and a hasMore boolean to facilitate iterative reading.
Sources: src/cli.ts:145-152, skill-packages/cxs/references/json-schema.md:19-25
Data Models and Schemas
Both commands return structured data consisting of SessionRecord and MessageRecord objects.
Session and Message Structures
JSON Response Fields
| Component | Field | Description |
|---|---|---|
| Common | session | The SessionRecord metadata. |
| Common | messages | Array of MessageRecord objects. |
| read-range | anchorSeq | The resolved sequence number used as the center. |
| read-range | rangeStartSeq | The calculated start of the window. |
| read-page | totalCount | Total messages available in the session. |
| read-page | hasMore | Indicates if subsequent messages exist beyond the current limit. |
Sources: skill-packages/cxs/references/json-schema.md:15-25
Technical Constraints and Implementation Details
Error Handling
If the SQLite index has not been created via sync, both commands will fail with an index_unavailable error code.
Sources: src/cli.ts:246-265, skill-packages/cxs/references/failure-cookbook.md:38-48
Formatting Logic
The CLI uses budget-based trimming for text output to ensure readability in terminal environments. For example, transcript messages are trimmed to a budget of 1,000 characters by default.
Sources: src/format.ts:6-7, src/format.ts:153-162
Usage Guidelines for Agents
- Don't Cold-start: Never run
read-pagewithout a validsessionUuidfrom afindorlistresult. - Session Hits: If
matchSource = "session", thematchSeqwill benull. In this case, agents should useread-pagewithoffset=0rather than attempting aread-range. - Relocation: If the initial anchor from a global search is misaligned with the user's specific intent, use
read-range --queryto refine the window internally.
Sources: skill-packages/cxs/references/progressive-workflow.md:11-17, skill-packages/cxs/references/json-schema.md:27-29
Summary
The read-range and read-page commands enable high-precision retrieval within identified sessions. By supporting both anchor-based windows and sequential paging, they provide a flexible interface for both human developers and autonomous agents to audit historical Codex interactions efficiently.