asrch-0.1.1 is not a library.

asrch

asrch is a search CLI for coding agents. It is designed to prevent large search results from consuming agent context and token budgets.

See the Japanese section for the Japanese version.

Requirements

Rust 1.85 or later
rg (ripgrep) available in PATH

Installation

cargo install asrch

Codex Plugin

The CLI is published through crates.io. The Codex workflow is distributed as a plugin in this repository.

After adding this repository as a Codex plugin marketplace, install the asrch-search plugin from the plugin browser:

codex plugin marketplace add rnisi621/asrch

The marketplace catalog is .agents/plugins/marketplace.json, and the plugin bundle is plugins/asrch-search.

Basic Workflow

asrch narrows a search in stages instead of printing large amounts of matched text immediately.

survey: compare candidate terms and candidate paths.
scout: inspect the directory and file distribution of one selected term.
sample: inspect nearby match cluster ranges in one explicit file.
show: print snippets from one explicit file or context around one line. For source code, symbol tools such as Serena are normally preferred.

For source code, the expected workflow is to identify candidate files with sample and then use Serena's symbol tools instead of repeatedly calling show. asrch handles broad exploration and narrowing, Serena handles functions, types, and references, and show handles documentation, configuration, and other files that cannot be inspected as symbols.

survey and scout use a compact TOON (Token-oriented object notation)-like output.

asrch survey \
  --term AuthConfig \
  --term auth_config \
  --term load_config \
  --term token \
  src tests docs \
  --identifier

Example output:

survey:
  terms: 4
  paths: 3
  mode: identifier
overall[term,matches,files,dominant_path]:
  AuthConfig,8,3,src
  auth_config,5,2,src
  load_config,2,1,src
  token,14,6,src
by_path:
  src[term,matches,files,top_directory]:
    AuthConfig,8,3,auth
    auth_config,5,2,auth
    load_config,2,1,config
    token,10,4,auth
  tests[term,matches,files,top_directory]:
    token,4,2,auth
next: choose one useful term and path, then run asrch scout

This result suggests AuthConfig and src/auth, so the next command uses one term and one path.

asrch scout AuthConfig src/auth --identifier

Example output:

scout:
  query: AuthConfig
  path: src/auth
  mode: identifier
  matches: 8
  files: 3
top_directories[path,matches]:
  .,8
top_files[path,matches]:
  config.rs,4
  session.rs,3
  mod.rs,1
next: narrow the path, then use asrch sample

Inspect cluster ranges to select a file and line to read.

asrch sample AuthConfig src/auth/config.rs --identifier --clusters 3 --page 1

Example output:

sample: query="AuthConfig" path=src/auth/config.rs mode=identifier matches=4 files=1 clusters=2 page=1/1 selected=2
clusters[index,range,hits,first,last]:
  1,12..12,1,src/auth/config.rs:12:12,src/auth/config.rs:12:12
cluster 1 first:
-- src/auth/config.rs:12:12
    11 |
