code-search-cli 0.3.0

Task-aware code search for coding agents

Explainable evidence. Scoped context. No runtime model.

English | 简体中文 | 日本語 | 한국어 | Русский

Code Search is a task-aware retrieval CLI for coding agents. It returns a concise, verifiable set of source evidence for an engineering task, not only a list of similar snippets.

The current version is an independently implemented, fully model-free MVP: no embeddings, no GPU, no server, and no network calls. It can read a working tree or any Git revision and returns source locations, ranking reasons, structural evidence roles, provenance, categorical confidence, and payload statistics.

Search less. Hand the agent the evidence it needs to act.

Quick start

Install from PyPI

uv tool install code-search-cli
code-search --version

The distribution is named code-search-cli; the installed command remains code-search.

Install from this checkout

cd /path/to/code-search
uv tool install .
code-search --version

Retrieve evidence for a task

code-search retrieve \
  --repo /path/to/repository \
  --task "Fix dependency injection order so startup events are not missed"

The command is read-only. It does not check out revisions, modify the target repository, or create an index inside it. It incrementally maintains a per-user SQLite index under the operating-system cache directory, honors Git ignore rules for working trees, and uses code-search clean to remove the cached source snapshot and derived metadata.

Optional agent integration

code-search install                  # Codex remains the default
code-search install --target cursor  # Or select one target explicitly

The bundled code-search Agent Skill can be installed for Codex, Claude Code, Cursor, Gemini CLI, OpenCode, GitHub Copilot, or Kiro. Installation is user-level and idempotent. It tracks hashes of the files it installed, so an untouched older release can upgrade safely while a locally modified skill is still protected unless --force is supplied. Add --dry-run to preview the operation. The CLI remains the primary interface; installing the skill adds neither an MCP server nor a runtime model.

Why there is no model underneath

Retrieval is deterministic, auditable, and runs entirely on lexical and structural signals: stemmed term matching, file-name coverage, structural expansion, and task-role inference. The same query on the same tree returns the same evidence, every result explains why it was included, and nothing is downloaded at runtime. Model-backed products appear in the public benchmark only as separately versioned comparison methods; they are not Code Search runtime dependencies.

What you get

• A concise, de-duplicated evidence set instead of an unbounded list of matches.
• Source locations, scores, inclusion reasons, evidence roles, provenance, categorical confidence, and estimated token cost for every result.
• Lightweight structural obligations for lifecycle, event, dependency-ordering, and test evidence.
• Direct reads from a working tree or historical Git revision without changing the checkout.
• A persistent incremental index that verifies content hashes and reuses unchanged source terms and structural boundaries.
• Optional code, tests, or config scope filters when a task does not need the whole repository.
• Source indexing across C/C++, C#, Elixir, Go, Haskell, Java, JavaScript/TypeScript, Kotlin, Lua, PHP, Python, Ruby, Rust, Scala, shell/Bats, Swift, Zig, and common configuration formats.
• Model-free structural extraction for Java/Kotlin/Scala, Python, and JavaScript/TypeScript on the default path.
• Compact exact-symbol windows across all indexed source formats when the whole task is an identifier or qualified name.
• A bundled Agent Skill, with user-level filesystem installers for Codex, Claude Code, Cursor, Gemini CLI, OpenCode, GitHub Copilot, and Kiro, that teaches the agent when to retrieve, expand, or fall back to exact rg. Their paths, dry-run behavior, idempotence, safe upgrades, and file-protection behavior have automated coverage.

Task evidence beyond ranked matches

A flat result list may return both a target function and a similar working function. For the callback patterns it currently supports, Code Search compares them and can label the behavior that is present in one path but absent from the other. For supported lifecycle patterns, it can also keep separate repair responsibilities in one evidence bundle.

From a source checkout, run the synthetic fixtures:

uv run python scripts/showcase_evidence.py

The task-evidence contract documents the fixture and its generated output. This is a regression check, not a held-out quality benchmark or a patch-success claim.

CLI

Read a historical revision:

code-search retrieve \
  --repo /path/to/repository \
  --ref HEAD~1 \
  --task "Resolve NullPointerException in scheduled dump" \
  --format json

Limit a focused query to conventional test paths and filenames:

code-search retrieve \
  --repo /path/to/repository \
  --task "Find regression tests for field naming" \
  --scope tests

--scope accepts all (the default), code, tests, or config. It filters files before ranking; leave it at all when a task crosses production code, configuration, and tests.

Expand a known anchor to its enclosing unit, siblings, or references:

code-search expand \
  --repo /path/to/repository \
  --path src/main/java/example/Service.java \
  --line 120 \
  --relation enclosing

Manage the optional Agent Skill:

code-search install                                  # Codex
code-search install --target claude-code
code-search install --target cursor
code-search install --target gemini
code-search install --target opencode
code-search install --target github-copilot
code-search install --target kiro
code-search install --target detected                # Best-effort convenience selector
code-search install --target detected --dry-run      # Preview without writing
code-search uninstall --target cursor
code-search uninstall --target detected

The installer writes only managed Skill files and its hash manifest inside the selected agent's user configuration:

Agent-specific environment overrides must be absolute paths; a relative XDG_CONFIG_HOME is ignored as required by the XDG base-directory specification. An existing legacy Codex installation under ~/.codex/skills/code-search/ is updated and removed in place instead of being silently migrated.

