code-search-cli 0.1.0

Task-aware, evidence-oriented local code retrieval

Task-aware code search for coding agents

Accurate evidence. Smaller 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 release is an independently implemented, no-runtime-model MVP. It can read a working tree or any Git revision and returns source locations, ranking reasons, structural evidence roles, and payload statistics.

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

Quick start

Install from this checkout

The complete local flow works today:

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

code-search install installs the bundled code-search skill into Codex. Restart Codex after the command so it can discover the skill. The installer is idempotent and refuses to overwrite a locally modified skill unless --force is supplied.

After the first PyPI release, the first command becomes:

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

The PyPI distribution name (code-search-cli) and CLI entry point (code-search) are ready, but this repository has not been published to PyPI yet.

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; use code-search clean to remove the cached source snapshot and derived metadata.

What you get

• A concise, de-duplicated evidence set instead of an unbounded list of matches.
• Source locations, scores, inclusion reasons, 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 reuses unchanged source terms and structural boundaries.
• Java, Python, JavaScript, and TypeScript structural extraction with no runtime model dependency.
• A bundled Codex skill that teaches the agent when to retrieve, expand, or fall back to exact rg.

CLI

Read a historical revision:

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

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 Codex skill:

code-search install
code-search uninstall

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

Benchmarks

The primary benchmark uses NDCG@10, Recall@10, MRR@10, latency, and Top-10 payload size. The local shared subset contains 61 queries over pinned revisions of Gson, Apache Commons Lang, and Jackson Databind. Semble's published 1,251-query results are kept in a separate table and are not presented as a local rerun.

Local four-axis scorecard

Local shared Java subset

Method	NDCG@10	Recall@10	MRR@10	Warm p50	Top-10 payload
Semble	0.8250	0.9754	0.7852	4.25 ms	1,803 tok
code-review-graph	0.7634	0.8607	0.7670	103.30 ms	16,162 tok
Code Search MVP	0.7217	0.8525	0.6970	38.08 ms	2,490 tok
BM25	0.5686	0.7623	0.5398	0.72 ms	1,752 tok
probe	0.2044	0.4262	0.1453	1,764.40 ms	5,537 tok
ripgrep	0.1977	0.2377	0.1904	30.84 ms	28,605 tok

Published full-suite reference (not a local rerun)

These values are reported by Semble for its 1,251-query, 63-repository, 19-language benchmark.

Method	NDCG@10	Cold first result	Model size
CodeRankEmbed Hybrid	0.8617	57.29 s	137M
semble	0.8544	264.09 ms	16M
CodeRankEmbed	0.7648	57.29 s	137M
ColGREP	0.6925	5.87 s	16M
BM25	0.6730	262.62 ms	no model
grepai	0.5610	35.00 s	137M
probe	0.3870	207.10 ms	no model
ripgrep	0.1260	12.08 ms	no model

Regenerate the scorecard and synchronize the measured JSON values into both READMEs:

uv run --no-project --with matplotlib python scripts/publish_shared_benchmark.py

This command does not rerun the benchmark or publish a package. See the shared benchmark methodology, raw local results, and published-reference provenance.

The unit test suite creates only temporary synthetic repositories. The shared benchmark uses public, pinned Gson, Apache Commons Lang, and Jackson Databind revisions with Semble's public annotations. Machine-local and private development tasks are deliberately excluded from the public repository.

How it differs from Semble and code-review-graph

The projects overlap, but optimize different parts of an agent workflow. This comparison describes their public product shape; it is not a claim that one implementation dominates every task.

	Code Search	Semble	code-review-graph
Primary job	Assemble task-relevant, explainable evidence	Find relevant code chunks quickly	Persist code relations for review, impact, and multi-hop exploration
Result shape	Evidence bundle with source, reason, score, and structural role	Compact ranked code snippets	Graph nodes, relations, traversals, and review reports
Retrieval	Lexical and task-aware structural retrieval; no runtime model today	Code-aware chunks, semantic retrieval, BM25, fusion, and reranking	Structural graph plus full-text/vector hybrid search
Structure/history	Persistent incremental local index, lightweight expansion, and direct reads from any Git revision	Similar-chunk retrieval and cached working-tree indexes	Persistent incremental graph, callers, flows, communities, and impact analysis
Onboarding	CLI plus a bundled Codex skill installer	CLI installer for MCP, instructions, and search sub-agents across multiple agents	CLI, MCP, daemon, GitHub Action, and review workflows
Best fit today	Explainable task-evidence experiments	Fast general-purpose natural-language code search	Review and durable multi-hop structural questions

Semble still has the broader onboarding path. Its install command can configure MCP, generated instructions, or a dedicated sub-agent across several coding agents. code-search install currently installs one Codex skill. Code Search intentionally uses CLI + skill as its primary interface; an MCP server is optional, not a prerequisite.

Current advantages

• Task roles, not only similarity. Lifecycle, registration, publication, ordering, and test evidence are represented separately instead of returning only one cluster of similar chunks.
• Missing-behavior evidence. For callback tasks, structurally similar sibling methods can expose an expected publication step that is absent from the target path, instead of rewarding only code that already contains the queried behavior.
• Causal repair sets. Startup-order tasks can connect a publisher, a lazily initialized static subscriber, and the lifecycle owner whose dependency declaration must change, marking each independently actionable production file.
• Auditable evidence. Each unit includes its location, reason, score, and estimated token cost.
• Historical and no-model operation. It can inspect a Git revision without checkout and has no runtime model dependency.
• Smaller output than the current graph adapter. On the shared subset, Code Search returns a 2,490-token Top-10 payload versus 16,162 tokens for code-review-graph.

Where competitors still lead

Semble leads this MVP on ranking quality, token efficiency, warm latency, and integration breadth. code-review-graph provides deeper persistent relations, incremental graph maintenance, and review automation. Code Search does not currently claim an overall win over either project.

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.

This is currently a transparent lexical/structural baseline. Independently implemented dense retrieval and stronger parsers remain future work.

Documentation

• Competitive analysis
• Product thesis and proposed architecture
• MVP implementation
• Evaluation plan
• Open benchmark and adapters
• Shared Java benchmark
• 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: add independently implemented optional dense retrieval and stronger AST/symbol parsers.
• P1 — onboarding breadth: add safe CLI/skill installers for more coding agents. Consider MCP only if a resident index or structured tool discovery provides a measured benefit over CLI invocation.
• P2 — distribution: publish to PyPI and ship signed standalone binaries. Until publication, uv tool install code-search-cli cannot install this project from the public registry.

Status and independent implementation

This is a testable experimental MVP, not a production release. It reaches 0.7217 NDCG@10 on the 61-query shared Java subset versus Semble at 0.8250; Recall@10 is 0.8525, and warm query p50 is 38.08 ms. These public results measure retrieval, not executable patch success, and are not a held-out production claim.

The project is inspired by Semble and code-review-graph, which are used as public baselines. It does not copy or rewrite their source, tests, prompts, documentation, interfaces, or distinctive command vocabulary. The implementation and bundled Codex skill are independently designed around this project's task-evidence workflow.

License

Licensed under the Apache License 2.0. Semble and code-review-graph are independent projects; their code is not included here.