Local Development & Setup

Relevant source files

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

• AGENTS.md
• CONTRIBUTING.md
• package.json
• README.md
• skill-packages/cxs/SKILL.md
• src/cli.test.ts

cxs is a local-first Command Line Interface (CLI) designed for the progressive retrieval and indexed search of local Codex session logs (JSONL). It operates as a retrieval engine that interfaces with a SQLite database to provide ranked search results and contextual message reading, intended for use by both human developers and AI agents.

The development environment focuses on a Node.js-based toolchain, leveraging TypeScript for logic and SQLite for persistence. Unlike real-time sync daemons, cxs relies on manual incremental synchronization via its sync command to update its index from raw session files located in ~/.codex/sessions.
Sources: README.md:1-12, AGENTS.md:3-10

Environment Requirements

To set up a local development environment for cxs, the following prerequisites must be met:

• Runtime: Node.js version 22 or higher.
• Operating System: macOS or Linux (Windows users should use WSL). The system must have read access to the local Codex session data, typically stored in ~/.codex/sessions.
• Dependency Management: npm is used for package management and script execution.

Sources: CONTRIBUTING.md:3-5, package.json:34-37, README.md:30-34

Project Initialization

Follow these steps to initialize the repository for local development:

1. Clone the Repository:

   git clone https://github.com/catoncat/cxs.git
   cd cxs
   

2. Install Dependencies: Use npm to install required packages, including better-sqlite3 for database operations and esbuild for the build pipeline.

   npm install
   

3. Verify Installation: Run the CLI from source using tsx to ensure the environment is correctly configured.

   npm run cxs -- --version
   

Sources: CONTRIBUTING.md:11-13, package.json:39-47, README.md:155-161

Development Workflow

The project uses a structured workflow for building, testing, and verifying changes.

Build and Execution

cxs uses esbuild to bundle TypeScript source files into a single ECMAScript module (ESM) for distribution. During development, developers can run the CLI directly from source using the tsx wrapper.

Script	Purpose	Command
build	Bundles src/cli.ts into dist/cli.js	npm run build
cxs	Executes the CLI from source via tsx	npm run cxs -- <args>
check	Runs Typechecking (TSC) and Tests (Vitest)	npm run check

Sources: package.json:39-47, CONTRIBUTING.md:15-18

Development System Flow

The following diagram illustrates the data flow from raw session logs to the user interface during development.

The system prioritizes manual synchronization; only the sync command modifies the SQLite index, while all other commands are read-only.
Sources: AGENTS.md:12-16, AGENTS.md:46-56

Testing and Evaluation

Reliability is maintained through unit tests and specialized evaluation runners.

Automated Testing

Unit tests are written using Vitest. The project enforces a strict "check" before any commit or release.

npm run check

Sources: CONTRIBUTING.md:34-36, src/cli.test.ts:35-45

Manual and Dogfood Evaluation

To maintain search quality, the project includes evaluation tools located in the eval/ directory.

• Manual Eval: Runs a predefined set of queries and exports results for qualitative analysis.

  npm run eval:manual
  

• Dogfood Eval: A specialized runner for the developer's real history retrieval collection.

  npm run eval:dogfood -- <goldens.local.jsonl>
  

Sources: CONTRIBUTING.md:20-25, AGENTS.md:92-105

Development Binary (cxsd) and Skill Integration

For testing agent integration (e.g., with Codex or Claude), the project defines a convention for a development-only binary called cxsd.

• cxsd: An alias or symlink pointing directly to the local src/cli.ts.
• Skill Linking: Instead of using the production cxs skill, developers link the skill-packages/cxs directory to their agent's local skill path to test unreleased changes.

This approach ensures that "dirty" local changes are verified before being published to the global cxs skill via npm.
Sources: AGENTS.md:73-88

Data Persistence and Storage

cxs stores its indexed data in a SQLite database. The location of the database follows standard XDG paths but can be overridden.

Path Type	Default Location	Override Variable
Data Directory	~/.local/state/cxs/	CXS_DATA_DIR
Index File	index.sqlite	N/A
Source Data	~/.codex/sessions	N/A

Sources: README.md:94-100, skill-packages/cxs/SKILL.md:104-105

Summary

Setting up cxs for local development involves configuring a Node.js 22 environment, installing dependencies via npm, and utilizing the npm run cxs script for source-level execution. The architecture relies on a manual synchronization process to populate a SQLite index from local Codex session files. Quality is ensured through Vitest for unit testing and specialized evaluation scripts in the eval/ directory to measure search accuracy.
Sources: CONTRIBUTING.md:3-13, README.md:155-161