>   12 | pub struct AuthConfig {
    13 |     pub token_ttl_seconds: u64,
cluster 2 first:
-- src/auth/config.rs:44:21
    43 | impl AuthConfig {
>   44 |     pub fn from_env() -> Self {
    45 |         Self::load()

For source code, use Serena's get_symbols_overview, find_symbol, and find_referencing_symbols at this point to inspect functions and types. Use show for documentation, configuration, or files that Serena cannot handle.

asrch show AuthConfig docs/authentication.md --identifier --line 18 --context 2

Example output:

show: query="AuthConfig" file=docs/authentication.md mode=identifier matches=2 context=2
-- docs/authentication.md:18:5
    16 | ## Configuration
    17 |
>   18 | AuthConfig controls token lifetime and refresh behavior.
    19 | It is loaded during service startup.
    20 |

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> <file>`	Page through nearby match ranges and short context from one explicit file.
`show <query> <file>`	Show small snippets from one explicit file or context around one line.

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 to evaluate candidate terms before continuing with scout.

Safety Rules

The CLI is read-only and does not modify searched repositories.
Every output line is clipped to 800 bytes.
Output volume is structurally bounded:
- survey accepts at most 12 terms and 8 paths and prints counts only.
- scout prints matching-line counts for the top five directories and files in the selected path.
- sample clusters matches and prints at most 5 clusters per page. Use --page to select another page.
- show is limited to one explicit file, at most 20 matching lines, and at most 5 context lines. With --line N, only context around that line is shown.
Without --line N, show attempts to print all selected matches, but prints no snippets if there are more than 20 matching lines or the internal scan limit is reached.
sample reports each cluster's range, hit count, first match, and last match. Use show --line N --context M to inspect the middle of a long cluster.
scout, sample, and show reject queries containing an unescaped | when --regex is used.
.git, target, node_modules, logs, JSONL/XML files, generated files, and scratch directories are excluded by default.

Documentation

CLI behavior: Japanese / English
Agent skill: skills/asrch-search/SKILL.md

Development

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

日本語

asrch は、コーディングエージェント向けの安全な検索 CLI です。大量の検索結果がコンテキストへ流れることによるトークンの浪費を防ぐように設計しています。

要件

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

インストール

cargo install asrch

Codex Plugin

CLI 本体は crates.io で配布します。Codex 用の workflow は、このリポジトリ内の plugin として配布します。

このリポジトリを Codex plugin marketplace として追加した後、plugin browser から asrch-search をインストールしてください。

codex plugin marketplace add rnisi621/asrch

marketplace catalog は .agents/plugins/marketplace.json、plugin bundle は plugins/asrch-search です。

基本ワークフロー

asrch は、検索結果の本文をいきなり大量に出すのではなく、次の順序で探索範囲を狭めるための CLI です。

survey : 複数の候補語と候補パスを比較
scout : 選んだ 1 語についてディレクトリ・ファイル分布を確認
sample : 明示した 1 ファイルから近接一致クラスタの範囲を確認
show : 指定した 1 ファイルの snippet、または指定行周辺を表示（通常serena等を優先して使用）

ソースコードを読む場合、show を繰り返すより、sample で候補ファイルを見つけた後に Serena の symbol ツールへ進むことを想定しています。asrch は広い探索と候補の絞り込み、Serena は関数・型・参照の読解、show は docs や設定ファイルなど symbol 化できない対象の確認に向いています。

survey と scout は、トークン消費を抑えるため TOON (Token-oriented object notation) ライクな形式で出力します。

asrch survey \
  --term AuthConfig \
  --term auth_config \
  --term load_config \
  --term token \
  src tests docs \
  --identifier

出力例:

survey:
  terms: 4
  paths: 3
  mode: identifier
overall[term,matches,files,dominant_path]:
  AuthConfig,8,3,src
  auth_config,5,2,src
  load_config,2,1,src
  token,14,6,src
by_path:
  src[term,matches,files,top_directory]:
    AuthConfig,8,3,auth
    auth_config,5,2,auth
    load_config,2,1,config
    token,10,4,auth
  tests[term,matches,files,top_directory]:
    token,4,2,auth
next: choose one useful term and path, then run asrch scout

ここでは AuthConfig と src/auth が有望だと分かるので、単一語・単一パスに狭めます。

asrch scout AuthConfig src/auth --identifier

出力例:

scout:
  query: AuthConfig
  path: src/auth
  mode: identifier
  matches: 8
  files: 3
top_directories[path,matches]:
  .,8
top_files[path,matches]:
  config.rs,4
  session.rs,3
  mod.rs,1
next: narrow the path, then use asrch sample

近接一致クラスタの範囲だけを見て、読むべきファイルと行を決めます。

asrch sample AuthConfig src/auth/config.rs --identifier --clusters 3 --page 1

出力例:

sample: query="AuthConfig" path=src/auth/config.rs mode=identifier matches=4 files=1 clusters=2 page=1/1 selected=2
clusters[index,range,hits,first,last]:
  1,12..12,1,src/auth/config.rs:12:12,src/auth/config.rs:12:12
cluster 1 first:
-- src/auth/config.rs:12:12
    11 | 
>   12 | pub struct AuthConfig {
    13 |     pub token_ttl_seconds: u64,
cluster 2 first:
-- src/auth/config.rs:44:21
    43 | impl AuthConfig {
>   44 |     pub fn from_env() -> Self {
    45 |         Self::load()

コードファイルであれば、この段階で Serena の get_symbols_overview、find_symbol、find_referencing_symbols を使って関数・型単位で読む方が高効率です。docs、設定ファイル、または Serena が扱えないファイルでは show を使います。

asrch show AuthConfig docs/authentication.md --identifier --line 18 --context 2

出力例:

show: query="AuthConfig" file=docs/authentication.md mode=identifier matches=2 context=2
-- docs/authentication.md:18:5
    16 | ## Configuration
    17 | 
>   18 | AuthConfig controls token lifetime and refresh behavior.
    19 | It is loaded during service startup.
    20 |

コマンド

コマンド	目的
`survey --term ... [path ...]`	最大 12 語を最大 8 パスで比較し、一致本文は表示しない
`scout <query> [path]`	一致件数、上位ディレクトリ、上位ファイルを要約する
`sample <query> <file>`	明示した 1 ファイルから、近接一致クラスタの範囲と短い文脈をページ表示する
`show <query> <file>`	明示した 1 ファイルから小さな snippet、または指定行周辺を表示する

検索モード

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

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

scout、sample、show はエスケープされていない OR 正規表現を拒否します。survey --term を使って候補語の有効度を推定してから scout 以降に進む設計です。

安全性

CLI は read-only で、検索対象のリポジトリを変更しません。
すべての出力行は最大 800 バイトに切り詰めます。
出力されるテキストの量は構造的に抑えられます。
- survey では最大 12 語 / 8 パスを受け取って出現回数のみ出力します。
- scout では指定パス内の上位 5 ディレクトリ / 5 ファイルについて、一致行数を出力します。
- sample では出現箇所をクラスタリングし、最大 5 クラスタずつ出力します。別な箇所を見たいときは --page で指定可能です。
- show は明示ファイル、最大 20 一致行、最大 5 context 行で構造的に出力量を抑えます。--line N 指定時は指定行周辺だけを表示します。
show は --line N を指定しない場合全てを出力しようとします。ただし、一致が 20 行を超える場合、または内部走査上限に達した場合、snippet を表示しません。
sample は各クラスタの行範囲、ヒット数、先頭・末尾一致を表示します。長いクラスタの途中を見たい場合は、範囲内の行を show --line N --context M で開きます。
scout、sample、show は、--regex 指定時にエスケープされていない | を含む OR 正規表現を拒否します。
.git、target、node_modules、ログ、JSONL/XML、生成物、scratch 領域などを既定で除外します。

ドキュメント

CLI の挙動: 日本語 / English
Agent Skill: skills/asrch-search/SKILL.md

asrch 0.1.1

asrch

Requirements

Installation

Codex Plugin

Basic Workflow

Commands

Search Modes

Safety Rules

Documentation

Development

日本語

要件

インストール

Codex Plugin

基本ワークフロー

コマンド

検索モード

安全性

ドキュメント