Related Pages

Related topics: System Architecture & Core Components, Data, Operations, & Extensibility

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:

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

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.

Related Pages

Related topics: Project Overview & Getting Started, Distillation Pipeline & AI Integration, Data, Operations, & Extensibility

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.

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

Related Pages

Related topics: System Architecture & Core Components, Data, Operations, & Extensibility

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

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.

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

Related Pages

Related topics: System Architecture & Core Components, Distillation Pipeline & AI Integration

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.

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.
• 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.
• The walker emits FileEntry values describing each candidate file before it reaches the matcher, decoupling discovery from evaluation. Source: 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.

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

The pipeline is wired together in main.go, which simply sequences these stages and propagates any returned error. Source: 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.

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

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.
• The walker never reads file contents; it only yields paths, keeping I/O predictable. Source: 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.
• Config is treated as immutable after Load, which lets downstream stages cache derived values safely. Source: 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.

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.

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://news.ycombinator.com/item?id=48920537

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://news.ycombinator.com/item?id=48920537

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• 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
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=48920537

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48920537

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using grepathy with real data or production workflows.

• Configuration risk requires verification - GitHub / issue