Query Scope Selectors

Relevant source files

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

• src/types.ts
• README.md
• skill-packages/cxs/references/cli-surface.md
• skill-packages/cxs/references/json-schema.md
• src/cli.ts
• src/status.test.ts
• AGENTS.md

Query Scope Selectors are structured JSON objects used in the cxs project to define and constrain the range of Codex session logs for indexing and searching. They serve as the primary mechanism for managing "coverage," allowing the system to determine which local files have been processed into the SQLite index and whether that index is fresh or stale relative to the source files. Sources: README.md:92-94, AGENTS.md:15-18

These selectors are mandatory for synchronization operations and optional for query commands like find and list. By defining a specific scope—such as a specific working directory or a date range—selectors prevent unnecessary full-index scans and enable progressive retrieval workflows. Sources: README.md:100-101, skill-packages/cxs/references/cli-surface.md:52-54

Selector Architecture and Types

The system categorizes selectors into four distinct "kinds," each targeting different metadata found in the Codex session logs. Every selector must include a root path, which points to the base directory where Codex sessions are stored (typically ~/.codex/sessions). Sources: skill-packages/cxs/references/json-schema.md:156-161

Selector Definitions

Kind	Description	Required Fields
all	Targets all sessions under the specified root.	kind, root
date_range	Targets sessions within a specific ISO date window.	kind, root, fromDate, toDate
cwd	Targets sessions associated with a specific absolute directory path.	kind, root, cwd
cwd_date_range	A hybrid targeting a specific directory within a date window.	kind, root, cwd, fromDate, toDate

Sources: skill-packages/cxs/references/json-schema.md:156-161, README.md:104-107

Data Structure Implementation

The selector is defined as a union type in the system's core types, ensuring strict validation during JSON parsing. Sources: src/types.ts

type Selector =
  | { kind: "all"; root: string }
  | { kind: "date_range"; root: string; fromDate: string; toDate: string }
  | { kind: "cwd"; root: string; cwd: string }
  | { kind: "cwd_date_range"; root: string; cwd: string; fromDate: string; toDate: string };

Sources: skill-packages/cxs/references/json-schema.md:156-161

Coverage and Provenance Logic

Selectors are not just filters; they are the basis for "provenance" (the history of where data came from). When a sync operation is performed with a selector, the system records a CoverageRecord in the database. This record includes a sourceFingerprint (a hash of the files in that scope) and a sourceFileCount. Sources: skill-packages/cxs/references/json-schema.md:180-188, README.md:143-145

Coverage Flow

The following diagram illustrates how the system uses selectors to determine if a query can proceed or if a sync is required.

The system utilizes "coverage implication" rules: a fresh all selector record automatically covers any narrower cwd or date_range selector under the same root. Sources: AGENTS.md:19-21, src/status.test.ts:98-100

Freshness States

• Fresh: The local files matching the selector match the sourceFingerprint in the index.
• Stale: The local files have changed, but a record exists.
• Missing: No record exists for this scope.
  Sources: skill-packages/cxs/references/json-schema.md:173-178, src/status.test.ts:77-79

CLI Usage and Integration

Selectors are passed to the CLI as stringified JSON via the --selector flag. This is handled by the parseSelectorJson utility and the requireSelector or optionalSelector functions in the CLI entry point. Sources: src/cli.ts:251-266

Synchronization (Required)

The sync command requires an explicit selector to define the write boundary. A "strict sync" will remove indexed sessions that no longer exist within the selected scope before committing the new coverage record. Sources: README.md:133-138, src/cli.ts:60-63

Querying (Optional)

When used with find or list, the selector acts as a filter. If a selector is provided but coverage is missing or stale, the CLI returns a RequestedCoverageStatus indicating that a sync is recommended. Sources: skill-packages/cxs/references/cli-surface.md:16-19, skill-packages/cxs/references/json-schema.md:170-178

# Example: Syncing a specific project
cxs sync --selector '{"kind":"cwd","root":"/Users/me/.codex/sessions","cwd":"/Users/me/work/project-a"}'

# Example: Finding within a specific date range
cxs find "bug fix" --selector '{"kind":"date_range","root":"/Users/me/.codex/sessions","fromDate":"2026-04-01","toDate":"2026-04-10"}'

Sources: README.md:113-115, skill-packages/cxs/references/cli-surface.md:52-54

Summary of Logic Rules

Selectors govern the lifecycle of data within the cxs index through the following set of constraints:

1. No Implicit Sync: Read commands like find or list never trigger a sync automatically. They only report status. Sources: AGENTS.md:18-19
2. Best Effort vs. Strict: A standard sync only writes a coverage record if all files in the selector scope parse successfully. The --best-effort flag allows partial indexing but prevents the writing of a "complete" coverage record. Sources: README.md:139-141, skill-packages/cxs/references/cli-surface.md:91-92
3. Provenance Migration: Indexes created in versions prior to v6-selector-provenance must be re-synced to populate the path_date and source_root fields used by modern selectors. Sources: README.md:148-151

Query Scope Selectors ensure that the cxs retrieval engine remains efficient and accurate by strictly tying indexed data to its physical source files on the local machine. By requiring explicit scopes, the system provides developers and agents with a predictable environment for session recall. Sources: README.md:12-15, AGENTS.md:7-10