Stop reading
whole files.

code-kb helps your coding agent find the part of a repository it needs: a file outline, one function with nearby context, or the code that calls it.

61–99% fewer tokens than a file read 1–100 ms for most queries about 25–40 MB of memory 42 languages

Install code-kb See the seven tools

Works with Claude Code, Grok CLI, Antigravity, Codex CLI, and Cursor. Ships binaries for Windows, Linux, and macOS.

crates/code-kb-core/src/telemetry.rs 2,336 lines
≈ 20,900 tokens 
fn sanitize_error_message(msg: &str) -> String {{ /* 4 lines hidden: L772-L775 */ }
    let home_candidates = home_candidates();    sanitize_error_message_with_homes(msg, &home_candidates)}
/// Replaces the user's home directory with `~` and keeps everything else, including newlines.fn mask_home_paths(text: &str) -> String {{ /* 3 lines hidden: L778-L780 */ }
    mask_home_paths_with(text, &home_candidates())}
fn home_candidates() -> Vec<String> {{ /* 18 lines hidden: L782-L799 */ }
    let mut candidates = Vec::new();    for var in ["HOME", "USERPROFILE"] {        if let Ok(home) = std::env::var(var)            && !home.trim().is_empty()            && home != "/"        {            let simplified = dunce::simplified(Path::new(&home))                .to_string_lossy()                .to_string();            if simplified != home {                candidates.push(simplified);            }            candidates.push(home);        }    }    candidates}
fn mask_home_paths_with(text: &str, home_candidates: &[String]) -> String {{ /* 15 lines hidden: L801-L815 */ }
    let mut masked = text.to_string();    for home in home_candidates {        let norm_home = to_forward_slash(&normalize_path(Path::new(home)));        masked = masked.replace(home.as_str(), "~");        if norm_home != *home {            masked = masked.replace(&norm_home, "~");        }        let backslash_home = home.replace('/', "\\");        if backslash_home != *home {            masked = masked.replace(&backslash_home, "~");        }    }    masked}
