Commands: list & stats
Relevant source files
The following files were used as context for generating this wiki page:
The list and stats commands in the cxs project serve as the primary tools for metadata inspection and index diagnostics. While find focuses on full-text search (FTS) across session content, list provides a way to browse and filter indexed sessions based on structural metadata like Current Working Directory (CWD) and timeframes. stats offers a high-level overview of the index's health, volume, and storage characteristics.
Both commands are strictly read-only and require an existing SQLite index to function. If the index has not been created via the sync command, these operations will return an index_unavailable error.
Sources: README.md:61-68, skill-packages/cxs/references/cli-surface.md:14-18, AGENTS.md:13
The list Command
The list command allows users to retrieve a collection of indexed sessions without performing full-text content matching. It is particularly effective when the user has specific metadata constraints, such as a known project path or a specific date range, but lacks a precise keyword for searching.
Workflow and Usage
The command follows the "metadata-first" retrieval philosophy. It is often used after a status check to verify coverage and before a read-range or read-page operation to inspect a specific session.
This diagram shows the logical flow of the list command from the initial request to the final output. Sources: skill-packages/cxs/references/cli-surface.md:14-18, skill-packages/cxs/references/progressive-workflow.md:3-9
Parameters and Options
| Option | Type | Description |
|---|---|---|
--selector | JSON String | A structured filter defining the scope (e.g., cwd, date_range). |
--sort | Enum | Determines ordering: ended (default for recent), started, or messages. |
--cwd | String | A substring filter for the Current Working Directory. |
--since | Date | Filters sessions occurring after the specified date. |
-n, --limit | Number | Maximum number of sessions to return. |
--json | Flag | Outputs structured data instead of human-readable text. |
Sources: README.md:111-114, skill-packages/cxs/references/cli-surface.md:126-132, skill-packages/cxs/references/advanced-queries.md:29
Implementation Details
The command returns a list of SessionListEntry objects. Each entry includes core identifying information and a summaryText derived from the session content.
{
"query": {
"cwd": "string",
"sort": "ended | started | messages",
"limit": "number"
},
"results": [
{
"sessionUuid": "uuid-string",
"title": "Session Title",
"summaryText": "Brief summary...",
"cwd": "/path/to/project",
"messageCount": 42,
"endedAt": "2026-04-30T..."
}
]
}
Sources: skill-packages/cxs/references/json-schema.md:52-63, src/format.ts:88-100
The stats Command
The stats command provides diagnostic information regarding the local SQLite database used for indexing Codex sessions. It is primarily used to monitor database size, session volume, and synchronization history.
Diagnostic Metrics
The output of stats includes:
- Volume Metrics: Total number of sessions and messages stored.
- Temporal Coverage: The timestamps for the earliest and latest sessions in the index.
- Storage Metadata: The absolute path to the SQLite database and its size in bytes.
- Health Information: The last successful synchronization time and the current index schema version.
- Distribution: A breakdown of the "Top CWDs" showing which projects have the most session history.
Sources: skill-packages/cxs/references/json-schema.md:65-76, src/format.ts:102-118
Sequence of Data Retrieval
The sequence diagram illustrates how stats aggregates multiple metrics from the SQLite database before presenting them to the user. Sources: src/format.ts:102-118, src/cli.test.ts:401-417
Output Formatting
When using text output (non-JSON), the project uses chalk to provide a clear, color-coded summary of the index state, including a padded table for top CWDs.
// Example from src/format.ts
export function printStats(stats: StatsSummary): void {
console.log(chalk.bold.cyan(`cxs stats`));
console.log(`sessions: ${stats.sessionCount}`);
console.log(`messages: ${stats.messageCount}`);
console.log(`db_path: ${stats.dbPath}`);
// ... top CWDs formatting with padding
}
Sources: src/format.ts:102-118
Integration with the Progressive Workflow
Both commands are part of the "status -> ensure coverage -> find/list -> read" chain. While find is the primary entry point for content discovery, list and stats are used to calibrate the user's expectations of the index's current state.
Failure Handling
A common failure mode for these commands is the database is locked error (SQLITE_BUSY), which occurs if a sync operation is simultaneously writing to the database. The recommended action is a simple retry or waiting for the synchronization to complete.
| Error Code | Trigger | Recommended Action |
|---|---|---|
index_unavailable | Database file does not exist. | Run cxs sync --selector <json>. |
database is locked | Concurrent write/sync operation. | Retry after a short delay. |
selector_required | Command requires explicit scope. | Provide a valid JSON selector. |
Sources: skill-packages/cxs/references/failure-cookbook.md:5-18, skill-packages/cxs/references/cli-surface.md:14-18
Summary
The list and stats commands are essential for index management and browsing within the cxs ecosystem. list provides a non-textual browsing mechanism using metadata filters and selectors, while stats serves as a diagnostic dashboard for the underlying SQLite index. Both rely on the completion of the sync process and provide structured outputs designed for both human readers and automated agents.