Skip to content

getting-started.md

Latest commit

 

History

History
149 lines (115 loc) · 5.26 KB

getting-started.md

File metadata and controls

149 lines (115 loc) · 5.26 KB
Raw

Getting started

This guide takes you from nothing to your first successful index and search with cce. It should be self-serve; if a step fails, that is a bug in this guide — please open an issue.

1. Prerequisites

cce is a single Rust binary whose tree-sitter dependencies compile C grammars from source. You need:

  • A stable Rust toolchain (via rustup).
  • A C compiler (Xcode Command Line Tools on macOS; build-essential on Ubuntu/Debian).

There is no database and no other system library to install — the index is just JSON on disk.

macOS

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
xcode-select --install

Ubuntu / Debian

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
sudo apt-get update && sudo apt-get install -y build-essential

2. Build and verify

git clone https://github.com/davidslv/cce-rust
cd cce-rust
cargo build --release     # binary at target/release/cce
cargo test                # confirms a green build (1002 tests)

Prefer not to build at all? Every release ships prebuilt binaries for macOS and Linux with a SHA256SUMS — see the Releases page and the README install section.

Optionally put the binary on your PATH:

cargo install --path .    # installs `cce` into ~/.cargo/bin
cce --version             # prints the version you built (see ../CHANGELOG.md)

The rest of this guide writes cce; if you did not install it, use ./target/release/cce instead.

3. Your first index

The repo ships a tiny multi-language sample corpus (one file per pack). Index it to a scratch store:

$ cce index test/fixture/samples --store /tmp/s.cce
Indexed test/fixture/samples
  files indexed : 7
  files skipped : 0
  total chunks  : 21
  embedder      : hash
  store         : /tmp/s.cce
  elapsed       : 0.002s

Files in a supported language (Python, JavaScript, Ruby, Rust, TypeScript, C) are chunked per function/class by tree-sitter through language packs; everything else becomes a single whole-file module chunk. Run cce packs to see the packs.

4. Your first search

search reopens the store in a fresh process — no re-embedding. Each result shows the coarse chunk_type and the exact node kind:

$ cce search "build the index store" --store /tmp/s.cce --top-k 3 --no-graph
 1. [0.79xxxx] rust.rs:3-5 (function/function_item)
    pub fn build_index() -> HashMap<String, u32> {
 2. [0.71xxxx] rust.rs:7-9 (class/struct_item)
    pub struct Store {
 3. [0.65xxxx] rust.rs:11-15 (class/impl_item)
    impl Store {

That is the whole loop: index a directory, then search it. The top hit is the build_index function — exactly the snippet you would feed to a model instead of the whole file.

5. Try it on your own code

Point cce at any project. By default the store lives at <dir>/.cce/index.json, so you can search with --dir instead of --store:

cce index ./my-project
cce search "where is the request handler" --dir ./my-project --top-k 5
cce stats --dir ./my-project

Add --json to search for machine-readable results.

The walk is gitignore-aware (since v2.6.3): files ignored by the repo's committed .gitignore are skipped, exactly as git sees the tree — while machine-local excludes (.git/info/exclude, the global core.excludesfile) are deliberately not honored, so the same commit indexes identically on every machine. .git/ and .cce/ are always skipped.

6. Optional: semantic embeddings

The default hashing embedder is offline and deterministic. If you want model-based vectors, install Ollama, pull the model, and pass --embedder ollama:

ollama pull nomic-embed-text
cce index ./my-project --embedder ollama

If Ollama is not running (or dies mid-index), cce index --embedder ollama fails loud with a clear error and writes no store — a store must never contain dead (empty) embeddings (#30). Searching an ollama-built index while Ollama is down also errors with guidance: start Ollama, or re-index with the default hash embedder. Set CCE_OLLAMA_URL / CCE_OLLAMA_MODEL to use a non-default endpoint or model.

Where to next

  • how-to.md — task recipes for every command.
  • mcp.md — wire CCE into an agent (Claude Code) as nine MCP tools.
  • sync.md — share the index through a git-backed cache: pull the CI-built index in seconds, or consume a whole team cache with no source checkout at all (consumer mode: cce sync pull --all).
  • savings.md — the seven Savings Layers, cce savings, and the honest "vs full-file baseline" framing.
  • knowledge.md — feed issues/epics/policy docs in with cce knowledge index and search them alongside the code (v2.6).
  • adding-a-language.md — add a language pack in one file.
  • architecture.md — how the pipeline is built and why.
  • ../SPEC.md + ../SPEC-V2.md — the authoritative behaviour reference (base engine + language packs).