RCE Code
GitHub

Quick Start

Go from a checked-out repository to ranked search results in a few minutes. This page runs the same flow two ways — through the CodeEngine Python facade and through the rce-code CLI — using nothing but the offline default install.

The shape is identical either way: open or create an index for a repo, index it, embed its chunks, then search and build a repo map. Indexing and embedding are incremental, so re-running them on an unchanged tree is nearly free.

Using Python

1

Open or create the index

CodeEngine.open_or_create opens the index database for a repo (creating and migrating it on first use) and returns a ready facade. The index lives at <repo>/.rce/code/index.db.

from rce.code import CodeEngine


engine = CodeEngine.open_or_create("/path/to/repo")
2

Index and embed

index() walks the repo, parses with tree-sitter, chunks along definition boundaries, extracts symbols and references, and resolves the call graph. embed() then embeds any chunks that lack a current embedding — with the default offline HashingEmbedder, no network is used.

engine.index()    # walk -> parse -> chunk -> symbols -> refs -> resolve
engine.embed()    # embed pending chunks (default offline HashingEmbedder)
3

Run a hybrid search

search_hybrid fuses lexical, semantic, and symbol results with Reciprocal Rank Fusion and returns a list of SearchResult. Each hit carries a score and the matched chunk.

for hit in engine.search_hybrid("authentication middleware", top_k=5):
    print(round(hit.score, 3), hit.chunk.file_path, hit.chunk.name)
4

Build a repo map, then close

build_repo_map renders a relevance-ranked, token-budgeted map of the repository, optionally biased toward focused files. Call close() when you are done to release the database connection.

print(engine.build_repo_map(focused_files=["src/auth.py"], token_budget=1024))
engine.close()

The whole flow as a single script:

quickstart.py
from rce.code import CodeEngine


engine = CodeEngine.open_or_create("/path/to/repo")
engine.index()                       # walk -> parse -> chunk -> symbols -> refs -> resolve
engine.embed()                       # embed pending chunks (default offline HashingEmbedder)


for hit in engine.search_hybrid("authentication middleware", top_k=5):
    print(round(hit.score, 3), hit.chunk.file_path, hit.chunk.name)


print(engine.build_repo_map(focused_files=["src/auth.py"], token_budget=1024))
engine.close()

Offline by default

The default HashingEmbedder is deterministic and needs no network, so semantic and hybrid search work right after install. Pass a real embedder to open_or_create when you want embedding quality — OpenAI-compatible, sentence-transformers, or your own. See Embedders.

Using the CLI

Installing the package provides a rce-code command. Every subcommand takes --repo, which defaults to the current directory (.). The CLI mirrors the Python flow.

rce-code index                                      # build / refresh the index
rce-code embed                                      # embed chunks that lack an embedding
rce-code search-hybrid "authentication middleware"  # fused lexical + semantic + symbol
rce-code repomap --focus src/auth.py                # token-budgeted repo map
rce-code stats                                      # index health snapshot

Run rce-code search-hybrid before embed and you still get lexical and symbol matches — semantic results join the fusion once chunks are embedded. Pass -k / --top-k to a search command to change the result count, and repeat --focus to bias the repo map toward several files.

See all options

Run rce-code --help for the full subcommand list, or rce-code <command> --help for a single command's flags. Other subcommands include search (lexical), search-semantic, grep, symbols, find, refs, callers, and callees.

Where to go next

Core Concepts

The mental model behind the index: chunks, symbols, references, freshness, embeddings.

Search Overview

Each retrieval modality in depth, and when to reach for it.