Performance Optimizations
Relevant source files
The following files were used as context for generating this wiki page:
Performance optimizations in the cxs project are centered around three primary objectives: minimizing I/O overhead during session synchronization, providing near-instantaneous search results across local SQLite databases, and implementing a "progressive" retrieval workflow that prevents unnecessary data processing. Because cxs is a local-first CLI tool for searching Codex session logs, optimizations focus heavily on balancing background indexing efficiency with foreground responsiveness.
The architecture emphasizes a Progressive Workflow where users (or agents) first establish coverage, find specific session candidates, and only then read specific ranges or pages. This avoids the high cost of "cold-starting" or dumping full JSONL transcripts.
Indexing Efficiency
The synchronization process (sync) is the only write-intensive operation in the system. To handle potentially thousands of Codex session files, cxs employs several implementation-level optimizations within the indexer.
Concurrency and Batching
To avoid I/O bottlenecks during file parsing, the indexer utilizes a worker loop pattern with a bounded concurrency limit.
- Concurrency Limit: The system defaults to a
CONCURRENCY_LIMITof 16 concurrent workers. This preventsEMFILE(too many open files) errors while maximizing CPU usage during JSONL parsing. - Batch Pre-fetching: Before processing files, the indexer fetches all indexed session metadata in a single batch query rather than performing N+1 queries during the loop.
Sources: src/indexer.ts:133-140, src/indexer.ts:145-147
Change Detection
cxs implements incremental updates by comparing filesystem metadata against the existing index. A session file is only re-parsed if:
- The file modification time (
mtimeMs) has changed. - The file size has changed.
- The system's internal
INDEX_VERSIONhas been bumped.
Sources: src/indexer.ts:155-161, src/indexer.ts:175-181
Indexing Flow Diagram
The following diagram illustrates the optimized synchronization pipeline:
The use of a single SQLite transaction for all operations ensures atomic updates and significantly improves write performance compared to individual row inserts. Sources: src/indexer.ts:145-173, src/indexer.ts:209-234
Query and Search Optimization
Search performance is optimized through a combination of SQLite Full-Text Search (FTS) strategies, weighted scoring, and localized fallback mechanisms.
Multi-Surface Recall
Search queries utilize both messages_fts (content-level) and sessions_fts (summary-level). To ensure high-quality relevance without expensive re-ranking, the project uses explicit field weighting for session-level recall:
| Field | Weight |
|---|---|
| Title | 8.0 |
| Compact Text | 4.0 |
| Summary Text | 3.0 |
| Reasoning Summary | 1.2 |
Sources: AGENTS.md:23-28
Tokenizer and CJK Strategy
For Chinese, Japanese, and Korean (CJK) text, cxs implements a bigram strategy. Continuous CJK strings are split into overlapping two-character tokens. If a CJK query results in zero FTS tokens (e.g., single character), the system falls back to a bounded LIKE scan to ensure recall at the cost of slight performance degradation only in edge cases.
Sources: skill-packages/cxs/references/advanced-queries.md:16-24
Progressive Retrieval Strategy
A key architectural performance optimization is the enforcement of a progressive retrieval lifecycle. This minimizes the memory and I/O footprint of the CLI by ensuring only necessary data is fetched at each stage.
This flow prevents the system from reading large JSONL files directly until a specific session and message range have been identified. Sources: skill-packages/cxs/SKILL.md:65-72, README.md:12-16
UI and Formatting Constraints
To maintain responsiveness in the CLI output and prevent buffer overflows or slow rendering of large sessions, cxs enforces strict character budgets on formatted output.
| Component | Character Budget | Purpose |
|---|---|---|
SUMMARY_TEXT_BUDGET | 220 characters | Trims session summaries in list and find views. |
TRANSCRIPT_TEXT_BUDGET | 1,000 characters | Caps individual message size in read-range and read-page. |
Sources: src/format.ts:14-15, src/format.ts:182-195
Performance Monitoring
The project includes a benchmarking utility (eval/perf-bench.ts) to track latency regressions across different query types (e.g., single token, multi-token, CJK).
- Warmup Runs: The tool performs 5 runs per query, discarding the first run as a "warmup" to account for OS file caching and JIT compilation.
- Metrics: It calculates p50 and p95 latency to identify worst-case performance in the FTS engine.
Sources: eval/perf-bench.ts:46-55, eval/perf-bench.ts:121-137
Synchronization performance is also measured by tracking the total milliseconds spent per batch and the resulting database size in bytes. Sources: eval/perf-bench.ts:142-154
cxs achieves high performance by treating local search as a data-sparse problem: it indexes aggressively using parallel workers and delta detection, but retrieves conservatively using a progressive workflow. By offloading complex tokenization and weighting to SQLite and enforcing output budgets, the tool maintains a lightweight footprint even as the local Codex session repository grows.