Crate ctx 

ctx - Code intelligence library for AI-assisted development.

This library powers the ctx CLI and can be embedded in your own tools. It provides:

• Code Indexing: Parse and index source code with symbol extraction
• Semantic Search: Find relevant code using embeddings
• Call Graph Analysis: Understand code relationships and impact
• Smart Context Selection: Intelligently select files for LLM context
• Diff-Aware Context: Generate context focused on code changes
• Token Management: Count and budget tokens for LLM context windows

Installation

The package is published on crates.io as agentis-ctx, but the library target is named ctx, so code imports use ctx:::

[dependencies]
agentis-ctx = "0.2"

Most of the commonly used types are re-exported through prelude:

use ctx::prelude::*;

Quick Start: index a codebase and search it

Indexing creates .ctx/codebase.sqlite under the project root. Subsequent runs are incremental — only changed files are reparsed.

use ctx::prelude::*;
use std::path::Path;

fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let root = Path::new("./my-project");

    // Build (or incrementally update) the index
    let mut indexer = Indexer::with_config(root, false, WalkerConfig::default())?;
    let result = indexer.index()?;
    println!(
        "Indexed {} files: {} symbols, {} edges",
        result.files_indexed, result.symbols_extracted, result.edges_extracted
    );

    // Reopen the database later without reindexing
    let db = open_database(root)?;

    // Keyword search over symbols (FTS5)
    for symbol in db.find_symbols("authenticate", 10)? {
        println!("{} ({}:{})", symbol.name, symbol.file_path, symbol.line_start);
    }
    Ok(())
}

Smart context selection

Select the files most relevant to a task description, within a token budget — the same engine behind ctx smart:

use ctx::prelude::*;
use std::path::Path;

fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let root = Path::new("./my-project");
    let db = open_database(root)?;
    let analytics = Analytics::open(root)?;

    // Local embedding model (downloaded on first use, ~90 MB).
    // OpenAIProvider is available as an alternative.
    let provider = LocalProvider::new()?;

    let context = smart_context(
        &db,
        &analytics,
        &provider,
        "add rate limiting to the API",
        SmartConfig::default(),
    )?;

    for file in &context.selected_files {
        println!("{} (relevance {:.2})", file.path, file.relevance_score);
    }
    println!("~{} tokens selected", context.total_tokens);
    Ok(())
}

Token counting

use ctx::tokens::{count_tokens, count_tokens_with_encoding, Encoding};

let n = count_tokens("fn main() { println!(\"hello\"); }").unwrap();
assert!(n > 0);

let n = count_tokens_with_encoding("hello world", Encoding::O200kBase).unwrap();
assert!(n > 0);

Module overview

Module	Purpose
index	Build and update the code intelligence index
db	SQLite storage: symbols, edges, files, FTS and vector search
parser	Tree-sitter based symbol/relationship extraction
embeddings	Embedding providers (local fastembed or OpenAI)
analytics	Call graph queries: callers, dependencies, impact (DuckDB)
smart	Task-driven file selection for LLM context
diff	Context generation focused on git changes
walker	File discovery with glob patterns and ignore rules
tokens	Token counting and budgeting (tiktoken)
formatter, output, tree	Rendering context as XML/Markdown/JSON/plain
audit	Code quality scoring for CI gates

Feature Flags

• duckdb (enabled by default) - DuckDB-backed analytics (call graphs, impact analysis, complexity). When disabled, analytics falls back to a stub that compiles everywhere (use this on Windows MSVC): add the dependency with default-features = false.
• mcp - Model Context Protocol server support for editor/agent integrations (see the mcp module).

Re-exports

pub use error::CtxError;

pub use error::Result;

Modules

analytics

Analytics module using DuckDB for complex graph queries.

audit

Code quality audit module.

check

Architecture-rules check engine (backs ctx check and the check_violations metric of ctx score).

db

Database module for code intelligence storage.

diff

Diff-aware context generation for code review and change understanding.

embeddings

Semantic search via embeddings.

error

Unified error type for ctx operations.

exit

Exit-code convention shared by all ctx commands.

fingerprint

Structural fingerprinting for near-duplicate function detection.

formatter

Output formatters for generated context.

gatelog

Gate-evaluation logging.

gitutil

Shared git helpers for quality commands.

harness

Harness packaging for ctx harness (Claude Code integration).

index

Code indexing module.

json

Machine-readable JSON output.

mcp

MCP (Model Context Protocol) server implementation for ctx.

output

Context generation from discovered files.

parser

Code parsing module using tree-sitter.

prelude

Prelude module for convenient imports.

rank

PageRank scoring over the symbol graph.

rules

Architecture rules for ctx check.

score

ctx score engine: a quality scorecard for the changes between a git reference and the current working tree.

smart

Smart context selection for LLM workflows.

snapshot

Per-commit metric snapshots (ctx snapshot).

tokens

Token counting for LLM context management.

tree

ASCII project tree rendering.

update

Release and update mechanism: ctx self-update, ctx --version --check, and the passive update notice.

utils

Shared utility functions for ctx.

walker

File discovery with glob patterns and layered ignore rules.