Metadata-Version: 2.4
Name: code-search-cli
Version: 0.3.0
Summary: Task-aware code search with compact, auditable evidence for coding agents
Author: Code Search contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://code-search.quguai.cc/
Project-URL: Documentation, https://code-search.quguai.cc/
Project-URL: Repository, https://github.com/quguai/code-search
Project-URL: Issues, https://github.com/quguai/code-search/issues
Project-URL: Changelog, https://github.com/quguai/code-search/releases
Keywords: code-search,code-retrieval,coding-agents,agent-skills,cli,codex
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

<div align="center">
  <a href="https://github.com/quguai/code-search">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-dark.png" />
      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-light.png" />
      <img src="https://raw.githubusercontent.com/quguai/code-search/main/assets/brand-light.png" alt="CodeSearch" width="600" />
    </picture>
  </a>
  <p><strong>Task-aware code search for coding agents</strong></p>
  <p>Explainable evidence. Scoped context. No runtime model.</p>
</div>

<p align="center">
  <a href="https://github.com/quguai/code-search/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/quguai/code-search/ci.yml?branch=main&amp;style=flat-square" /></a>
  <a href="https://pypi.org/project/code-search-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/code-search-cli?style=flat-square" /></a>
  <a href="https://github.com/quguai/code-search/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/github/license/quguai/code-search?style=flat-square" /></a>
  <img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&amp;logo=python&amp;logoColor=white" />
  <img alt="Agent Skill installers for seven agents" src="https://img.shields.io/badge/Agent_Skills-7_targets-5B47D6?style=flat-square" />
  <img alt="Experimental status" src="https://img.shields.io/badge/status-experimental-D97706?style=flat-square" />
</p>

<p align="center">
  <strong>English</strong> | <a href="https://github.com/quguai/code-search/blob/main/README.zh-CN.md">简体中文</a> | <a href="https://github.com/quguai/code-search/blob/main/README.ja-JP.md">日本語</a> | <a href="https://github.com/quguai/code-search/blob/main/README.ko-KR.md">한국어</a> | <a href="https://github.com/quguai/code-search/blob/main/README.ru-RU.md">Русский</a>
</p>

---

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

```bash
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

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

### Retrieve evidence for a task

```bash
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

```bash
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.

| Synthetic case | Code Search task-evidence schema | Neutral flat-result schema |
|---|---|---|
| Python callback using `emit` | `missing-behavior` + `comparison` with reasons, provenance, and confidence | source spans + score |
| TypeScript callback using `dispatchEvent` | `missing-behavior` + `comparison` with reasons, provenance, and confidence | source spans + score |
| Java/Spring-style startup lifecycle | two explicit `required repair site` responsibilities + subscriber `registration` | source spans + score |

From a source checkout, run the synthetic fixtures:

```bash
uv run python scripts/showcase_evidence.py
```

The [task-evidence contract](https://github.com/quguai/code-search/blob/main/benchmarks/evidence-showcase/README.md)
documents the fixture and its
[generated output](https://github.com/quguai/code-search/blob/main/benchmarks/evidence-showcase/RESULTS.md).
This is a regression check, not a held-out quality benchmark or a patch-success claim.

## CLI

Read a historical revision:

```bash
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:

```bash
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:

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

Manage the optional Agent Skill:

```bash
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:

| `--target` | User-level destination |
|---|---|
| `codex` | `$CODEX_HOME/skills/code-search/` when set; otherwise `~/.agents/skills/code-search/` |
| `claude-code` | `$CLAUDE_CONFIG_DIR/skills/code-search/` when set; otherwise `~/.claude/skills/code-search/` |
| `cursor` | `~/.cursor/skills/code-search/` |
| `gemini` | `$GEMINI_CLI_HOME/.gemini/skills/code-search/` when set; otherwise `~/.gemini/skills/code-search/` |
| `opencode` | `$OPENCODE_CONFIG_DIR/skills/code-search/` when set; otherwise `${XDG_CONFIG_HOME:-~/.config}/opencode/skills/code-search/` |
| `github-copilot` | `$COPILOT_HOME/skills/code-search/` when set; otherwise `~/.copilot/skills/code-search/` |
| `kiro` | `~/.kiro/skills/code-search/` |

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:

