ctx

AI coding agents write fast, sloppy code. They duplicate logic that already exists, drift the architecture, and declare "done" without proof.

ctx is the local quality authority for AI-written code. It's a single local binary that turns your repo into a queryable model (every symbol, call, and dependency) and uses it to ground your agent and gate its output on every turn:

• Ground: hand the agent a map before it starts, and the right ~8k tokens of context instead of the wrong 233k.
• Govern: show the blast radius of every edit, and enforce your architecture rules as deterministic gates it can't ship past.

Rules live in your repo as code, checks run in milliseconds inside the agent's loop, and nothing leaves your machine.

Unlike code-graph tools, ctx governs what agents write, not just what they read. Unlike quality platforms, it does so in milliseconds, locally, with gates you own.

📖 Documentation: https://docs.agentis.tools/

Install

cargo install agentis-ctx        # crate is `agentis-ctx`; it installs the `ctx` binary

Prebuilt binaries for Linux (x86_64), macOS (Intel + Apple Silicon), and Windows (x86_64) are attached to each GitHub release. Once installed, ctx self-update upgrades in place (every download is checksum-verified against the release's SHA256SUMS before replacing the binary).

# On Windows (MSVC), DuckDB analytics aren't available, so skip the default feature:
cargo install agentis-ctx --no-default-features

See the Getting Started guide for the full platform matrix.

The loop: index → ground → govern

Build the model first. Every intelligence and governance command reads a prebuilt index, so ctx index always comes first (it writes a single .ctx/codebase.sqlite). On this repo it indexes 870 symbols and 5,463 call edges in 0.36s. Run it once, then keep it warm with --watch.

ctx index                        # build the world model (or `ctx index --watch` in the background)

Ground: feed the agent the right context, selected by meaning and call-graph relevance:

ctx smart "add rate limiting" --max-tokens 8000   # ~8.7k tokens instead of 233k, about 27× smaller
ctx diff --summary                                # context for what changed, with dependency expansion
ctx similar "retry with backoff"                  # reuse before you write: find it if it already exists

Govern: guardrail what the agent changes, with deterministic pass/fail gates:

ctx check --against origin/main                                   # enforce architecture rules
ctx score --fail-on "check_violations>0,new_duplication>0"       # one composite quality gate

One model, two jobs

ctx indexes your repo into a structured, queryable model: symbols, call graphs, relationships, and semantics. Not a bag of files, but a model an agent (or you) can ask questions of. That one model does two jobs: it feeds the model the right context going in, and guardrails what it changes coming out.

Ground: the right context, in

Plain ctx is also a context generator: select files by glob and stream LLM-ready output:

ctx src/ | pbcopy                 # copy source to the clipboard (XML by default)
ctx --format markdown src/        # or Markdown / JSON / plain
ctx --count-only src/             # just count tokens against your model's window
ctx --max-tokens 8000 "src/**/*.rs"

Semantic search and ctx smart/ctx similar need embeddings first. Generate them with ctx embed (a ~90 MB local model by default, or --openai with OPENAI_API_KEY). See Index & embed first.

Govern: guardrails on what changes

Architecture rules live in your repo as code (.ctx/rules.toml: layers, forbidden dependencies, fan-in/complexity limits) and --against <ref> scopes any gate to only what a diff changed, so a PR or an agent is judged on its new violations, not the repo's history.

Exit codes are the integration API. Every governance command shares one convention, so CI and agents read the result the same way:

See the Quality Gates guide for CI recipes and the --json contract.

Drop it into Claude Code

The point of ctx is to run inside the agent's loop, not beside it. One command wires the whole suite into Claude Code as hooks, with the guardrails already set:

ctx harness init --target claude          # local hooks in .claude/ (or --mode plugin for a shareable plugin)

This scaffolds three hooks and a starter .ctx/rules.toml:

• SessionStart → ctx map primes the agent with a codebase map before it does anything.
• PostToolUse (on Edit/Write) → ctx index reindexes, then ctx check --against HEAD flags any architecture violation the edit just introduced.
• Stop → ctx score --fail-on "check_violations>0,new_duplication>0": a quality scorecard on the whole change before the agent calls it done.

The generated permissions let the agent run ctx * but deny ctx self-update and edits to the rules, hooks, and settings, so an agent can't weaken the policy that governs it. ctx harness doctor diagnoses the integration. Details in the Claude integration guide and Using ctx with agents.

MCP server (Claude Desktop)

ctx can also expose the world model over the Model Context Protocol. MCP is feature-gated and not in the default/release binaries, so build with the mcp feature:

cargo install agentis-ctx --features mcp
ctx serve --mcp

Configure Claude Desktop and see the available tools in the Claude integration guide.

Command reference

The full flag reference for every command lives at docs.agentis.tools. At a glance:

Supported Languages

See Language Support for detail.

Using ctx as a library

Everything the CLI does is available as a Rust library, so you can embed indexing, search, and context generation in your own tools. The package is agentis-ctx; the library target is named ctx:

[dependencies]
agentis-ctx = "0.3"

# On Windows (or to skip DuckDB analytics):
# agentis-ctx = { version = "0.3", default-features = false }

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 at .ctx/codebase.sqlite
    let mut indexer = Indexer::with_config(root, false, WalkerConfig::default())?;
    let result = indexer.index()?;
    println!("{} symbols extracted", result.symbols_extracted);

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

The API documentation covers the full surface: smart context selection, diff-aware context, semantic search (local or OpenAI embeddings), call-graph analytics, token counting, and output formatting.

How it works

.ctx/
├── codebase.sqlite    # symbols, edges, embeddings, compressed source (FTS5 + sqlite-vec)
└── rules.toml         # your architecture rules (created by `ctx harness init`)

• Tree-sitter parses every supported language into symbols and relationship edges.
• SQLite (with FTS5 and sqlite-vec) is the persistent, single-file store.
• DuckDB runs the recursive graph and analytical queries (default-on; not available on Windows).
• fastembed generates local embeddings offline (all-MiniLM-L6-v2, 384-dim); OpenAI is optional.

Indexing respects .gitignore, an optional .contextignore, and 170+ built-in patterns. See Configuration and Architecture.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on development setup, coding style, and the pull request process.

Security

To report a security vulnerability, see SECURITY.md.

License

This project is licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.