Command: find
Relevant source files
The following files were used as context for generating this wiki page:
The find command is the primary search interface for the cxs project, designed to perform full-text searches across local Codex session logs. Its primary purpose is to identify relevant sessions and specific message anchors within those sessions based on a user-provided query. It sits in the middle of the progressive retrieval workflow: status -> ensure selector coverage -> find/list -> read-range/read-page.
Sources: README.md:6 AGENTS.md:12
Core Functionality and Architecture
The find command utilizes SQLite's Full-Text Search (FTS) capabilities to query indexed data. It targets two main recall surfaces: messages_fts for individual user and assistant messages, and sessions_fts for session-level metadata including titles, summaries, and reasoning text. Results are ranked based on a heuristic reranking process that accounts for relevance or temporal data depending on user configuration.
Sources: AGENTS.md:32-35, README.md:104-108
Retrieval Pipeline
The search logic follows a multi-stage process to ensure accurate results:
- Recall: Candidates are pulled from
messages_ftsandsessions_fts. A LIKE-based fallback is used for rare zero-token CJK (Chinese, Japanese, Korean) queries. - Reranking: Sessions are reranked using heuristic scoring. Title matches are weighted significantly higher (8.0) than other fields like summary (3.0) or reasoning (1.2).
- Projection: The command returns a list of
FindResultobjects, providing enough context (snippets and metadata) for the user to decide on the next progressive read step.
Sources: AGENTS.md:32-37, README.md:104-111
The following diagram illustrates the data flow for the find command:
Sources: AGENTS.md:32-37, src/cli.ts
Command Options and Usage
The find command supports several options to refine search results, including sorting, result limiting, and session exclusion.
Parameters and Options
| Option | Type | Default | Description |
|---|---|---|---|
query | string | N/A | The search term or phrase. |
--selector | JSON | N/A | Constraints the search to specific CWDs, dates, or roots. |
--sort | enum | relevance | Sort order: relevance, ended, or started. |
--exclude-session | string | N/A | UUID of a session to ignore (useful for excluding the current session). |
--limit, -n | number | N/A | The maximum number of results to return. |
--json | flag | false | Outputs the result in structured JSON format. |
Sources: skill-packages/cxs/references/cli-surface.md:46-56, README.md:88-92
Query Semantics
Input queries are processed by a tokenizer before being passed to SQLite. Every term is wrapped in double quotes and terms are joined by AND operators. For CJK content, the system uses a bigram-based strategy, requiring at least two characters for stable FTS matching.
Sources: skill-packages/cxs/references/advanced-queries.md:3-23
Data Models
When the --json flag is used, the command returns a structured response containing search results and coverage status.
FindResult Schema
The FindResult object provides the identity and context of a hit:
| Field | Type | Description |
|---|---|---|
sessionUuid | string | Unique identifier for the session. |
title | string | The title of the session. |
matchSource | string | Indicates if the hit was a message or a session level match. |
matchSeq | number | null | The sequence number of the matching message (null for session-level hits). |
snippet | string | A text fragment highlighting the match (wrapped in <mark> tags). |
score | number | The calculated relevance score. |
Sources: skill-packages/cxs/references/json-schema.md:14-30
Interaction Flow
The find command is intended to provide "anchors" for further reading. If a match is found at the message level, the system suggests using read-range with the specific matchSeq. If it is a session-level match, it suggests read-page.
Usage Requirements and Constraints
The find command is a read-only operation. It relies entirely on the existing SQLite index. If the index has not been created or the requested range is not covered, the command will fail or return incomplete results.
- Index Dependency: If the index is missing, the command returns an
index_unavailableerror. - Sync Prerequisite: Users are encouraged to run
status --selectorto check coverage before querying. IfrecommendedActionissync, the index must be updated first. - Result Exclusion: The
--exclude-sessionflag is specifically recommended to avoid "self-hits" from the currently active session.
Sources: AGENTS.md:14-25, skill-packages/cxs/references/cli-surface.md:40-44, README.md:88-92
Summary
The find command provides high-performance, indexed search for local session history. By combining message-level FTS and heuristic-weighted metadata search, it allows users to quickly locate historical context. Its tight integration with selectors ensures that searches can be precisely scoped to specific projects or timeframes, serving as the critical discovery phase in the cxs progressive retrieval workflow.