asrch 0.1.0

Agent-safe bounded code search CLI
asrch-0.1.0 is not a library.

asrch

asrch is an agent-safe, bounded code search CLI for coding agents. It uses ripgrep as the backend, but it does not dump unbounded matches into the agent context.

The tool is designed for exploratory search in unfamiliar repositories: compare candidate terms, identify promising paths, sample representative nearby matches, and only then show focused snippets.

日本語版は README.md#日本語 を参照してください。

Requirements

  • Rust 1.85 or later
  • rg (ripgrep) available in PATH

Installation

From a local checkout:

cargo install --path .

After publication to crates.io:

cargo install asrch

Basic Workflow

When you have multiple candidate terms, do not combine them into a broad OR regular expression. Start with survey; it compares terms and paths without printing match bodies.

asrch survey \
  --term cam_coef \
  --term hyb_cam \
  --term erfc \
  --term erf \
  crates/rschem crates/libxc docs \
  --identifier

Then choose one useful term and path, and narrow step by step.

# Summarize match counts and path distribution.
asrch scout cam_coef crates/rschem --identifier

# Sample representative nearby match clusters.
asrch sample cam_coef crates/rschem/src --identifier

# Show focused snippets only after selecting an explicit file.
asrch show cam_coef crates/rschem/src/functional.rs --identifier --context 2

survey and scout use a compact TOON-style output:

survey:
  terms: 3
  paths: 2
  mode: identifier
overall[term,matches,files,dominant_path]:
  cam_coef,20,5,crates/rschem
  hyb_cam,6,2,crates/rschem
by_path:
  crates/rschem[term,matches,files,top_directory]:
    cam_coef,18,4,crates/rschem/src
    hyb_cam,6,2,crates/rschem/src
next: choose one useful term and path, then run asrch scout

Commands

Command Purpose
survey --term ... [path ...] Compare up to 12 terms across up to 8 paths without printing matches.
scout <query> [path] Summarize match counts, top directories, and top files.
sample <query> [path] Show deterministic representative nearby match clusters.
show <query> <file> Show small snippets from one explicit file.

Search Modes

Queries are fixed strings by default. Regex search is enabled only with --regex.

Option Meaning
none Fixed-string substring search
--identifier ASCII identifier-boundary search
--word Word-boundary fixed-string search
--regex Regex search for single-query commands

scout, sample, and show reject unescaped OR regexes. Use survey --term for multi-term comparison.

Safety Rules

  • Output is hard-capped at 40 lines and 8,000 bytes.
  • show accepts only an explicit file path.
  • show refuses broad matches before printing snippets.
  • sample does not accept --context; use show after narrowing.
  • Empty queries are rejected.
  • Short partial-match terms are warned about in survey.
  • .git, target, node_modules, logs, JSONL/XML files, generated files, and scratch directories are excluded by default.
  • The CLI is read-only and never modifies searched repositories.

Documentation

Development

cargo fmt --all -- --check
cargo test
cargo clippy --all-targets -- -D warnings

日本語

asrch は、コーディングエージェント向けの安全な検索 CLI です。バックエンドには ripgrep を使いますが、一致結果を無制限にエージェントのコンテキストへ流し込みません。

未知のリポジトリで探索するときに、候補語を比較し、有望なパスを絞り、代表的な近接一致だけを見てから、最後に小さな snippet を読むための道具です。

要件

  • Rust 1.85 以降
  • rg (ripgrep) が PATH に存在すること

インストール

ローカル checkout から:

cargo install --path .

crates.io 公開後:

cargo install asrch

基本ワークフロー

複数の候補語がある場合は、広い OR 正規表現へ結合しないでください。まず survey で、本文を表示せずに候補語と候補パスを比較します。

asrch survey \
  --term cam_coef \
  --term hyb_cam \
  --term erfc \
  --term erf \
  crates/rschem crates/libxc docs \
  --identifier

有効な語とパスを選び、段階的に狭めます。

# 一致件数とパス分布を確認する
asrch scout cam_coef crates/rschem --identifier

# 代表的な近接一致クラスタを少量見る
asrch sample cam_coef crates/rschem/src --identifier

# 明示したファイルだけ、短い文脈付きで見る
asrch show cam_coef crates/rschem/src/functional.rs --identifier --context 2

survey と scout は、トークン消費を抑えるため TOON に寄せた compact な形式で出力します。

コマンド

コマンド 目的
survey --term ... [path ...] 最大 12 語を最大 8 パスで比較し、一致本文は表示しない
scout <query> [path] 一致件数、上位ディレクトリ、上位ファイルを要約する
sample <query> [path] 決定的に選んだ代表的な近接一致クラスタを表示する
show <query> <file> 明示した 1 ファイルから小さな snippet を表示する

検索モード

検索語は既定で固定文字列として扱います。正規表現は --regex を明示した場合だけ使います。

オプション 意味
なし 固定文字列の部分一致
--identifier ASCII 識別子境界付き検索
--word 単語境界付き固定文字列検索
--regex 単一クエリ系コマンドの正規表現検索

scout、sample、show はエスケープされていない OR 正規表現を拒否します。複数語の比較には survey --term を使ってください。

安全性

  • 出力は最大 40 行、8,000 バイトです。
  • show は明示したファイルだけを受け付けます。
  • show は一致が広すぎる場合、snippet を表示しません。
  • sample は --context を受け付けません。文脈量を増やす場合は、絞り込み後に show を使います。
  • 空の検索語は拒否します。
  • 短い部分一致語は survey で警告します。
  • .git、target、node_modules、ログ、JSONL/XML、生成物、scratch 領域などを既定で除外します。
  • CLI は読み取り専用であり、検索対象を変更しません。

ドキュメント