# virtual0ps/agentgrep architecture

> Architecture diagram of the GitHub repository virtual0ps/agentgrep, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/virtual0ps/agentgrep
- Repository: https://github.com/virtual0ps/agentgrep

## Overview

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: [`src/cli.rs`](https://github.com/virtual0ps/agentgrep/blob/master/src/cli.rs) (CLI), [`src/structure.rs`](https://github.com/virtual0ps/agentgrep/blob/master/src/structure.rs) (Structure), [`src/smart_engine.rs`](https://github.com/virtual0ps/agentgrep/blob/master/src/smart_engine.rs) (Trace engine), [`src/search.rs`](https://github.com/virtual0ps/agentgrep/blob/master/src/search.rs) (Grep)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entrypoint"]
  node_main(("main<br/>binary entry<br/>[main.rs]"))
  node_cli["CLI<br/>arg dispatch<br/>[cli.rs]"]
end

subgraph group_core["Workspace core"]
  node_lib["Library<br/>shared modules<br/>[lib.rs]"]
  node_workspace[("Workspace<br/>repo boundary<br/>[workspace.rs]")]
  node_structure{{"Structure<br/>analysis layer<br/>[structure.rs]"}}
  node_context["Context<br/>harness input<br/>[context.rs]"]
  node_output["Output<br/>result formatting"]
end

subgraph group_modes["Search modes"]
  node_search["Grep<br/>exact search<br/>[search.rs]"]
  node_outline["Outline<br/>symbol scan<br/>[outline.rs]"]
  node_find["Find<br/>file ranking<br/>[find.rs]"]
end

subgraph group_smart["Smart trace"]
  node_smart_dsl["DSL<br/>query parser<br/>[smart_dsl.rs]"]
  node_smart_engine{{"Trace engine<br/>region ranking<br/>[smart_engine.rs]"}}
end

subgraph group_ops["Ops and docs"]
  node_smoke["Smoke test<br/>validation script<br/>[smoke.sh]"]
  node_benchmark["Benchmark<br/>perf script<br/>[benchmark.sh]"]
  node_benchmark_matrix["Bench matrix<br/>perf matrix"]
  node_arch_doc["Architecture<br/>design doc<br/>[ARCHITECTURE.md]"]
  node_interface_doc["Interface<br/>contract doc<br/>[INTERFACE.md]"]
  node_smart_output_doc["Smart output<br/>contract doc<br/>[SMART_OUTPUT.md]"]
end

node_main -->|"invokes"| node_cli
node_cli -->|"opens"| node_workspace
node_cli -->|"grep mode"| node_search
node_cli -->|"outline mode"| node_outline
node_cli -->|"find mode"| node_find
node_cli -->|"trace mode"| node_smart_dsl
node_smart_dsl -->|"drives"| node_smart_engine
node_search -->|"groups by"| node_structure
node_outline -->|"extracts"| node_structure
node_find -->|"scores with"| node_structure
node_smart_engine -->|"ranks with"| node_structure
node_smart_engine -->|"biases with"| node_context
node_search -->|"formats"| node_output
node_outline -->|"formats"| node_output
node_find -->|"formats"| node_output
node_smart_engine -->|"formats"| node_output
node_lib -->|"shares"| node_workspace
node_lib -->|"shares"| node_structure
node_smoke -->|"checks"| node_interface_doc
node_benchmark -->|"measures"| node_arch_doc
node_benchmark_matrix -->|"extends"| node_benchmark
node_smart_output_doc -.->|"specifies"| node_output

click node_main "https://github.com/virtual0ps/agentgrep/blob/master/src/main.rs"
click node_cli "https://github.com/virtual0ps/agentgrep/blob/master/src/cli.rs"
click node_lib "https://github.com/virtual0ps/agentgrep/blob/master/src/lib.rs"
click node_workspace "https://github.com/virtual0ps/agentgrep/blob/master/src/workspace.rs"
click node_structure "https://github.com/virtual0ps/agentgrep/blob/master/src/structure.rs"
click node_context "https://github.com/virtual0ps/agentgrep/blob/master/src/context.rs"
click node_search "https://github.com/virtual0ps/agentgrep/blob/master/src/search.rs"
click node_outline "https://github.com/virtual0ps/agentgrep/blob/master/src/outline.rs"
click node_find "https://github.com/virtual0ps/agentgrep/blob/master/src/find.rs"
click node_smart_dsl "https://github.com/virtual0ps/agentgrep/blob/master/src/smart_dsl.rs"
click node_smart_engine "https://github.com/virtual0ps/agentgrep/blob/master/src/smart_engine.rs"
click node_smoke "https://github.com/virtual0ps/agentgrep/blob/master/scripts/smoke.sh"
click node_benchmark "https://github.com/virtual0ps/agentgrep/blob/master/scripts/benchmark.sh"
click node_benchmark_matrix "https://github.com/virtual0ps/agentgrep/blob/master/scripts/benchmark_matrix.sh"
click node_arch_doc "https://github.com/virtual0ps/agentgrep/blob/master/docs/ARCHITECTURE.md"
click node_interface_doc "https://github.com/virtual0ps/agentgrep/blob/master/docs/INTERFACE.md"
click node_smart_output_doc "https://github.com/virtual0ps/agentgrep/blob/master/docs/SMART_OUTPUT.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli toneBlue
class node_lib,node_workspace,node_structure,node_context,node_output toneAmber
class node_search,node_outline,node_find toneMint
class node_smart_dsl,node_smart_engine toneRose
class node_smoke,node_benchmark,node_benchmark_matrix,node_arch_doc,node_interface_doc,node_smart_output_doc toneIndigo
```

## Components

### CLI entrypoint

Argument parsing and mode dispatch.

- [main](https://github.com/virtual0ps/agentgrep/blob/master/src/main.rs): binary entry · Program entrypoint that starts CLI execution. · `src/main.rs`
- [CLI](https://github.com/virtual0ps/agentgrep/blob/master/src/cli.rs): arg dispatch · Parses commands and routes into the selected mode. · `src/cli.rs`

### Workspace core

Repository boundary and shared structural analysis.

- [Library](https://github.com/virtual0ps/agentgrep/blob/master/src/lib.rs): shared modules · Exports internal modules for the binary and tests. · `src/lib.rs`
- [Workspace](https://github.com/virtual0ps/agentgrep/blob/master/src/workspace.rs): repo boundary · Turns a path into a bounded searchable workspace. · `src/workspace.rs`
- [Structure](https://github.com/virtual0ps/agentgrep/blob/master/src/structure.rs): analysis layer · Shared structural extraction used by search and ranking flows. · `src/structure.rs`
- [Context](https://github.com/virtual0ps/agentgrep/blob/master/src/context.rs): harness input · Optional external context used to suppress repetition and bias novelty. · `src/context.rs`
- **Output**: result formatting · Shapes plain text, JSON, and paths-only result packets.

### Search modes

Mode-specific pipelines built on shared structure extraction.

- [Grep](https://github.com/virtual0ps/agentgrep/blob/master/src/search.rs): exact search · Literal or regex matching with grouped file and symbol results. · `src/search.rs`
- [Outline](https://github.com/virtual0ps/agentgrep/blob/master/src/outline.rs): symbol scan · Known-file structural summary without full body traversal. · `src/outline.rs`
- [Find](https://github.com/virtual0ps/agentgrep/blob/master/src/find.rs): file ranking · Ranks likely-relevant files from a topic-style query. · `src/find.rs`

### Smart trace

Relation-aware query parsing and investigation ranking.

- [DSL](https://github.com/virtual0ps/agentgrep/blob/master/src/smart_dsl.rs): query parser · Parses subject/relation queries with optional filters and hints. · `src/smart_dsl.rs`
- [Trace engine](https://github.com/virtual0ps/agentgrep/blob/master/src/smart_engine.rs): region ranking · 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](https://github.com/virtual0ps/agentgrep/blob/master/scripts/smoke.sh): validation script · Runs quick behavioral checks for the CLI. · `scripts/smoke.sh`
- [Benchmark](https://github.com/virtual0ps/agentgrep/blob/master/scripts/benchmark.sh): perf script · Measures performance and compares behavior across runs. · `scripts/benchmark.sh`
- [Bench matrix](https://github.com/virtual0ps/agentgrep/blob/master/scripts/benchmark_matrix.sh): perf matrix · Runs a benchmark matrix across multiple scenarios. · `scripts/benchmark_matrix.sh`
- [Architecture](https://github.com/virtual0ps/agentgrep/blob/master/docs/ARCHITECTURE.md): design doc · Documents the intended subsystem boundaries. · `docs/ARCHITECTURE.md`
- [Interface](https://github.com/virtual0ps/agentgrep/blob/master/docs/INTERFACE.md): contract doc · Describes the user-facing command and output contract. · `docs/INTERFACE.md`
- [Smart output](https://github.com/virtual0ps/agentgrep/blob/master/docs/SMART_OUTPUT.md): contract doc · Documents compact packet formatting for smart modes. · `docs/SMART_OUTPUT.md`

## Connections

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