Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Opt-in Claude Code hook that requires a CodeGraph query before Grep/Glob (`codegraph gate-hook`)

Open
  • Is something wrong?
#2,313 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
node.js, typescript
Domain
cli, tooling

Research direction

Review the proposed branch and start with src/hooks/gate.ts and src/bin/codegraph.ts, comparing the new hook with the existing prompt-hook. Run tests/gate-hook.test.ts and tests/frontload-hook.test.ts, then check the README.md and CHANGELOG.md updates. Done means the opt-in hook gates searches only as described, passes its tests and type check, and leaves installation unchanged; the issue author has already implemented a branch.

Written by the indexing model from the issue text.

Description

Problem

In an indexed project, Claude Code still often answers code questions with Grep/Glob or rg/grep/find through Bash instead of CodeGraph (#1279). #1696, fixed in #1697, made the codegraph_explore schema available from the first turn with alwaysLoad, which raises the odds the model can pick it. Some users want a guarantee instead: no text search until the index has been asked once.

prompt-hook front-loads context for structural prompts, but nothing currently stops a session that skips it and greps first.

Proposal

A small, opt-in Claude Code hook next to prompt-hook: codegraph gate-hook, hidden like prompt-hook.

  • PreToolUse (Grep|Glob|Bash): in an indexed project (findNearestCodeGraphRoot), deny Grep, Glob, and Bash commands whose search head is rg/grep/find/fd/ag/ack. The deny reason tells the model to call codegraph_explore (or codegraph explore|query|node) first.
  • PostToolUse / PostToolUseFailure (mcp__.*codegraph.*|Bash): a CodeGraph MCP call or a codegraph explore|query|node|… Bash command writes a per-session marker. From then on, text search is allowed again for literals and non-code files.
  • Never in the way:
    • It is off unless the user registers it. codegraph install is not changed.
    • It does nothing outside an indexed project.
    • A pipe target such as pnpm test | grep FAIL is not a search head.
    • Searches whose target is inside node_modules are allowed, but a repo-wide search that only excludes node_modules is still gated.
    • Like prompt-hook, it never breaks a session. Any error, malformed stdin or TTY exits 0 with no output, and CODEGRAPH_NO_GATE_HOOK=1 turns it off.
  • Telemetry: gate-hook-deny and gate-hook-allow counters only, no payload content.

I have run the same behavior for a while as a local Python hook, and it reliably makes sessions query CodeGraph before searching.

Implementation ready for review

Branch on my fork: https://github.com/BGamboa13/codegraph/tree/feat/gate-hook (one commit, feat(hooks): add opt-in gate-hook to require a CodeGraph query before text search)

File Change
src/hooks/gate.ts Pure logic: runGateHook, isSearchHead, isCodegraphCommand, isIndexed
src/bin/codegraph.ts Hidden gate-hook command (kill-switch, TTY guard, stdin, telemetry), mirroring prompt-hook
__tests__/gate-hook.test.ts 12 tests
README.md Opt-in settings snippet next to the hooks docs
CHANGELOG.md [Unreleased] › New Features entry

Verification, on Node 24.21.0 with env -i and an empty HOME:

  • RED: before the module existed, the suite failed to load.
  • GREEN: vitest run __tests__/gate-hook.test.ts __tests__/frontload-hook.test.ts passes 60/60. tsc --noEmit is clean.
  • Built CLI: dist/bin/codegraph.js gate-hook prints the deny JSON for a Grep payload in an indexed temp repo, and exits 0 silently on garbage stdin.

Out of scope: installer integration (codegraph install offering the hook). It could follow in a separate PR if you want it.

Would you take this? I'll open the PR from that branch once you're OK with the approach, and adapt names or behavior to what you prefer.

Dominant language
C
Stars
73.2k
Forks
4.7k
Avg merge
2h 13m
Merged PRs (30d)
418

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from colbymchenry/codegraph

All issues in colbymchenry/codegraph

Similar issues

More C issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.