JSON Output Schema Reference
Relevant source files
The following files were used as context for generating this wiki page:
This page provides a comprehensive reference for the JSON output schemas used by the cxs CLI. cxs is designed as a local-first retrieval engine for Codex session logs, and its JSON output serves as the primary integration interface for agents and sidecar applications. Every command that reads indexed content supports the --json flag to provide structured data instead of human-readable text.
The schemas ensure consistency across various operations including session discovery (find, list), content retrieval (read-range, read-page), and system introspection (status, stats). All JSON responses are derived from the SQLite index or the raw session metadata inventory.
Sources: README.md:1-20, src/cli.ts:35-250, src/types.ts:1-10
Core Data Models
The following shared records form the building blocks of most command responses.
Session and Message Records
A SessionRecord represents a single indexed Codex session, while a MessageRecord represents an individual interaction within that session.
The diagram shows the relationship between a session and its constituent messages.
Sources: src/types.ts:107-133, skill-packages/cxs/references/json-schema.md:112-140
Selectors
Selectors are used to define the scope of operations such as synchronization or filtered searching.
| Selector Kind | Fields | Description |
|---|---|---|
all | root | Covers all sessions under the specified root directory. |
date_range | root, fromDate, toDate | Filters sessions by their date within a specific range. |
cwd | root, cwd | Filters sessions belonging to a specific working directory. |
cwd_date_range | root, cwd, fromDate, toDate | Combines working directory and date range filters. |
Sources: src/types.ts:32-37, skill-packages/cxs/references/json-schema.md:142-148
Command Responses
Find Results
The find command returns ranked session candidates based on relevance or time.
The flow illustrates how matchSource determines the availability of a sequence anchor (matchSeq) for subsequent read-range calls.
Schema Details:
- matchSource: If set to
"session", the hit originated from metadata (title, summary, etc.) rather than a specific message. - snippet: Contains the matching text context, often with
<mark>tags.
Sources: src/types.ts:148-164, skill-packages/cxs/references/json-schema.md:4-37
Content Retrieval (Read Range & Page)
Content retrieval is handled by two distinct modes: localized window reading and sequential paging.
- read-range: Focused on a specific anchor sequence or query match.
- read-page: Handles pagination with
offset,limit,totalCount, and ahasMoreboolean.
Sources: src/types.ts:184-211, skill-packages/cxs/references/json-schema.md:39-55
Status and Coverage
The status command provides a snapshot of the environment and index freshness.
The requestedCoverage object is critical for determining if an index update is required before querying.
Sources: src/types.ts:241-260, skill-packages/cxs/references/json-schema.md:73-90
Error Handling
When using the --json flag, errors are returned as structured objects rather than plain text on stderr.
| Error Code | Occurs When | Response Shape |
|---|---|---|
index_unavailable | Attempting to read before running sync. | { "error": { "code": "index_unavailable", "message": string, "dbPath": string, "hint": string } } |
selector_required | Running sync without the mandatory --selector flag. | { "error": { "code": "selector_required", "message": string } } |
invalid_selector | The provided selector JSON is malformed or invalid. | { "error": { "code": "invalid_selector", "message": string } } |
Sources: src/cli.ts:208-239, skill-packages/cxs/references/failure-cookbook.md:88-106
Sync Summary
The sync command returns a detailed summary of the synchronization process, including any file-level errors encountered.
// Sources: [src/types.ts:166-176]
export interface SyncSummary {
scanned: number;
added: number;
updated: number;
skipped: number;
filtered: number;
removed: number;
errors: number;
errorDetails: SyncErrorDetail[];
selector: Selector;
coverage: CoverageWriteSummary;
}
Conclusion
The JSON output schema of cxs provides a robust contract for programmatic interaction. By leveraging structured Selectors and detailed Coverage statuses, external tools can reliably determine when to synchronize and how to interpret search results. The distinction between message and session match sources specifically guides agents toward the correct retrieval strategy (read-range vs read-page).
Sources: AGENTS.md:10-30, skill-packages/cxs/references/cli-surface.md:1-20