rgk

rgk is rg plus one extra option:

rgk PATTERN --keep "natural language condition"

rg still does the fast lexical search. --keep sends the matching lines to Codex, keeps only results that satisfy the condition, and prints kept results ranked strongest first.

Without --keep, rgk execs rg directly. --help, -h, and --version show normal rg output with a short rgk section appended.

Installation

npm install -g @akuzmenko/rgk

For Pi, install the package as an extension to make Pi's bash tool expand rg commands to rgk:

pi install npm:@akuzmenko/rgk

Requirements:

• Node.js 24+
• rg on PATH
• codex on PATH, authenticated and ready to run codex exec

Usage

rgk "TODO" --keep "security-sensitive follow-up"
rgk "fetch" src --keep "network calls without timeout"
rgk "class .*Error" --keep "errors shown to end users"
echo "foo\nbar" | rgk foo --keep "the foo line"

Recommended global AGENTS.md instruction for coding agents:

- Prefer `rgk` over `rg`; it accepts the same args. When exploring with `rgk`, add `--keep '<natural language condition>'` to Codex-filter/rank matched lines into `path:line:column:text`; omit `--keep` when using bare `rg` or when you need every literal match, e.g. refactors/edits.

Recommended global AGENTS.md instruction for Pi coding agents with the rgk extension installed:

- Prefer `rg`/ripgrep for searching text in files. When exploring with `rg`, add `--keep '<natural language condition>'` (a Codex-only `rg` extension) to filter/rank matched lines into `path:line:column:text`; omit `--keep` when you need every literal match, e.g. refactors/edits.

In --keep mode, output is normalized and match-centered for agents and scripts:

path/to/file:line:column:compact matched text

Long lines are shortened around the matched span before they reach the agent context. Search semantics pass through to rg; presentation becomes plain, no-color, and line-oriented so ranking and filtering are reliable in pipes, editors, and coding-agent workflows. --keep rejects rg output modes that do not return match lines, such as count and files-with-matches modes.

Privacy

Without --keep, rgk execs rg directly and does not call Codex. With --keep, the keep condition, matched paths, and compact matched lines are sent to Codex for filtering and ranking. Narrow your rg query first when searching private or sensitive code.

Configuration

Environment variables:

Variable	Default	Description
RGK_MODEL	gpt-5.4-mini	Codex model
RGK_REASONING_EFFORT	none	Codex reasoning effort
RGK_PROMPT_MAX_BYTES	400000	Max prompt bytes per Codex request
RGK_TOTAL_PROMPT_MAX_BYTES	4000000	Max total keep prompt bytes processed
RGK_PROMPT_LINE_MAX_BYTES	600	Max matched-line bytes sent per candidate (min 4)
RGK_OUTPUT_LINE_MAX_BYTES	300	Max matched-line bytes printed per result (min 4)
RGK_CODEX_CONCURRENCY	4	Max concurrent Codex requests
RGK_CODEX_TIMEOUT_MS	300000	Codex timeout
RGK_RG_PATH	rg	ripgrep executable
RGK_CODEX_PATH	codex	Codex executable
RGK_DEBUG	unset	Set 1 or true to show Codex diagnostics

Exit codes

• 0: kept results printed
• 1: no rg matches, or no kept results
• 2: invalid usage, rg error, or Codex/filter failure

Development

pnpm install
pnpm run verify

License

MIT