Implementation Sourcesrc/index.ts

Usage

The ContextOS binary is installed globally or invoked via npx. All commands are executed within the context of your current working directory (which is expected to be a Git repository).

npx contextos <command> [options]

Commands

`init`

Initializes ContextOS in the current repository. This creates the local .contextos SQLite database, parses all supported files, generates AST chunks, extracts relationship edges, and computes embeddings (if configured).

contextos init

`query`

Execute a natural language search against the repository. This runs the RRF Hybrid Retriever and Graph Expansion engine to return the most contextually relevant codebase snippets.

contextos query "How is the authentication token validated?"

Options

--raw: Output raw JSON instead of human-readable text.
--depth <n>: Set the BFS graph expansion depth (default: 2).

`watch`

Starts a background filesystem watcher (using chokidar). When you save a file in your editor, the watcher instantly diffs the AST and surgically updates the SQLite graph. This allows the index to stay up-to-date with zero manual re-indexing.

contextos watch

`daemon`

Starts the ContextOS HTTP / JSON-RPC server on a local port. This daemon is used by IDE extensions (like Cursor or VSCode) to communicate with the retrieval engine over a persistent connection.

contextos daemon --port 4000

`reindex`

Forces a hard rebuild of the .contextos database. Useful if the database state becomes corrupted or if you change ignore patterns in contextos.json.

contextos reindex

`status`

Prints the current indexing metrics of the repository, including chunk counts, total relationship edges, and the SQLite database file size.

contextos status