Introduction & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
cxs is a local-first command-line interface (CLI) designed for progressive retrieval and indexed searching of Codex session logs. Unlike real-time sync daemons or GUI applications, cxs operates as a retrieval engine that allows users and agents to find specific historical discussions, configurations, or information stored within local .jsonl session files. Sources: README.md:3-10, AGENTS.md:5-13
The system architecture follows a "find-then-read" philosophy. It utilizes a SQLite backend for indexing and provides a structured workflow for ensuring data coverage before querying. This ensures that users do not need to load massive JSONL files into memory, instead pinpointing relevant message ranges or session pages through a tiered retrieval process. Sources: README.md:16-19, AGENTS.md:15-20
Core System Architecture
The cxs architecture is built around a progressive retrieval chain. This chain moves from broad session recall to heuristic reranking, and finally to detailed message projection.
The diagram illustrates the data flow from raw session logs to the final projected output via the SQLite index.
Sources: AGENTS.md:52-65, README.md:143-150
Key Components
| Component | Description | Relevant Files |
|---|---|---|
| CLI Surface | The primary entry point for users and agents, handling command routing and JSON output. | src/cli.ts, cli-surface.md |
| Indexer | Manages the sync process, updating the SQLite index based on defined selectors. | src/indexer.ts |
| Parser | Extracts metadata, messages, and summaries from Codex JSONL files. | src/parser.ts |
| Search Engine | Executes FTS (Full Text Search) queries with weighted relevance for session titles and summaries. | src/query/search.ts |
| Coverage Manager | Tracks which session subsets are indexed and fresh using selectors and fingerprints. | src/db/coverage.ts |
Sources: AGENTS.md:52-65, cli-surface.md:13-17
Installation & Setup
cxs requires Node.js (>= 22) and is compatible with macOS and Linux environments.
CLI Installation
The CLI is distributed as a scoped npm package.
npm i -g @act0r/cxs
cxs --help
Sources: README.md:32-46, package.json:37-39
Environment Configuration
cxs respects XDG specifications but allows overrides via environment variables.
| Variable | Description | Default |
|---|---|---|
CXS_BIN | Absolute path to the cxs binary for agent skill usage. | cxs (from PATH) |
CXS_DATA_DIR | Directory for storing the SQLite index and state. | ~/.local/state/cxs/ |
XDG_STATE_HOME | Standard state directory path. | ~/.local/state |
Sources: README.md:112-118, SKILL.md:20-25
Primary Workflow: The Progressive Search
The recommended operational sequence for cxs ensures data freshness and optimal retrieval performance. This is particularly critical for agents to avoid "index unavailable" errors. Sources: progressive-workflow.md:3-15, SKILL.md:43-55
The progressive workflow prioritizes verifying index coverage before executing searches.
Sources: README.md:16-19, progressive-workflow.md:5-10
1. Status and Coverage Check
Before searching, the status command provides an inventory of raw sessions and check if the desired range (defined by a selector) is indexed.
cxs status --selector '{"kind":"cwd","root":"/Users/me/sessions","cwd":"/Users/me/work/project"}' --json
Sources: cli-surface.md:22-30
2. Synchronization
If recommendedAction is "sync", the index must be updated. This is the only command that performs write operations to the SQLite database.
cxs sync --selector '{"kind":"all","root":"/Users/me/sessions"}'
Sources: README.md:120-125, cli-surface.md:51-58
3. Searching and Reading
Queries are executed against the index. Searches utilize Full-Text Search (FTS) with specific field weighting:
- Title: 8.0
- Compact Text: 4.0
- Summary: 3.0
- Reasoning Summary: 1.2
Sources: AGENTS.md:24-26, README.md:152-155
This sequence shows how the CLI coordinates between the indexed database and the raw filesystem for detailed reading.
Sources: README.md:143-150, progressive-workflow.md:21-35
Selectors
Selectors are JSON objects used to constrain the scope of sync, find, and list commands.
| Selector Kind | Purpose | Required Fields |
|---|---|---|
all | Indexes everything under a root. | root |
cwd | Constrains to a specific working directory. | root, cwd |
date_range | Constrains to a specific timeframe. | root, fromDate, toDate |
cwd_date_range | Intersection of directory and time. | root, cwd, fromDate, toDate |
Sources: README.md:95-105, cli-surface.md:42-49
Summary & Significance
cxs serves as a critical bridge between unstructured Codex session logs and AI agents that require historical context. By implementing a progressive retrieval model, it minimizes resource consumption while maximizing the accuracy of session recall. Its reliance on explicit selectors and a strictly read-only query interface (save for the sync command) makes it a stable foundation for building complex agentic workflows and local development tools. Sources: AGENTS.md:5-20, SKILL.md:43-45