detected is a best-effort convenience selector based on known commands, configuration directories, environment overrides, and an already-installed target. It does not launch a client or verify that the client can load the skill. Cursor detection deliberately relies on ~/.cursor rather than the ambiguous agent executable name. Because some clients also scan another client's compatibility directories, prefer an explicit target and use one if the same skill appears more than once.

Every selected destination is preflighted before writing or removing files. A small hidden manifest records hashes of the managed files; it is installer metadata, not another instruction loaded by the agent. This lets an untouched older installation upgrade without treating it as a user edit. Uninstall removes only managed files whose content is still recognized and leaves extra user files in place. Use --force only when you intentionally want to replace or remove a modified managed file. --dry-run performs the same checks and reports the planned action without changing files.

Prewarm, inspect, or remove the per-repository index:

code-search index --repo /path/to/repository
code-search status --repo /path/to/repository
code-search clean --repo /path/to/repository

Benchmark

The repository publishes two recorded development comparisons. Both measure Code Search, Semble, code-review-graph, BM25, Probe, and ripgrep. They use different datasets and adapters, so their scores must not be merged into one leaderboard. The shared Java runner reproduces all six methods; the multilingual public runner currently reproduces BM25, Probe, and ripgrep, while the other three rows retain their recorded implementation identities and per-task output. The Code Search rows describe the source revisions recorded by each benchmark, not a new measurement of the current release.

Shared Java comparison

The primary comparison uses the same 61 public queries and relevance annotations over pinned Gson, Apache Commons Lang, and Jackson Databind revisions.

No row wins every dimension. On these 61 queries, Code Search has the highest NDCG and MRR; Semble has slightly higher Recall, lower query latency, and a smaller payload; BM25 has the lowest query latency and payload.

NDCG@10 also changes by query type:

The shared Java methodology and machine-readable results record exact tool commits, model revisions, repository revisions, adapter definitions, p95 values, per-query rows, and reproduction commands.

Multilingual diagnostic

The second comparison uses 30 fixed pre-fix tasks from eight public repositories and eight languages. Each language has only three or four tasks, so the heatmap locates weaknesses in this sample; it does not establish broad language support.

BM25 and ripgrep return whole files in this diagnostic, which explains their large payloads. Probe returns AST blocks; its file order was identical across five repeated queries on 25 of 30 tasks. See the multilingual methodology and per-language results for the adapter definitions and complete records.

Both datasets are retrieval-only development data that have already been inspected. They do not generate patches, run project tests, or run agents. Native result units also differ—evidence spans, chunks, graph nodes, AST blocks, and whole files—so setup and payload describe the recorded adapters, not every capability of each product. Held-out product claims still require untouched tasks, executable patch tests, and repeated agent runs.

How Code Search fits

No retrieval approach is best for every query. The first four rows below generate candidates or index source relationships. Code Search builds on lexical candidates, applies lightweight structural inference, and organizes selected source as task evidence. It is an evidence layer, not a same-level replacement for every retrieval method.

These approaches complement each other. Exact search remains the right first tool for a known literal. Semantic retrieval helps with conceptual discovery, while a structural index is better for deep relation queries. Code Search focuses on deciding which implementation, test, configuration, registration, comparison, or repair site belongs in the evidence set for the task.

How it works

The engine incrementally caches source terms and structural boundaries, splits identifiers, expands engineering aliases, scores paths and content, identifies task-specific structural obligations, contrasts related sibling methods when a callback path is missing expected behavior, detects missing subscriber-initialization and dependency edges, focuses long methods into query-aware windows, expands selected anchors, and packs non-duplicate evidence into a ranked result set. The differentiating thesis is:

Return not only similar code, but the evidence subgraph required to answer the engineering task.

The retrieval path is a transparent lexical/structural engine. For an exact symbol-only query, a compact window is promoted only when the literal symbol appears directly after a common declaration keyword. The result remains a medium-confidence exact-text anchor, not a parser-verified definition. Task roles and structural conclusions are rule-based. Stronger parsers and independent held-out validation remain future work.

Documentation

• Retrieval approaches
• Product thesis and proposed architecture
• MVP implementation
• Evaluation plan
• Evaluation harness
• Reproducible benchmark entry points
• Public release E2E smoke test
• Shared Java retrieval comparison
• Multilingual development benchmark
• Task-evidence fixture
• PyPI release process

Current gaps

• P0, public held-out validation: publish at least 30 untouched, license-compatible tasks with executable patch tests and repeated model runs.
• P1, retrieval quality: close the long-query ranking gaps surfaced by the multilingual diagnostic, and add stronger AST/symbol parsers.
• P1, onboarding validation: expand beyond the seven current user-level Agent Skill destinations only when another integration has a real discovery path and automated coverage. Consider MCP only if a resident index or structured tool discovery provides a measured benefit over CLI invocation.
• P2, distribution: ship signed standalone binaries.

Status and independent implementation

This is a testable experimental MVP, not a production release. The public development benchmark measures retrieval, while the deterministic fixtures and tests cover output behavior and package quality. None of them proves held-out retrieval superiority or executable patch success. The implementation and bundled Agent Skill are independently designed around the task-evidence workflow.

License

Licensed under the Apache License 2.0.