Code Intelligence

Zeph provides out-of-the-box code intelligence for any project you work in — without plugins, language servers, or manual configuration. It combines three complementary layers into a unified search_code tool that the agent calls automatically when it needs to understand your codebase.

The Problem with Context Windows

When an agent needs to understand a large codebase, it faces a fundamental constraint: it cannot read every file. A grep-based approach works for small projects or large context windows, but becomes expensive at scale — each grep cycle consumes tokens, and an 8K-context local model might exhaust its budget after 3–4 searches.

Zeph’s code intelligence pre-indexes your project and retrieves the most relevant code for each query, so the agent spends its context budget on reasoning rather than searching.

Three Layers, One Tool

The search_code tool unifies three search strategies:

Structural Search (tree-sitter)

Tree-sitter parses your source files into an AST and extracts named symbols — functions, structs, classes, impl blocks — with accurate visibility annotations and line numbers. Structural search is fast, offline, and works for all supported languages without any external services.

Use structural search when you need exact definitions: “where is AuthMiddleware defined?”

Semantic Search (Qdrant)

When your question is conceptual rather than syntactic — “how does the authentication flow work?” — semantic search finds relevant code by meaning, not keyword. Each source chunk is embedded into a vector and stored in Qdrant. At query time, the question is embedded and the closest chunks are retrieved.

Semantic search requires a running Qdrant instance and an active code index. Enable it once and Zeph keeps the index up to date as you edit files.

LSP Integration

For precise cross-reference questions — “what calls this function?”, “go to definition” — Zeph delegates to the language server via the mcpls MCP tool. LSP answers are authoritative because they come from the same compiler-backed analysis used by IDEs.

LSP integration requires mcpls to be configured under [[mcp.servers]].

How the Agent Uses It

The agent calls search_code with a natural-language query. Zeph runs all available layers in parallel, deduplicates results, and returns a ranked list with file paths, line numbers, and relevance scores:

> find where API keys are validated

[structural] src/vault/mod.rs:34  pub fn validate_key
[semantic]   src/vault/mod.rs:34–67  (score: 0.94)
[semantic]   src/auth/middleware.rs:12–45  (score: 0.81)
[lsp]        3 references to `validate_key`

The agent uses these results to read specific files rather than scanning the entire codebase.

Repo Map

Alongside per-query retrieval, Zeph maintains a compact structural map of the project — a list of every public symbol with its file and line number. The repo map is injected into the system prompt and cached (default: 5 minutes). It gives the model a bird’s-eye view of the codebase without consuming significant context.

The repo map is generated via tree-sitter queries and works for all providers, including Claude and OpenAI. It does not require Qdrant.

Example:

<repo_map>
  src/agent.rs :: pub struct Agent (line 12), pub fn new (line 45), pub fn run (line 78)
  src/config.rs :: pub struct Config (line 5), pub fn load (line 30)
  src/vault/mod.rs :: pub fn validate_key (line 34), pub fn get_secret (line 68)
  ... and 14 more files
</repo_map>

Setup

Structural search and repo map (always available)

No setup required. Tree-sitter grammars are compiled into every Zeph build. The repo map is enabled by default with a 1024-token budget.

[index]
repo_map_budget = 1024    # tokens; set to 0 to disable
repo_map_ttl_secs = 300   # cache TTL

Semantic search (requires Qdrant)

1. Start Qdrant:

   docker compose up -d qdrant
   

2. Enable indexing:

   [index]
   enabled = true
   auto_index = true    # re-index on startup and on file changes
   

3. On first run, Zeph indexes the project automatically. Subsequent runs only re-embed changed files.

LSP integration (requires mcpls)

Configure mcpls as an MCP server in your config or via zeph init:

[[mcp.servers]]
name = "mcpls"
command = "mcpls"
args = ["--config", ".zeph/mcpls.toml"]

Run zeph init to have the wizard generate the correct mcpls config for your project.

Supported Languages

Related

• Code Indexing — full configuration reference, chunking algorithm, retrieval tuning
• LSP Context Injection — automatic diagnostic and hover injection on file read/write
• Tools — how search_code fits into the tool catalog
• Feature Flags — tree-sitter grammar sub-features