How virtual0ps/agentgrep works
1. Overall shape
- agentgrep is a single Rust CLI binary with a small library layer.
- It is intentionally daemon-free and index-free: every command works from the current workspace and returns a one-shot result packet.
2. Command entrypoint and dispatch
- src/main.rs and src/cli.rs form the front door.
- They parse CLI arguments, select one of the four modes, and route execution into the mode-specific pipeline.
- src/lib.rs likely exposes the shared internal modules so the binary and tests can reuse them.
3. Workspace boundary
- src/workspace.rs is the repository-scoping layer.
- Its job is to turn a path or current directory into a searchable workspace, so the rest of the system can operate over a bounded file tree rather than arbitrary files.
- This is the first major boundary between “user input” and “repo analysis.”
4. Exact lexical search path: grep
- src/search.rs backs the grep mode.
- This mode is for exact literal or regex matching, but unlike plain rg, it packages results by file and enclosing symbol when available.
- The key data flow here is: query → file scan → exact matches → grouped presentation.
5. Structural scanning path: outline
- src/outline.rs provides the known-file structural scan.
- It summarizes a file’s symbol-level structure without forcing a full body read.
- This is the “look at the shape first” subsystem, useful when the caller already knows which file matters.
6. Ranked file discovery: find
- src/find.rs powers the find mode.
- It takes a topic-style query and ranks candidate files using lexical and structural signals.
- Its output is not exact hits; it is a shortlist of likely-relevant files with compact reasons and file structure hints.
7. Investigation tracing: trace
- src/smart_engine.rs and src/smart_dsl.rs support the trace mode, which is the most opinionated path.
- trace combines file ranking with region-level ranking so the tool can point to likely answer locations, not just files.
- This is the main “investigation assistant” subsystem: query interpretation → candidate files → candidate regions → compact answer packet.
8. Smart query contract
- src/smart_dsl.rs is the explicit query parser for trace.
- The DSL centers on a required subject and relation, with optional support terms, kind filters, and path hints.
- This makes the relation-aware mode deterministic and scriptable rather than freeform/NLP-driven.
9. Shared context injection
- src/context.rs handles optional harness-provided retrieval context.
- This is a separate input channel from the query itself: an external harness can tell agentgrep what the caller already knows.
- That context is used to compress repeated output and bias toward novel information instead of reprinting the same structure.
10. Structure extraction as a shared capability
- src/structure.rs appears to be the common structural analysis layer used by outline, find, grep, and trace.
- Conceptually, it sits between raw file contents and mode-specific ranking/formatting.
- It is what enables symbol grouping, file outlines, and region selection without turning the tool into a full parser/indexer.
11. Output boundary
- The CLI supports multiple output surfaces: plain text, JSON, and paths-only.
- That makes the tool usable both by humans in a terminal and by automation in a harness.
- Output shaping is a core architectural concern, not an afterthought: the repo emphasizes compactness and stable packets over raw match streaming.
12. Tooling and verification
- scripts/smoke.sh and scripts/benchmark.sh are repo-level operational tools for validating behavior and measuring performance against another codebase.
- The docs in docs/ARCHITECTURE.md, docs/INTERFACE.md, docs/SMART_OUTPUT.md, and related files are part of the design contract and appear to document the intended boundaries of each subsystem.
13. What is intentionally not present
- There is no background service, persistent index, embeddings pipeline, or personalization layer.
- The architecture is built around local filesystem traversal + lexical/structural ranking + compact formatting.
- That constraint is central to the design and explains why the system is simple to run and easy to embed in agent workflows.
Main entry points: cli.rs CLI · structure.rs Structure · smart_engine.rs Trace engine · search.rs Grep
Components 18
CLI entrypoint
Argument parsing and mode dispatch.
Workspace core
Repository boundary and shared structural analysis.
- Library · Exports internal modules for the binary and tests.
src/lib.rs - Workspace · Turns a path into a bounded searchable workspace.
src/workspace.rs - Structure · Shared structural extraction used by search and ranking flows.
src/structure.rs - Context · Optional external context used to suppress repetition and bias novelty.
src/context.rs - Output · Shapes plain text, JSON, and paths-only result packets.
Search modes
Mode-specific pipelines built on shared structure extraction.
Smart trace
Relation-aware query parsing and investigation ranking.
- DSL · Parses subject/relation queries with optional filters and hints.
src/smart_dsl.rs - Trace engine · Combines file and region ranking to point at likely answer locations.
src/smart_engine.rs
Ops and docs
Benchmarks, smoke checks, and design docs.
- Smoke test · Runs quick behavioral checks for the CLI.
scripts/smoke.sh - Benchmark · Measures performance and compares behavior across runs.
scripts/benchmark.sh - Bench matrix · Runs a benchmark matrix across multiple scenarios.
scripts/benchmark_matrix.sh - Architecture · Documents the intended subsystem boundaries.
docs/ARCHITECTURE.md - Interface · Describes the user-facing command and output contract.
docs/INTERFACE.md - Smart output · Documents compact packet formatting for smart modes.
docs/SMART_OUTPUT.md
Connections 22
- main → CLI: invokes · Binary starts the CLI dispatcher.
- CLI → Workspace: opens · Commands operate inside a workspace boundary.
- CLI → Grep: grep mode · Routes exact matching into the grep pipeline.
- CLI → Outline: outline mode · Routes known-file structural scans.
- CLI → Find: find mode · Routes topic-style file ranking.
- CLI → DSL: trace mode · Parses the smart query contract for tracing.
- DSL → Trace engine: drives · Parsed subject/relation queries feed the trace engine.
- Grep → Structure: groups by · Uses structural information to group matches by symbol when available.
- Outline → Structure: extracts · Relies on shared structure extraction for file summaries.
- Find → Structure: scores with · Uses structural signals alongside lexical ones.
- Trace engine → Structure: ranks with · Uses shared structure to choose candidate files and regions.
- Trace engine → Context: biases with · Consumes optional harness context to avoid repeating known details.
- Grep → Output: formats · Emits compact result packets in the supported output surfaces.
- Outline → Output: formats · Produces structured summaries for terminal or automation use.
- Find → Output: formats · Returns ranked candidate files with concise reasons.
- Trace engine → Output: formats · Returns trace packets with file and region hints.
- Library → Workspace: shares · Exposes the workspace boundary to the binary and tests.
- Library → Structure: shares · Exposes common analysis primitives across modes.
- Smoke test → Interface: checks · Validates command behavior against the documented interface.
- Benchmark → Architecture: measures · Supports performance evaluation of the architecture.
- Bench matrix → Benchmark: extends · Runs benchmark variations across scenarios.
- Smart output → Output: specifies · Documents the compact packet contract used by smart modes.