# igrep-claude-code

> Use when setting up or operating igrep in Claude Code: bootstrap, indexing, two-stage search, dependency/usage queries, Z.AI/OpenAI-compatible API configuration, background LLM enrichment, and noise filtering for token-efficient codebase understanding.

- Author: Henrik Holkenbrink
- Repository: hholk/igrep
- Version: 20260127204929
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/hholk/igrep
- Web: https://mule.run/skillshub/@@hholk/igrep~igrep-claude-code:20260127204929

---

---
name: igrep-claude-code
description: Use when setting up or operating igrep in Claude Code: bootstrap, indexing, two-stage search, dependency/usage queries, Z.AI/OpenAI-compatible API configuration, background LLM enrichment, and noise filtering for token-efficient codebase understanding.
---

# igrep Claude Code

## Overview
Use igrep to build a fast local code index and optionally enrich it with an LLM for better titles/summaries/tags. Claude Code then uses `igrep search`, `igrep uses`, and `igrep deps` for precise, token-efficient context retrieval.

## Quick Setup (Claude Code)
1. Bootstrap deps:
   ```bash
   bash scripts/bootstrap.sh
   ```
2. Add API key if you want LLM/RLM features:
   - Put `IGREP_API_KEY` in your environment or `.env` (see `.env.example`).
3. Build the index (fast pass first; LLM enrichment can run in background):
   ```bash
   uv run igrep index-build
   ```
4. If you need the provider runtime, start it in the background (default):
   ```bash
   claude-plugin/scripts/server_up.sh
   ```

## Daily Use
- Search (default: two-stage, unlimited Stage-1):
  ```bash
  uv run igrep search "<query>"
  ```
- Usage lookup (thin lines by default):
  ```bash
  uv run igrep uses <symbol>
  ```
- Dependency lookup:
  ```bash
  uv run igrep deps <file-or-symbol>
  ```

## Token-Efficient Defaults
- Use mismatch-first to expose gaps quickly:
  ```bash
  uv run igrep search "<query>" --mismatch-only --rlm-timeout 15 --seed-limit 12
  ```
- Keep contexts thin by default; add `--context` only when needed.

## Claude Hook (Replace Grep)
To route Claude Code `Grep` tool usage through igrep, add a PreToolUse hook.
See `references/claude-hooks.md` for the ready-to-paste JSON.

## LLM Enrichment (Optional)
- Foreground (blocking):
  ```bash
  uv run igrep index-build --llm-index --llm-max-nodes 6
  ```
- Background (default when API key is set):
  ```bash
  IGREP_LLM_BACKGROUND=1 uv run igrep index-build
  ```
- Disable background:
  ```bash
  IGREP_LLM_BACKGROUND=0 uv run igrep index-build
  ```

## Provider Runtime (Non-Blocking)
The helper `claude-plugin/scripts/server_up.sh` runs in the background by
default. To keep it in the foreground:

```bash
IGREP_SERVER_BACKGROUND=0 claude-plugin/scripts/server_up.sh
```

## Noise Filtering (Project-Specific)
Enable only when it matches the repo:
```bash
export IGREP_NOISE_PREFIXES_ENABLE=1
export IGREP_NOISE_PREFIXES=".github,.claude,dist,build,vendor"
```

## References
- See `references/setup.md` for environment variables, models, and provider defaults.