Semantic Explorer

sx is a local-first semantic and lexical code explorer built in Rust. It indexes code and configuration files from a project and supports fast search workflows from the terminal or interactive TUI.

Features

• Discover repository context and initialize a local .sx workspace.
• Build and update indexed content with incremental indexing.
• Run BM25 text search, semantic search, and hybrid query modes.
• Inspect referenced chunks and trace results into working directory guidance.
• Interact from CLI subcommands and default TUI mode.

Requirements

• Rust 1.75+ for source builds.
• SQLite and internet access when using remote embedding providers.

Go LSP support (gopls)

sx can use gopls for more accurate Go semantics:

• sx trace uses gopls call_hierarchy for Go call edges when available (auto-enabled).
• sx lsp ... provides read-only Go navigation commands (definition, references, implementations, call hierarchy, symbols, diagnostics).

Install gopls:

go install golang.org/x/tools/gopls@latest

Trace controls:

sx trace "<query>"          # auto-uses gopls for Go if available
sx trace "<query>" --no-lsp # force heuristic mode
sx trace "<query>" --lsp    # force gopls mode (errors if gopls missing)

Go navigation examples:

sx lsp def src/main.go:10:6
sx lsp refs src/main.go:10:6 --declaration --json
sx lsp impl src/main.go:10:6
sx lsp calls src/main.go:10:6
sx lsp symbols src/main.go
sx lsp ws-symbol "Foo"
sx lsp sig src/main.go:10:6
sx lsp highlight src/main.go:10:6
sx lsp check src/main.go

Configuration:

• .sx/config.toml: [lsp] enabled, [lsp.go] enabled, and [trace] go_use_gopls_calls.

Installation

Homebrew tap (recommended)

brew tap BrainBuzzer/sx
brew install sx

One-line installer

curl -fsSL https://raw.githubusercontent.com/BrainBuzzer/sx/main/install.sh | sh

Build from source

cargo install --path .

Onboarding command (complete)

The onboarding entry point is:

sx onboard

This launches the interactive configuration flow for embedding provider/model credentials used by sx.

Use non-interactive mode only when needed:

sx onboard --defaults
sx onboard --skip-check
sx onboard --defaults --skip-check

Current available onboarding flags:

• --defaults to skip prompts and use current defaults.
• --skip-check to skip provider connectivity checks during onboarding.

For provider credentials, use the auth command directly:

sx auth zhipu --api-key <KEY>
sx auth voyage --from-env
sx auth status

How this repo works right now

sx is a terminal-first code exploration workflow built around a project-local index.

1. Initialize workspace and database:

sx init

This sets up .sx/, resolves root config (.sx/config.toml), and migrates .sx/index.sqlite.

2. Build search index:

sx index
sx index --full

Creates chunked, BM25-ready local indexes from project files.

3. Search text:

sx search "<query>" --limit 20
sx search "<query>" --fts
sx search "<query>" --json

4. Build embedding vectors (optional but required for semantic modes):

sx embed
sx embed --full
sx embed --provider openai --model <model>

5. Run semantic / hybrid searches:

sx vsearch "<query>"
sx query "<query>"

6. Navigate findings:

sx get "<result-id>"
sx open "<result-id>"
sx cd "<query>"
sx guide "<query>"
sx trace "<query>"

7. Environment checks:

sx doctor

sx opens directly into the interactive TUI when no subcommand is provided:

sx

Usage

# initialize workspace, index, and search
sx init
sx index
sx search "semantic search" --limit 20

# open and inspect by reference
sx get "<result-id>"
sx open "<result-id>"

# launch TUI mode
sx

Repository layout

• src/cli.rs defines available commands and flags.
• .sx/config.toml is the generated project configuration.
• .sx/index.sqlite stores local index data.

License

MIT License. See LICENSE.