fn sanitize_error_message_with_homes(msg: &str, home_candidates: &[String]) -> String {{ /* 20 lines hidden: L817-L836 */ }
    let mut sanitized = mask_home_paths_with(msg, home_candidates);    // Replace newlines with spaces to avoid breaking markdown tables    sanitized = sanitized.replace("\r\n", " ").replace(['\n', '\r'], " ");    // Escape markdown table pipe characters    sanitized = sanitized.replace('|', "\\|");    // Truncate message to 500 characters    if sanitized.chars().count() > 500 {        let mut truncated: String = sanitized.chars().take(500).collect();        if truncated.ends_with('\\') && !truncated.ends_with("\\\\") {            truncated.pop();        }        truncated    } else {        sanitized    }}
      ⋮  1,500 more lines to the end of the file

Example output from this repository. Token estimates use one token per four bytes.

Why

Reading a whole file adds up

Reading this 2,336-line file to find one function signature adds about 21,000 tokens to the conversation. That leaves less room for the task and earlier decisions. code-kb can show the signature or the function's context on its own.

Read the file

cat crates/code-kb-core/src/telemetry.rs
Lines
2,336
Tokens
≈ 20,900
Needed
one signature

Ask code-kb

file_skeleton("telemetry.rs")
get_symbol_context("sanitize_error_message")
Skeleton
≈ 2,400 tokens, 88% less
Context slice
≈ 420 tokens, 98% less
Query time
≈ 5 ms skeleton, ≈ 110 ms context

What it does

What your agent can find

File outlines
file_skeleton lists a file's types and function signatures without the implementation. On a folder, it gives a short directory overview.
Function context
get_symbol_context shows a function's code and return type, its callers with their evidence, the tests to run with their commands, the markers its sibling symbols share, the signatures of functions it calls, and related types, in one call.
Callers and tests
find_references lists every caller site, and blast_radius follows callers across the repository to the tests to run. Use them when you need the full list. With no target, blast_radius checks your uncommitted changes.
Post-edit check
After you edit, check_edit lists the symbols whose shape changed and every call, construction, or match that your diff did not reach. code-kb hook Stop runs it when the agent stops and blocks once if a site still uses the old shape.
Up-to-date results
Edit files as usual. code-kb picks up changes automatically and refreshes a file before showing its body or outline.
Usage stats
Run code-kb stats to see estimated tokens saved, tool calls, and errors across sessions.
Windows support
Every release includes a Windows binary tested on NTFS. Results show paths with forward slashes on every platform.
Structural facts
Find routes, queries, config keys, and more with the code-kb facts command. It lists the categories indexed in your repository.
Agent hooks
code-kb hook SessionStart tells the agent when to use each tool and records the commit the session started at. code-kb hook Stop and code-kb hook SubagentStop run the edit check. The hooks run from the binary without a script runtime.

Languages

42 supported languages

The bundled julie-extract 3.12.0 indexes these languages and file formats. What it can extract varies by language.

Code and scripts
Bash, C, C++, C#, Dart, Elixir, Erlang, F#, GDScript, Go, Java, Kotlin, Lua, PHP, PowerShell, Python, R, Ruby, Rust, Scala, Swift, VB.NET, Zig.
Web and UI
CSS, HTML, JavaScript, JSX, QML, qmldir, Razor, TSX, TypeScript, Vue.
Data and documents
go.mod, go.sum, JSON, Markdown, regex, SQL, TOML, XML, YAML.

Find more than names

Structural facts are indexed details beyond symbol names. Examples include Express and FastAPI routes, SQL statements, TOML keys, Go module dependencies, and QML bindings. Run code-kb facts to see the categories found in your repository, or code-kb facts route to list routes. See the extractor's supported-language list for more detail.

Compared

code-kb and manual file search

Task With code-kb Reading and searching files
Prompt tokens per lookup 61–99% fewer than a full-file read in measured examples 5,000–15,000 per file read
Find a signature file_skeleton, bodies removed Find and copy the relevant lines
Search by concept Search indexed names and signatures Search file text, including comments and logs
Prepare an edit get_symbol_context, one call Find the function and related code separately
Calls outside the project Common runtime calls filtered across source languages Filter matches yourself
Predict which tests to run get_symbol_context lists the tests to run; blast_radius walks further Find relevant tests yourself
Select an overloaded symbol Choose the exact result by its symbol_id Narrow it down by name and file path
Query time 1–100 ms for most warm queries; check_edit takes seconds on a real diff Depends on the file and search command
Memory held by the server About 25–40 MB; 50–60 MB after a large callers report No server process
Context left for the task Less file text added to the conversation Full file reads use more of the conversation

Steps

From first look to tested change

Here's one way to use code-kb when you start work in an unfamiliar repository.

  1. Orient

    Directory tree and the main exports, in a few hundred tokens.

    file_skeleton("src")

  2. Find the interface

    Signatures and traits with bodies removed. Search by concept when the name is unknown.

    file_skeleton("src/server.rs")
lookup_symbol("auth token validation")

  3. Get the context

    Before you change a symbol: its body, its callers, the tests to run with their commands, the markers its siblings share, its callees' signatures, and its types in one call.

    get_symbol_context("handle_request")

  4. Edit

    Read the file you will edit, since the editor needs it, and edit with your usual tools. code-kb picks up file changes automatically.

  5. Check the edit

    The symbols whose shape changed and every site that your diff did not reach. For the full list of callers or tests, call find_references or blast_radius.

    check_edit()

  6. Verify

    Run the tests that the context listed. Check usage with code-kb stats.

    cargo test handle_request
code-kb stats

Tools

Seven tools, each with a matching command

Every MCP tool has a one-to-one CLI command, so you can check any answer from the terminal.

Every tool also requires project_root, the absolute path of the project or git worktree you work in. The Accepts column lists the other parameters. The CLI takes the same value as --root, which defaults to the current directory.

MCP tool CLI command Returns Accepts
file_skeletoncode-kb skeleton <file>
or code-kb outline [path] for a folder		File outline, bodies removed; a folder returns its layout; public_only hides private rowsfile_path (a file or a folder), public_only
lookup_symbolcode-kb lookup <query>Name, prefix, or concept; a query that names no symbol exactly also gets ranked matches; a query that names one definition with a short body also gets that body; a query with /, ., {, or : also lists matching routes and config keys; each result row includes id=<symbol_id>query, path, kind, is_test, limit
get_symbol_bodycode-kb body [symbol]
or code-kb body --symbol-id <id>		Source of one symbolsymbol_name or symbol_id, file_path
get_symbol_contextcode-kb context [symbol]
or code-kb context --symbol-id <id>		Body and return type, callers summary, tests to run with commands, callee signatures, types, open endssymbol_name or symbol_id, file_path, include_external
find_referencescode-kb refs [symbol]
or code-kb refs --symbol-id <id>		Every caller site, labeled by its evidence, or callees with stdlib calls filteredsymbol_name or symbol_id, file_path, direction (default callers), include_external, offset, limit
blast_radiuscode-kb blast-radius [symbol]
or code-kb blast-radius --symbol-id <id>
or code-kb blast-radius --file <file>		Multi-hop callers and tests to runsymbol, symbol_id, or file (omitted target reads git changes), depth (default 2), include_low_signal, offset, limit
check_editcode-kb check [--base REV]After you edit: the symbols whose shape changed, and every site of each that your diff did not reachbase (default: the session base, else HEAD), offset, limit

Four query commands have no MCP tool: code-kb outline [path] prints a folder's layout, which file_skeleton on a folder also returns, code-kb search <query> prints the ranked search with each row's score (--explain adds the score breakdown), code-kb facts [category] lists routes, queries, models, and config keys, and code-kb stats reports token savings and tool errors.

Install

Connect it to your agent

Choose your agent below for setup steps. The plugin needs Node.js 18 or newer. On first use, it downloads code-kb and the matching julie-extract for your platform.

You can also download the release archive, put both binaries on PATH, and register the server yourself. The same code-kb serve command works in GUI apps and terminal agents. --root is optional; it only prepares that project's index at start. See the README for more setup options.

Install the plugin, skill, and hooks with these two commands:

/plugin marketplace add anortham/code-kb
/plugin install code-kb@code-kb

For manual setup across projects on this machine:

claude mcp add --scope user code-kb -- code-kb serve

For one project, in .mcp.json:

{
  "mcpServers": {
    "code-kb": {
      "command": "code-kb",
      "args": ["serve"]
    }
  }
}