Codebase Structure & Navigation

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• skill-packages/cxs/SKILL.md
• skill-packages/cxs/references/cli-surface.md
• skill-packages/cxs/references/progressive-workflow.md
• skill-packages/cxs/references/json-schema.md
• src/parser.ts
• src/format.ts

The cxs project is a local-first command-line interface (CLI) and retrieval engine designed for indexing and searching native Codex session logs. It follows a progressive retrieval philosophy: identifying relevant sessions first, then reading specific ranges or pages to minimize overhead. The system is built as a stateless CLI that interacts with a SQLite database for indexing, rather than operating as a daemon or real-time synchronization service.

The architecture is centered around a "Mainline" intent memory layer for AI-assisted engineering and a strict command surface that separates read-only queries from the index-modifying sync command. Navigation through the codebase is organized by functional responsibilities, including CLI orchestration, parsing, database management, and ranking heuristics.

Sources: README.md:3-12, AGENTS.md:5-15, AGENTS.md:144-150

Core Architectural Components

The system is partitioned into several distinct modules that handle the lifecycle of a retrieval request, from initial status checking to final content rendering.

System Overview Diagram

The following diagram illustrates the high-level flow from raw Codex JSONL files to the user-facing CLI results.

Functional Module Map

Module	File Path	Responsibility
CLI Surface	src/cli.ts	Entry point for all subcommands and option parsing.
Sync/Index	src/indexer.ts	Orchestrates the synchronization of local files to SQLite.
Parser	src/parser.ts	Parses JSONL sessions and generates summaries/metadata.
DB Facade	src/db.ts	SQLite abstraction and schema management (in src/db/).
Query Engine	src/query.ts	Facade for search, list, and read operations (in src/query/).
Selector Logic	src/selector.ts	Logic for parsing and validating coverage selectors.
Ranking	src/ranking.ts	Heuristic reranking of session candidates.
Formatting	src/format.ts	Console output orchestration and text budgeting.

Sources: AGENTS.md:34-46

Data Flow & Retrieval Chain

The primary retrieval chain follows a structured sequence: message/session recall -> session heuristic rerank -> progressive read. This ensures that data is retrieved efficiently without dumping entire session transcripts prematurely.

Retrieval Sequence Diagram

This diagram shows the interaction between components during a typical search and read workflow.

Indexing and Parsing Logic

The parser.ts module extracts specific signals from Codex JSONL logs to populate the Full-Text Search (FTS) indexes. It identifies user and assistant messages, reasoning summaries, and "compacted" handoff messages.

• FTS Recall: Candidates are recalled from messages_fts and sessions_fts.
• Fields: Session-level search includes title, summary_text, compact_text, and reasoning_summary_text.
• Weights: Title (8.0), Compact (4.0), Summary (3.0), Reasoning Summary (1.2).

Sources: AGENTS.md:26-33, src/parser.ts:40-100

Command Implementation & Protocols

The project enforces a strict protocol for command usage, where only sync is permitted to modify the index.

CLI Command Summary

Command	Write Access	Key Parameters	Data Source
status	Read-only	--selector	Raw metadata + DB
sync	Read/Write	--selector, --best-effort	Raw JSONL -> DB
find	Read-only	<query>, --sort, --exclude-session	DB FTS
list	Read-only	--selector, --sort	DB Metadata
read-range	Read-only	<uuid>, --seq OR --query	DB Messages
read-page	Read-only	<uuid>, --offset, --limit	DB Messages

Sources: README.md:46-55, references/cli-surface.md:3-15, AGENTS.md:16-18

Selector and Coverage System

Selectors define the scope of data for both syncing and querying. The system recognizes several kinds of selectors:

• all: The entire session root.
• date_range: Sessions within specific dates.
• cwd: Sessions belonging to a specific working directory.
• cwd_date_range: A combination of directory and date constraints.

Sources: README.md:61-75, references/json-schema.md:139-145

Directory Structure

.
├── src/                # Implementation source code
│   ├── db/             # SQLite stores and schema migrations
│   ├── query/          # Find, read, and list implementations
│   ├── cli.ts          # CLI entry point
│   ├── indexer.ts      # Sync logic
│   ├── parser.ts       # Codex JSONL parser
│   └── types.ts        # Core TypeScript contracts
├── skill-packages/     # Distributable agent skills
│   └── cxs/            # Main skill package for agents
├── eval/               # Evaluation runners and schemas
├── docs/               # Documentation and roadmaps
└── data/               # (Ignored) local SQLite DBs and test data

Sources: AGENTS.md:34-46, README.md:134-145

Conclusion

The cxs codebase is structured to facilitate high-performance, progressive retrieval of local interaction history. By separating raw file metadata scanning (Source Inventory) from the actual indexed search (SQLite FTS), it allows agents and users to maintain an accurate view of their session history with minimal overhead. The clear boundary between read-only query commands and the authoritative sync command ensures index integrity and predictable CLI behavior.

Sources: AGENTS.md:5-15, README.md:105-115