```bash
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](https://github.com/quguai/code-search),
[Semble](https://github.com/MinishLab/semble),
[code-review-graph](https://github.com/tirth8205/code-review-graph), BM25,
[Probe](https://github.com/probelabs/probe), and
[ripgrep](https://github.com/BurntSushi/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.

![Six retrieval methods compared across quality, coverage, latency, and payload](https://raw.githubusercontent.com/quguai/code-search/main/assets/benchmark-quality-speed.png)

| Method | NDCG@10 | Recall@10 | MRR@10 | Setup | Query p50 / p95 | Top-10 payload |
|---|---:|---:|---:|---:|---:|---:|
| Code Search | **0.8638** | 0.9672 | **0.8463** | 1.809 s | 15.69 / 50.11 ms | 3,058 tok |
| Semble | 0.8250 | **0.9754** | 0.7852 | 1.550 s | 5.83 / 22.41 ms | 1,803 tok |
| code-review-graph | 0.7634 | 0.8607 | 0.7670 | 23.744 s | 103.55 / 230.24 ms | 16,161 tok |
| BM25 | 0.5686 | 0.7623 | 0.5398 | 1.449 s | **1.47 / 3.16 ms** | **1,752 tok** |
| Probe | 0.2271 | 0.4754 | 0.1649 | — | 586.82 / 952.48 ms | 4,295 tok |
| ripgrep | 0.1977 | 0.2377 | 0.1904 | — | 32.52 / 61.40 ms | 28,605 tok |

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:

| Query type | Tasks | Code Search | Semble | code-review-graph | BM25 | Probe | ripgrep |
|---|---:|---:|---:|---:|---:|---:|---:|
| Conceptual | 33 | **0.8550** | 0.7869 | 0.7607 | 0.4855 | 0.1794 | 0.0000 |
| Architecture | 12 | **0.7204** | 0.7068 | 0.4877 | 0.5819 | 0.3044 | 0.0000 |
| Symbol | 16 | 0.9895 | **0.9923** | 0.9758 | 0.7301 | 0.2678 | 0.7539 |

The [shared Java methodology and machine-readable results](https://github.com/quguai/code-search/tree/main/benchmarks/shared-java)
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.

![NDCG, Recall, and MRR by language for six retrieval methods](https://raw.githubusercontent.com/quguai/code-search/main/assets/benchmark-multilingual.png)

| Method | NDCG@10 | Recall@10 | MRR@10 | Warm p50 | Payload p50 |
|---|---:|---:|---:|---:|---:|
| Code Search | 0.5026 | 0.7311 | 0.4520 | 18.5 ms | 4,816 tok |
| Semble | **0.5620** | 0.6700 | **0.5609** | 13.5 ms | 1,750 tok |
| code-review-graph | 0.3603 | 0.3800 | 0.3944 | 69.7 ms | **734 tok** |
| BM25 | 0.4973 | **0.7644** | 0.4663 | **0.9 ms** | 70,558 tok |
| Probe | 0.3084 | 0.6133 | 0.2380 | 1,262.0 ms | 6,982 tok |
| ripgrep | 0.3954 | 0.7200 | 0.3009 | 473.0 ms | 100,974 tok |

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](https://github.com/quguai/code-search/tree/main/benchmarks/multilingual-30)
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.

| Approach | Typical question | Typical output | Main trade-off |
|---|---|---|---|
| Exact text or regex search | Where does this identifier, error string, or literal occur? | Matching lines or small windows | Fast and deterministic, but depends on exact wording and does not infer missing behavior on its own |
| Lexical or full-text retrieval | Which files share this vocabulary or path context? | Ranked files or spans with lexical scores | Explainable and model-free, but weaker on paraphrases and cross-file relationships |
| Embedding or hybrid chunk retrieval | Which code expresses this natural-language concept? | Semantically ranked code chunks | Designed to recover conceptual matches, but adds model and index cost; chunk boundaries may omit surrounding evidence |
| Structural graph or symbol index | Where is this symbol defined, referenced, or related? | Definitions, references, relations, or traversals | Strong for explicit relations, but depends on parser coverage, edge accuracy, and a correct starting anchor |
| Code Search task-evidence bundle | Which evidence belongs in this bug, change, or review? | De-duplicated source spans with task roles, reasons, provenance, confidence, and payload | Task-role inference is lightweight and rule-based, and the result is not a compiler-grade program graph |

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](https://github.com/quguai/code-search/blob/main/docs/retrieval-approaches.md)
- [Product thesis and proposed architecture](https://github.com/quguai/code-search/blob/main/docs/product-thesis.md)
- [MVP implementation](https://github.com/quguai/code-search/blob/main/docs/implementation.md)
- [Evaluation plan](https://github.com/quguai/code-search/blob/main/docs/evaluation-plan.md)
- [Evaluation harness](https://github.com/quguai/code-search/blob/main/docs/benchmarking.md)
- [Reproducible benchmark entry points](https://github.com/quguai/code-search/tree/main/benchmarks)
- [Public release E2E smoke test](https://github.com/quguai/code-search/blob/main/scripts/e2e_smoke.py)
- [Shared Java retrieval comparison](https://github.com/quguai/code-search/tree/main/benchmarks/shared-java)
- [Multilingual development benchmark](https://github.com/quguai/code-search/tree/main/benchmarks/multilingual-30)
- [Task-evidence fixture](https://github.com/quguai/code-search/blob/main/benchmarks/evidence-showcase/README.md)
- [PyPI release process](https://github.com/quguai/code-search/blob/main/docs/releasing.md)

## 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](https://github.com/quguai/code-search/blob/main/LICENSE).
