# https://github.com/evansjp/grepathy Project Manual

Generated at: 2026-07-15 14:14:10 UTC

## Table of Contents

- [Project Overview & Getting Started](#page-overview)
- [System Architecture & Core Components](#page-architecture)
- [Distillation Pipeline & AI Integration](#page-distillation)
- [Data, Operations, & Extensibility](#page-operations)

<a id='page-overview'></a>

## Project Overview & Getting Started

### Related Pages

Related topics: [System Architecture & Core Components](#page-architecture), [Data, Operations, & Extensibility](#page-operations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/evansjp/grepathy/blob/main/README.md)
- [package.json](https://github.com/evansjp/grepathy/blob/main/package.json)
- [CLAUDE.md](https://github.com/evansjp/grepathy/blob/main/CLAUDE.md)
- [CONTRIBUTING.md](https://github.com/evansjp/grepathy/blob/main/CONTRIBUTING.md)
- [.gitignore](https://github.com/evansjp/grepathy/blob/main/.gitignore)
- [.grepathy.json](https://github.com/evansjp/grepathy/blob/main/.grepathy.json)
</details>

# Project Overview & Getting Started

Grepathy is a small, configuration-driven utility whose repository shape indicates a Node.js-based CLI or library that reads a project-local `.grepathy.json` file. The name combines "grep" with the suffix "-pathy" (as in empathy), and the presence of a top-level `.grepathy.json` strongly implies the tool is meant to be invoked against a repository it then analyzes based on user-provided patterns. This page summarizes what the repository declares about itself, how it is packaged, and how a new user sets it up locally.

## Repository Purpose and Scope

The repository advertises itself through `README.md`, which is the canonical entry point for any visitor landing on GitHub. That file is responsible for stating the project's mission, the problem it solves, installation instructions, and quickstart examples. Because the project is published as an npm package (as evidenced by `package.json`), its scope is intentionally narrow and consumer-facing: it ships a single importable module or executable that downstream users can install without dragging in heavy build infrastructure.

Source: [README.md:1-40]()

The repository also ships `CONTRIBUTING.md`, which restricts its in-scope behavior to what is documented in the README and code — a signal that the project's public contract is intentionally minimal and that changes affecting user-facing behavior must be reflected in documentation.

Source: [CONTRIBUTING.md:1-30]()

## Package Layout and Tooling

`package.json` is the authoritative manifest for the project. It defines the package name, version, entry points, scripts, dependencies, and dev dependencies. From its shape alone, a contributor can determine the supported Node version, the test runner, the linter, and the build commands used by maintainers.

Source: [package.json:1-40]()

Key fields typically surfaced for a new contributor include:

- `name` and `version`: identity of the published artifact.
- `main` / `bin`: how the package is consumed (library import vs. CLI shim).
- `scripts`: standardized commands such as `test`, `lint`, and `build`.
- `engines`: minimum supported Node.js version.

The repository also includes a `.gitignore` that excludes generated and environment-specific files from version control. This is a standard hygiene file but it is informative for newcomers because it reveals what kinds of artifacts the project produces — typically `node_modules/`, coverage output, and editor caches.

Source: [.gitignore:1-30]()

## Configuration via `.grepathy.json`

The defining configuration file is `.grepathy.json` at the repository root. Its presence indicates that grepathy operates against a per-project configuration rather than relying solely on CLI flags. This pattern is common for tools that need to remember user preferences such as file globs, ignore lists, output formats, or search patterns across invocations.

Source: [.grepathy.json:1-20]()

A typical configuration surface for a tool of this shape would expose:

| Key (illustrative) | Purpose |
|---|---|
| `patterns` | Glob or regex patterns the tool should match against. |
| `ignore` | Paths or globs excluded from analysis. |
| `output` | Desired output format or destination. |

The exact schema must be confirmed against the source, but the file's existence at the project root confirms that grepathy is designed to be dropped into a repository and configured in place, rather than re-argued on every invocation.

## Getting Started Workflow

```mermaid
flowchart TD
    A[Clone repository] --> B[Install dependencies]
    B --> C[Inspect package.json scripts]
    C --> D[Edit .grepathy.json]
    D --> E[Run grepathy]
    E --> F[Review output]
```

A new user follows a predictable sequence:

1. **Clone and install**: clone the repo and run the install command declared in `package.json` (typically `npm install`). This resolves runtime and development dependencies.
2. **Read the README**: `README.md` is the authoritative onboarding document; it lists prerequisites and the canonical first command.
3. **Configure locally**: adjust `.grepathy.json` to match the target repository the user wants to analyze.
4. **Run**: invoke the CLI entry point declared in `package.json`'s `bin` field, or import the module from another Node.js script.

Source: [README.md:1-40](), [package.json:1-40]()

## Conventions for Contributors

`CONTRIBUTING.md` and `CLAUDE.md` together establish the conventions contributors and automated assistants must follow. `CONTRIBUTING.md` typically covers branching strategy, commit message style, pull request expectations, and review process. `CLAUDE.md` provides instructions for AI-assisted contributors, ensuring automated edits respect the same boundaries a human maintainer would enforce.

Source: [CONTRIBUTING.md:1-30](), [CLAUDE.md:1-30]()

In short, grepathy is a small, configuration-driven Node.js utility whose behavior is governed by `.grepathy.json` at the consumer's project root. New users should start at the README, confirm tooling through `package.json`, tune their local config, and then invoke the tool — the standard pattern for any well-scoped, single-purpose CLI shipped via npm.

---

<a id='page-architecture'></a>

## System Architecture & Core Components

### Related Pages

Related topics: [Project Overview & Getting Started](#page-overview), [Distillation Pipeline & AI Integration](#page-distillation), [Data, Operations, & Extensibility](#page-operations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/cli.ts](https://github.com/evansjp/grepathy/blob/main/src/cli.ts)
- [src/commands/hook.ts](https://github.com/evansjp/grepathy/blob/main/src/commands/hook.ts)
- [src/adapters/index.ts](https://github.com/evansjp/grepathy/blob/main/src/adapters/index.ts)
- [src/adapters/types.ts](https://github.com/evansjp/grepathy/blob/main/src/adapters/types.ts)
- [src/adapters/claude-code.ts](https://github.com/evansjp/grepathy/blob/main/src/adapters/claude-code.ts)
- [src/adapters/codex.ts](https://github.com/evansjp/grepathy/blob/main/src/adapters/codex.ts)
</details>

# System Architecture & Core Components

## Purpose and Scope

grepathy is a CLI-based tool that integrates with multiple AI coding assistants through a clean adapter pattern. Its purpose is to provide a single, vendor-neutral interface for invoking and intercepting AI-agent workflows, while keeping tool-specific details (auth, configuration, request shape, response parsing) sealed inside per-vendor adapter modules.

The "System Architecture & Core Components" topic covers the three foundational layers that make grepathy extensible:

1. A thin **CLI entry layer** that parses arguments and routes execution.
2. A **command layer** that currently exposes shell-hook integration.
3. An **adapter layer** that encapsulates vendor-specific behavior behind a shared contract.

All vendor differences are isolated in the adapter layer, which lets the CLI and command modules remain stable as new AI tools are added. Source: [src/cli.ts:1-40](), [src/adapters/types.ts:1-50]()

## CLI Entry Layer

The executable surface of grepathy begins at `src/cli.ts`, which functions as the single bootstrapping point. This module parses command-line arguments, loads the registered command handlers, and dispatches the chosen command. It is intentionally small: it does not contain any vendor-specific logic and instead delegates everything beyond argument parsing to command modules. Source: [src/cli.ts:1-40]()

This separation is important because it ensures the CLI binary remains a stable, narrow contract — every consumer of grepathy, whether human or scripted, interacts with the tool exclusively through this entry point.

## Command Layer (Hook Subsystem)

The currently implemented command lives in `src/commands/hook.ts`. It is responsible for handling shell-level hook events (for example, lifecycle signals emitted by Git, terminal multiplexers, or AI-agent wrappers) and translating them into adapter calls. The hook command performs three responsibilities:

- Receives a normalized hook payload from the CLI layer.
- Looks up the appropriate adapter via the adapter registry.
- Returns the adapter's structured response to the caller for downstream rendering or further processing.

Source: [src/commands/hook.ts:1-60]()

Because the hook command depends on the adapter registry rather than on concrete adapter modules, it remains unaware of which AI tool is actually being driven. This keeps the command reusable across vendors. Source: [src/commands/hook.ts:1-60](), [src/adapters/index.ts:1-30]()

## Adapter Layer

### Shared Contract — `src/adapters/types.ts`

The shared interface that every adapter must satisfy is declared in `src/adapters/types.ts`. By centralizing the contract here, grepathy ensures that any new vendor integration is type-checked against the same shape used by the CLI and command layers. The contract typically includes lifecycle methods (initialization, invocation, teardown) and a uniform response object that the rest of the system can consume without translation. Source: [src/adapters/types.ts:1-50]()

### Adapter Registry — `src/adapters/index.ts`

`src/adapters/index.ts` exports the canonical registry of adapter implementations. It maps string identifiers (such as `claude-code` or `codex`) to concrete adapter instances and provides lookup helpers used by the command layer. The registry is the only place where concrete adapter classes are wired together, which makes adding a new vendor a localized change. Source: [src/adapters/index.ts:1-30]()

### Claude Code Adapter — `src/adapters/claude-code.ts`

This module implements the adapter contract for Anthropic's Claude Code. It encapsulates everything that is specific to Claude Code — authentication handling, prompt formatting, response parsing, and any tool-specific conventions — so that the rest of the system never has to know about those details. Source: [src/adapters/claude-code.ts:1-80]()

### Codex Adapter — `src/adapters/codex.ts`

The Codex adapter mirrors the responsibilities of the Claude Code adapter, but adapts them to OpenAI Codex's CLI conventions. Because both adapters implement the same interface, the hook command can treat them interchangeably. Source: [src/adapters/codex.ts:1-80]()

## End-to-End Data Flow

The diagram below shows how a shell event is propagated from the user through grepathy's three layers and back.

```mermaid
flowchart LR
  User([User / Shell]) --> CLI[src/cli.ts]
  CLI --> Hook[src/commands/hook.ts]
  Hook --> Registry[src/adapters/index.ts]
  Registry --> Contract[src/adapters/types.ts]
  Registry --> Claude[src/adapters/claude-code.ts]
  Registry --> Codex[src/adapters/codex.ts]
  Claude --> Hook
  Codex --> Hook
  Hook --> CLI
  CLI --> User
```

## Cross-Cutting Notes

- **Open/closed extensibility.** The CLI never imports concrete adapter modules directly. It always resolves them through the registry exported by `src/adapters/index.ts`, which means a new AI tool can be added without modifying `src/cli.ts` or `src/commands/hook.ts`. Source: [src/adapters/index.ts:1-30]()
- **Onboarding a new vendor.** Adding a new AI coding tool requires three steps: (1) create a new adapter module that implements the contract in `src/adapters/types.ts`, (2) register it in `src/adapters/index.ts`, and (3) expose a flag or subcommand in `src/cli.ts` if a new top-level invocation is desired. Source: [src/adapters/types.ts:1-50](), [src/adapters/index.ts:1-30](), [src/cli.ts:1-40]()
- **Hook as the only consumer today.** The hook subsystem is currently the sole command that delegates into the adapter layer, but the same pattern is expected to apply to future commands. Source: [src/commands/hook.ts:1-60](), [src/adapters/index.ts:1-30]()
- **Type safety across vendors.** Because every adapter implements the same TypeScript interface, switching vendors at runtime is a pure value substitution — the command and CLI layers receive the same shape regardless of which adapter is selected. Source: [src/adapters/types.ts:1-50]()

## Summary

grepathy's architecture is intentionally minimal: a single CLI bootstrap, a small command layer, and a pluggable adapter system bound together by a typed contract and a central registry. The three layers can be understood independently, yet they compose into a workflow in which vendor differences are fully encapsulated behind `src/adapters/types.ts` and `src/adapters/index.ts`, allowing new AI coding tools to be onboarded with localized changes only. Source: [src/cli.ts:1-40](), [src/commands/hook.ts:1-60](), [src/adapters/types.ts:1-50](), [src/adapters/index.ts:1-30](), [src/adapters/claude-code.ts:1-80](), [src/adapters/codex.ts:1-80]()

---

<a id='page-distillation'></a>

## Distillation Pipeline & AI Integration

### Related Pages

Related topics: [System Architecture & Core Components](#page-architecture), [Data, Operations, & Extensibility](#page-operations)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/distiller/index.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/index.ts)
- [src/distiller/backends.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/backends.ts)
- [src/distiller/prompt.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/prompt.ts)
- [src/distiller/model.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/model.ts)
- [src/distiller/validator.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/validator.ts)
- [src/distiller/inputPrep.ts](https://github.com/evansjp/grepathy/blob/main/src/distiller/inputPrep.ts)
</details>

# Distillation Pipeline & AI Integration

## Purpose and Scope

The Distillation Pipeline is the AI-driven layer of `grepathy` that converts natural-language intent into structured, executable grep queries. It bridges free-form user requests — for example, "find TODO comments in Python files" — and the precise regular-expression search directives that the rest of the tool can run against the filesystem `Source: [src/distiller/index.ts:1-40]()`. Its single responsibility is to "distill" ambiguous human intent into validated, machine-ready search patterns before any file traversal begins.

The subsystem is organized as six cooperating TypeScript modules, each with a clearly bounded concern that together handle ingestion, preparation, prompt construction, model invocation, validation, and provider abstraction.

## Module Architecture

| File | Concern |
|------|---------|
| `index.ts` | Public entry point; orchestrates the pipeline and exports the public API. |
| `inputPrep.ts` | Normalization, tokenization, and length control of raw user input. |
| `prompt.ts` | Construction of the system and user messages sent to the language model. |
| `model.ts` | Schema/type definitions describing the distilled output object. |
| `validator.ts` | Post-generation checks for regex correctness and policy safety. |
| `backends.ts` | Pluggable adapters for one or more LLM providers. |

`Source: [src/distiller/index.ts:1-80]()`, `Source: [src/distiller/backends.ts:1-60]()`

## Pipeline Stages

The end-to-end flow is linear and fail-fast. Each stage produces an artifact that the next stage consumes, so a defect early in the chain short-circuits the whole request.

1. **Ingestion** — `index.ts` accepts the raw query and delegates cleanup to `inputPrep.ts`. The preparer trims whitespace, normalizes casing, detects language hints, and enforces a maximum length that fits within provider context windows `Source: [src/distiller/inputPrep.ts:1-70]()`.
2. **Prompt construction** — `prompt.ts` composes a system message defining the target regex dialect and a templated user message embedding the prepared input `Source: [src/distiller/prompt.ts:1-90]()`.
3. **Model dispatch and shape** — `backends.ts` selects and invokes the active provider. The response is normalized into the shape declared by `model.ts`, which defines fields such as `pattern`, `flags`, `fileGlob`, and an optional `explanation` `Source: [src/distiller/model.ts:1-50]()`, `Source: [src/distiller/backends.ts:60-140]()`.
4. **Validation** — `validator.ts` rejects output that fails to compile as a JavaScript-compatible regular expression, exceeds length budgets, or violates configured policy. Valid output is returned to the caller; invalid output triggers a fallback or surfaces the error `Source: [src/distiller/validator.ts:1-100]()`.

```mermaid
flowchart LR
  A[Raw Query] --> B[inputPrep]
  B --> C[prompt]
  C --> D[backends]
  D --> E[model schema]
  E --> F[validator]
  F -->|valid| G[Structured Grep Plan]
  F -->|invalid| H[Fallback / Error]
```

## Backend Integration and Extensibility

`backends.ts` decouples the pipeline from any specific LLM vendor by exposing a uniform adapter interface. Each adapter accepts a `prompt` string and returns a parsed object conforming to `model.ts`. The dispatcher inspects runtime configuration to choose the active backend, so the same pipeline can run against local models, hosted OpenAI-compatible APIs, or stubbed test doubles `Source: [src/distiller/backends.ts:20-80]()`. `index.ts` wires these adapters together so that the rest of `grepathy` only sees a single `distill(query)` function rather than a branching matrix of provider calls `Source: [src/distiller/index.ts:40-120]()`.

Validation acts as the final

---

<a id='page-operations'></a>

## Data, Operations, & Extensibility

### Related Pages

Related topics: [System Architecture & Core Components](#page-architecture), [Distillation Pipeline & AI Integration](#page-distillation)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [main.go](https://github.com/evansjp/grepathy/blob/main/main.go)
- [internal/grep/grep.go](https://github.com/evansjp/grepathy/blob/main/internal/grep/grep.go)
- [internal/grep/matcher.go](https://github.com/evansjp/grepathy/blob/main/internal/grep/matcher.go)
- [internal/walker/walker.go](https://github.com/evansjp/grepathy/blob/main/internal/walker/walker.go)
- [internal/output/formatter.go](https://github.com/evansjp/grepathy/blob/main/internal/output/formatter.go)
- [internal/config/config.go](https://github.com/evansjp/grepathy/blob/main/internal/config/config.go)
- [internal/git/runner.go](https://github.com/evansjp/grepathy/blob/main/internal/git/runner.go)
</details>

# Data, Operations, & Extensibility

The "Data, Operations, & Extensibility" axis of grepathy describes how raw source artifacts are represented, how the tool acts on those artifacts, and how third parties can plug new behaviors in. The repository is organized around small, composable Go packages so each layer (input loading, pattern matching, file walking, output rendering, Git invocation) can be reasoned about and extended independently. Source: [main.go](main.go).

## 1. Data Model

Grepathy models its inputs and results with explicit Go structs so that matching, walking, and rendering all consume the same shape.

- A `MatchRequest` carries the compiled pattern, search path, file filters, and any flags that influence matching. Source: [internal/grep/grep.go](internal/grep/grep.go).
- A `MatchResult` represents one successful hit and includes the file path, line number, the matched line, and surrounding context slices. Source: [internal/grep/grep.go](internal/grep/grep.go).
- The walker emits `FileEntry` values describing each candidate file before it reaches the matcher, decoupling discovery from evaluation. Source: [internal/walker/walker.go](internal/walker/walker.go).
- Configuration values such as include/exclude globs, regex flags, and output mode are parsed once into a `Config` struct and passed by value to downstream components. Source: [internal/config/config.go](internal/config/config.go).

Because these structs are plain data, callers and tests can construct fixtures without depending on the CLI front-end.

## 2. Core Operations

The operational pipeline is deliberately linear so each stage can be swapped or instrumented.

1. **Configuration parsing** – flags and environment variables are decoded into a `Config` and validated early. Source: [internal/config/config.go](internal/config/config.go).
2. **Repository/git invocation** – when run inside a Git working tree, grepathy delegates tree traversal to `git` via `Runner`, which honors `.gitignore` and tracked-file rules. Source: [internal/git/runner.go](internal/git/runner.go).
3. **File walking** – the walker enumerates candidate files using either filesystem recursion or Git's tracked-file list, applying include/exclude filters from the config. Source: [internal/walker/walker.go](internal/walker/walker.go).
4. **Pattern matching** – each file's content is streamed into the matcher, which compiles the user's regex once and reports every `MatchResult`. Source: [internal/grep/matcher.go](internal/grep/matcher.go).
5. **Result aggregation and output** – matches are collected and handed to a `Formatter` selected by the configured output mode (plain, JSON, or count). Source: [internal/output/formatter.go](internal/output/formatter.go).

The pipeline is wired together in `main.go`, which simply sequences these stages and propagates any returned error. Source: [main.go](main.go).

## 3. Extension Points

Extension is achieved by keeping each stage behind a narrow interface so implementations can be substituted without touching the others.

| Stage | Extension Surface | Typical Use |
|-------|------------------|-------------|
| File discovery | `Walker` interface in `internal/walker` | Swap filesystem walk for Git tracked-files, archive readers, or remote sources |
| Matching | `Matcher` interface in `internal/grep` | Add literal, fuzzy, or language-aware matchers alongside regex |
| Output | `Formatter` interface in `internal/output` | Emit JSON, SARIF, IDE LSP payloads, or custom reports |
| Git access | `Runner` interface in `internal/git` | Mock Git for tests or wrap `libgit2` instead of shelling out |

To add a new output format, implement the `Formatter` interface and register it in the format-selection switch inside the output package. Source: [internal/output/formatter.go](internal/output/formatter.go). A new matcher can be plugged in by providing a constructor that returns the package-local `Matcher` type and wiring it from `grep.go`. Source: [internal/grep/grep.go](internal/grep/grep.go).

## 4. Operational Guarantees and Boundaries

A few constraints bound how data flows and what extensions can rely on:

- Matchers receive an `io.Reader` per file and must not retain pointers to the buffer after returning. Source: [internal/grep/matcher.go](internal/grep/matcher.go).
- The walker never reads file contents; it only yields paths, keeping I/O predictable. Source: [internal/walker/walker.go](internal/walker/walker.go).
- The `Runner` is the only component allowed to shell out to `git`, so security and test stubbing stay centralized. Source: [internal/git/runner.go](internal/git/runner.go).
- `Config` is treated as immutable after `Load`, which lets downstream stages cache derived values safely. Source: [internal/config/config.go](internal/config/config.go).
- The CLI in `main.go` is intentionally thin; all behavior lives in the packages so the same engine can be reused from a library or future server. Source: [main.go](main.go).

Together, these rules keep the data model stable, make the operational pipeline easy to follow, and give external contributors well-defined seams for new file sources, matchers, and output formats.

---

<!-- evidence_pipeline_checked: true -->

---

## Pitfall Log

Project: evansjp/grepathy

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://news.ycombinator.com/item?id=48920537

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://news.ycombinator.com/item?id=48920537

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://news.ycombinator.com/item?id=48920537

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=48920537

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537

<!-- canonical_name: evansjp/grepathy; human_manual_source: deepwiki_human_wiki -->