# dzhng/jevgrep architecture

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

- Interactive diagram: https://gitdiagram.com/dzhng/jevgrep
- Repository: https://github.com/dzhng/jevgrep

## Overview

Jevgrep is a repository-question CLI for coding agents: a user asks about code, and the CLI returns ranked file leads and source excerpts. The core workflow filters and reads repository files, evaluates relevance through a selected provider, then selects and formats evidence for stdout. Separate commands configure credentials, install the agent skill, count eligible files, verify provider access, and clear the evaluation cache. Edges follow the README and supplied source/index references; unsampled implementation details are not assumed.

Main entry points: [`apps/cli/src/index.ts`](https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/index.ts) (Command dispatch), [`packages/core/src/retrieve.ts`](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/retrieve.ts) (Search orchestration), [`packages/core/src/evaluator.ts`](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/evaluator.ts) (Relevance evaluator), [`apps/cli/src/auth.ts`](https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/auth.ts) (Provider authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and setup"]
  node_command["Command dispatch<br/>[index.ts]"]
  node_arguments["Argument parsing<br/>[args.ts]"]
  node_authentication["Provider authentication<br/>[auth.ts]"]
  node_skill["Skill installation<br/>[skill.ts]"]
  node_output["Result rendering<br/>[render.ts]"]
end

subgraph group_retrieval["Repository retrieval"]
  node_inventory["File inventory<br/>[inventory.ts]"]
  node_retrieve["Search orchestration<br/>[retrieve.ts]"]
  node_filesystem["Filtered filesystem<br/>[filesystem.ts]"]
  node_source["Source inspection<br/>[source.ts]"]
  node_selection["Evidence selection<br/>[selection.ts]"]
  node_callcontext["Call context<br/>[call-context.ts]"]
  node_repo_context["Repository guidance lookup"]
end

subgraph group_analysis["Relevance and parsing"]
  node_evaluator["Relevance evaluator<br/>[evaluator.ts]"]
  node_requests["Evaluation requests<br/>[requests.ts]"]
  node_providers["Provider adapters<br/>[providers.ts]"]
  node_rate_budget["Rate budget<br/>[rate-budget.ts]"]
  node_parser["Language parser<br/>[parser.ts]"]
  node_parser_helpers["Parser helpers<br/>[parser-helpers.mjs]"]
  node_parser_declarations["Declaration parsing"]
  node_parser_preview["Preview parsing<br/>[parser-preview.mjs]"]
  node_parser_worker["Parser worker<br/>[parser-worker.mjs]"]
end

subgraph group_state["Local state"]
  node_cache[("Evaluation cache<br/>[cache.ts]")]
  node_storage["Config and cache paths<br/>[storage.ts]"]
end

node_user(("Developer or agent"))
node_external_provider{{"Jev-compatible provider"}}
node_agent_installer{{"Skills installer"}}

node_user -->|"runs command"| node_command
node_command -->|"parses arguments"| node_arguments
node_command -->|"starts auth"| node_authentication
node_command -->|"installs skill"| node_skill
node_command -->|"counts files"| node_inventory
node_command -->|"runs search"| node_retrieve
node_command -->|"checks provider"| node_evaluator
node_command -->|"clears cache"| node_cache
node_command -->|"renders results"| node_output
node_authentication -->|"stores credentials"| node_storage
node_authentication -->|"validates provider"| node_providers
node_skill -->|"delegates install"| node_agent_installer
node_retrieve -->|"creates reader"| node_filesystem
node_retrieve -->|"inspects source"| node_source
node_retrieve -->|"selects evidence"| node_selection
node_retrieve -->|"adds call context"| node_callcontext
node_retrieve -->|"looks up guidance"| node_repo_context
node_retrieve -->|"scores relevance"| node_evaluator
node_retrieve -->|"builds requests"| node_requests
node_inventory -->|"enumerates files"| node_filesystem
node_filesystem -->|"protects local paths"| node_storage
node_evaluator -->|"uses provider"| node_providers
node_evaluator -->|"reads and writes"| node_cache
node_evaluator -->|"controls requests"| node_rate_budget
node_evaluator -->|"sends evaluations"| node_external_provider
node_source -.->|"parses declarations"| node_parser
node_parser_worker -->|"runs helpers"| node_parser_helpers
node_parser_helpers -->|"parses declarations"| node_parser_declarations
node_parser_helpers -->|"builds previews"| node_parser_preview

click node_command "https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/index.ts"
click node_arguments "https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/args.ts"
click node_authentication "https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/auth.ts"
click node_skill "https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/skill.ts"
click node_output "https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/render.ts"
click node_inventory "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/inventory.ts"
click node_retrieve "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/retrieve.ts"
click node_filesystem "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/filesystem.ts"
click node_source "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/source.ts"
click node_selection "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/selection.ts"
click node_callcontext "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/call-context.ts"
click node_repo_context "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/repository-context.ts"
click node_evaluator "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/evaluator.ts"
click node_requests "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/requests.ts"
click node_providers "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/providers.ts"
click node_rate_budget "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/rate-budget.ts"
click node_parser "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser.ts"
click node_parser_helpers "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser-helpers.mjs"
click node_parser_declarations "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser-declarations.mjs"
click node_parser_preview "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser-preview.mjs"
click node_parser_worker "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser-worker.mjs"
click node_cache "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/cache.ts"
click node_storage "https://github.com/dzhng/jevgrep/blob/main/packages/core/src/storage.ts"

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_command,node_arguments,node_authentication,node_skill,node_output toneBlue
class node_inventory,node_retrieve,node_filesystem,node_source,node_selection,node_callcontext,node_repo_context toneAmber
class node_evaluator,node_requests,node_providers,node_rate_budget,node_parser,node_parser_helpers,node_parser_declarations,node_parser_preview,node_parser_worker toneMint
class node_cache,node_storage toneRose
class node_user,node_external_provider,node_agent_installer toneIndigo
```

## Components

### CLI and setup

- [Command dispatch](https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/index.ts): `apps/cli/src/index.ts`
- [Argument parsing](https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/args.ts): `apps/cli/src/args.ts`
- [Provider authentication](https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/auth.ts): `apps/cli/src/auth.ts`
- [Skill installation](https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/skill.ts): `apps/cli/src/skill.ts`
- [Result rendering](https://github.com/dzhng/jevgrep/blob/main/apps/cli/src/render.ts): `apps/cli/src/render.ts`

### Repository retrieval

- [File inventory](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/inventory.ts): `packages/core/src/inventory.ts`
- [Search orchestration](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/retrieve.ts): `packages/core/src/retrieve.ts`
- [Filtered filesystem](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/filesystem.ts): `packages/core/src/filesystem.ts`
- [Source inspection](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/source.ts): `packages/core/src/source.ts`
- [Evidence selection](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/selection.ts): `packages/core/src/selection.ts`
- [Call context](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/call-context.ts): `packages/core/src/call-context.ts`
- [Repository guidance lookup](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/repository-context.ts): `packages/core/src/repository-context.ts`

### Relevance and parsing

- [Relevance evaluator](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/evaluator.ts): `packages/core/src/evaluator.ts`
- [Evaluation requests](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/requests.ts): `packages/core/src/requests.ts`
- [Provider adapters](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/providers.ts): `packages/core/src/providers.ts`
- [Rate budget](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/rate-budget.ts): `packages/core/src/rate-budget.ts`
- [Language parser](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser.ts): `packages/core/src/parser.ts`
- [Parser helpers](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser-helpers.mjs): `packages/core/src/parser-helpers.mjs`
- [Declaration parsing](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser-declarations.mjs): `packages/core/src/parser-declarations.mjs`
- [Preview parsing](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser-preview.mjs): `packages/core/src/parser-preview.mjs`
- [Parser worker](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/parser-worker.mjs): `packages/core/src/parser-worker.mjs`

### Local state

- [Evaluation cache](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/cache.ts): `packages/core/src/cache.ts`
- [Config and cache paths](https://github.com/dzhng/jevgrep/blob/main/packages/core/src/storage.ts): `packages/core/src/storage.ts`

### Other components

- **Developer or agent**
- **Jev-compatible provider**
- **Skills installer**

## Connections

- Developer or agent → Command dispatch: runs command (evidence: `README.md`)
- Command dispatch → Argument parsing: parses arguments (evidence: `apps/cli/src/index.ts`)
- Command dispatch → Provider authentication: starts auth (evidence: `apps/cli/src/index.ts`)
- Command dispatch → Skill installation: installs skill (evidence: `apps/cli/src/index.ts`)
- Command dispatch → File inventory: counts files (evidence: `apps/cli/src/index.ts`)
- Command dispatch → Search orchestration: runs search (evidence: `apps/cli/src/index.ts`)
- Command dispatch → Relevance evaluator: checks provider (evidence: `apps/cli/src/index.ts`)
- Command dispatch → Evaluation cache: clears cache (evidence: `apps/cli/src/index.ts`)
- Command dispatch → Result rendering: renders results (evidence: `apps/cli/src/index.ts`)
- Provider authentication → Config and cache paths: stores credentials (evidence: `apps/cli/src/auth.ts`)
- Provider authentication → Provider adapters: validates provider (evidence: `apps/cli/src/auth.ts`)
- Skill installation → Skills installer: delegates install (evidence: `README.md`)
- Search orchestration → Filtered filesystem: creates reader (evidence: `packages/core/src/retrieve.ts`)
- Search orchestration → Source inspection: inspects source (evidence: `packages/core/src/retrieve.ts`)
- Search orchestration → Evidence selection: selects evidence (evidence: `packages/core/src/retrieve.ts`)
- Search orchestration → Call context: adds call context (evidence: `packages/core/src/retrieve.ts`)
- Search orchestration → Repository guidance lookup: looks up guidance (evidence: `packages/core/src/retrieve.ts`)
- Search orchestration → Relevance evaluator: scores relevance (evidence: `packages/core/src/retrieve.ts`)
- Search orchestration → Evaluation requests: builds requests (evidence: `packages/core/src/retrieve.ts`)
- File inventory → Filtered filesystem: enumerates files (evidence: `README.md`)
- Filtered filesystem → Config and cache paths: protects local paths (evidence: `packages/core/src/filesystem.ts`)
- Relevance evaluator → Provider adapters: uses provider (evidence: `packages/core/src/evaluator.ts`)
- Relevance evaluator → Evaluation cache: reads and writes (evidence: `packages/core/src/evaluator.ts`)
- Relevance evaluator → Rate budget: controls requests (evidence: `packages/core/src/evaluator.ts`)
- Relevance evaluator → Jev-compatible provider: sends evaluations (evidence: `README.md`)
- Source inspection → Language parser: parses declarations
- Parser worker → Parser helpers: runs helpers (evidence: `packages/core/src/parser-worker.mjs`)
- Parser helpers → Declaration parsing: parses declarations (evidence: `packages/core/src/parser-helpers.mjs`)
- Parser helpers → Preview parsing: builds previews (evidence: `packages/core/src/parser-helpers.mjs`)
