glep / Guides
Using glep with Claude Code
Install the glep skill and PreToolUse hook so Claude Code runs its Grep and Glob searches through the glep index instead of a full scan.
On this page
The repository ships two pieces for Claude Code, in the claude/ folder:
- A skill (
SKILL.md) that teaches the agent how to call glep through Bash. - A PreToolUse hook (
hooks/glep_redirect.py) that intercepts the built-in Grep and Glob tools and tells the agent to run the equivalent glep command instead.
First principles
- The hook never runs glep itself. It only decides whether the built-in tool may run, and if not, names the equivalent glep command. The agent then runs that command through Bash and sees exactly what ran.
- It fails open. Without
glepon the PATH, without a.glep/directory, or on input it cannot read, it allows the built-in call unchanged, so a session that does not use glep is never affected. - It translates only what has a glep equivalent. A request glep cannot honor exactly falls through to the built-in tool.
Requirements
glepon your PATH. See Installation.python3on your PATH, for the hook.- A
.glep/index in the directory Claude Code runs in. Runglep indexonce in the project root.
Install
The installer copies files into your user-scope Claude Code directory:
git clone https://github.com/velofy/glep
glep/claude/install.sh
It installs:
~/.claude/skills/glep/SKILL.md
~/.claude/hooks/glep_redirect.py
The script does not edit your settings. Add the hook to ~/.claude/settings.json yourself, merging with any hooks you already have:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Grep|Glob",
"hooks": [
{ "type": "command", "command": "python3 ~/.claude/hooks/glep_redirect.py" }
]
}
]
}
}
What the hook does
When Claude Code is about to run Grep or Glob, the hook checks two things: that glep is on the PATH, and that the session’s working directory (the payload’s cwd) contains a .glep/ directory. It does not look in parent directories. If either check fails, it allows the call unchanged. It also allows the call on malformed input.
When both checks pass, it denies the call and returns the equivalent glep command as the reason. For a case-insensitive Grep for foo bar in *.rs files:
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "This project has a glep index. Run the equivalent indexed search via Bash instead: glep -i -g '*.rs' -e 'foo bar'"
}
}
The agent then reruns the search through Bash.
Grep parameters are translated as follows:
patternbecomes-e 'pattern', always last before the path. A pattern starting with a dash, such as-> Result, works with glep 2.0.0; 0.3.1 rejects it as an unknown flag.-ibecomes-i.output_mode: files_with_matchesbecomes-l;output_mode: countbecomes-c.multilinebecomes-U.globbecomes-g,typebecomes-t.-C,-Aand-Bpass through.pathis appended as a path operand.offsetandhead_limitbecome pipes on the shown command:| tail -n +K(K is offset plus 1) first, then| head -N. Values that cannot be read as integers, or are negative, are dropped.
One case is left to the built-in tool: -n: false with output_mode set to content or left out. Grep’s results then omit line numbers, which the hook’s glep command always prints.
A Glob call becomes glep --files 'pattern', with path appended when given.
What the skill says
The skill maps Claude Code’s tools to glep commands:
- Grep pattern X:
glep -e 'X' - With a glob filter:
glep -g '*.rs' -e 'X' - Files with matches:
glep -l -e 'X' - Case-insensitive:
glep -i -e 'X' - Type filter:
glep -t rust -e 'X' - Context:
glep -C N -e 'X'(or-A N/-B N) - Count:
glep -c -e 'X' - Multiline:
glep -U -e 'X' - Glob pattern P:
glep --files 'P' - All files:
glep --files
For machine-readable results it suggests --json. Its rules:
- On first use in a project, run
glep indexonce. - Exit code 1 means no matches, not an error.
- For read-only exploration bursts, add
--ttl 5. Drop it after any file edit, or the edit may be invisible for up to 5 seconds. - If glep errors unexpectedly, fall back to the built-in Grep and Glob tools.
Test the hook
From a clone of the repository, with the glep it builds on your PATH (one case runs a dash-leading pattern, which 0.3.1 rejects):
cargo build
PATH="$PWD/target/debug:$PATH" claude/hooks/test_hook.sh
It prints hook tests: OK when every translation case passes.
Uninstall
Remove the hook entry from ~/.claude/settings.json, then delete ~/.claude/skills/glep/ and ~/.claude/hooks/glep_redirect.py.