Dirgrep

dirgrep

dirgrep is a CLI tool to perform grep operations directory-wise.

Written in Go, it leverages the language built-in concurrency feature to execute grep operations concurrently on all files within a directory (even recursively!).

Install

In order to install dirgrep there are three ways:

1. Using go: if you already have go 1.23+ installed in your environment, installing dirgrep is effortless

go install github.com/AstraBert/dirgrep

1. Using npm:

npm install @cle-does-things/dirgrep

1. Downloading the executable from the releases page: you can download it directly from the GitHub repository or, if you do not want to leave your terminal, you can use curl:

curl -L -o dirgrep https://github.com/AstraBert/dirgrep/releases/download//dirgrep___.tar.gz ## e.g. https://github.com/AstraBert/dirgrep/releases/download/0.1.1/dirgrep_0.1.1_darwin_amd64.tar.gz

# make sure the downloaded binary is executable (not needed for Windows)
chmod +x dirgrep

In this last case, be careful to specify your OS (supported: linux, windows, macos) and your processor type (supported: amd, arm).

Usage

dirgrep [command] [flags]

Commands

• mcp: Start an MCP server over stdio transport

Flags

• -c, --context int

Number of characters of context to include around matches. Defaults to 0.

• -d, --directory string

Directory to search for the pattern. Defaults to the current working directory (".").

• -h, --help

Show the help message and exit.

• -p, --pattern string

Pattern to search for within the given directory. Required.

• -r, --recursive

Search files recursively. Defaults to false.

• -s, --skip strings

One or more sub-directories to skip. Can be specified multiple times or as comma-separated values. Defaults to an empty list.

• -x, --no-pretty

Deactivate pretty-printing for the matches to the console.

Examples

# search for 'package main' in the current directory, excluding .git and .gitub
dirgrep --pattern 'package main' --skip .git --skip .github --recursive
# search in a specific directory non-recursively
dirgrep --pattern 'root' --directory cmd/
# add a context of 200 charachters around the match
dirgrep --pattern '202\d' --context 200
# deactivate pretty-printing
dirgrep --pattern '202\d' --context 100 --no-pretty
# start MCP server
dirgrep mcp

Benchmark

> Python 3.9+ is required for running the benchmark

You can run the [benchmark for dirgrep](./benchmark/) (VS other tools) using:

cd benchmark
bash run.sh

This will:

• Create 1 million files (approx. 4GB) under the benchmark/files directory, containing three random lines each.
• Start ./dirgrep search for the pattern A password forgot itself at dawn. (one of the random lines), redirecting the standard output to benchmark_dirgrep.txt
• Start grep search recursively for the same pattern, redirecting the standard output to benchmark_grep.txt
• Start ripgrep search recursively for the same pattern, redirecting the standard output to benchmark_ripgrep.txt
• Once the program is finished, you will have the time output for it.

In the latest run, dirgrep VS other tools performed as follows:

| Metric | dirgrep | grep | ripgrep | Description | |------------|-------------|-------------|-------------|--------------------------------------| | user | 35.58s | 1.53s | 2.06s | CPU time in user mode (program code) | | system | 454.60s | 27.67s | 38.44s | CPU time in system mode (kernel ops) | | cpu | 1166% | 17% | 312% | CPU utilization across all cores | | total | 42.037s | 166.34s | 12.940s | Actual elapsed wall-clock time |

Contributing

We welcome contributions! Please read our [Contributing Guide](./CONTRIBUTING.md) to get started.

License

This project is licensed under the [MIT License](./LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AstraBert
• Source: AstraBert/dirgrep
• License: MIT

Install and usage instructions live in the source repository linked above.