pi-lean-grep

---

中文文档

---

A lightweight upgrade for Pi’s built-in grep.

In real tests, pi-lean-grep didn’t just reduce token usage — it also noticeably lowered current context load.

Its design is intentionally simple:

• no grep rewrite
• no complex policy engine
• keep the native workflow familiar
• only add lightweight constraints where grep most easily wastes tokens

---

Real-world impact

Test model: GPT-5.4 mini

Experiment	Extension	Total Input	Cost	Context Share
1	Off	4.2k	$0.003	1.0%
1	On	2.7k	$0.002	0.5%
2	Off	7.3k	$0.006	2.2%
2	On	2.4k	$0.002	0.4%

Two things stand out:

1. Total cost goes down
   • Example: experiment 2 dropped from 7.3k -> 2.4k
2. Current context load also goes down
   • Example: experiment 2 dropped from 2.2% -> 0.4%

Input / Cost here is cumulative usage, while Context Share is the current footer snapshot. One is closer to the bill; the other is closer to current context pressure.

---

What it does

pi-lean-grep only does 3 things:

Mechanism	Behavior	Why it helps
Default limit	If limit is omitted, it becomes 20	Prevents overly large default result sets
Broad search + context guard	Broad searches with context return guidance instead of expanding results	Stops grep from turning into a bulk-reading tool
Large-result summary	Oversized results are summarized instead of dumped in full	Reduces context pollution

In one sentence:

Return a bit less by default, avoid broad context expansion, and compress oversized results first.

---

What it does not do

To stay lightweight, this extension deliberately avoids a lot of heavy behavior:

• does not rewrite grep’s search engine
• does not change the real matching semantics of regex or literal search
• does not rename the tool
• does not change the parameter schema
• does not introduce a complex strategy engine

So the core idea is:

It optimizes the cost of using grep, not grep’s search capability.

---

What changes does the AI actually see?

This extension only changes two parts of the grep tool prompt.

1) description

Built-in grep:

Search file contents for a pattern. Returns matching lines with file paths and line numbers. Respects .gitignore. Output is truncated to 100 matches or 50KB (whichever is hit first). Long lines are truncated to 500 chars.

pi-lean-grep:

Search file contents for a pattern. Returns matching lines with file paths and line numbers. Respects .gitignore. Large results may be limited or summarized, and broad searches with context may be refused to avoid large noisy result sets.

2) One extra guideline

This is added to Pi’s Guidelines: section:

Use grep to locate candidate files or lines first. Use read when surrounding code is needed. Avoid broad grep searches with context.

What stays unchanged

These parts are untouched:

• tool name: grep
• parameter schema
• promptSnippet
• underlying grep implementation

---

Installation

Install from npm

pi install npm:pi-lean-grep

Install for the current project only

pi install -l npm:pi-lean-grep

Temporary load

pi -e npm:pi-lean-grep

Local development load

pi -e ./pi-lean-grep

Lower-noise test setup

pi -e ./pi-lean-grep --tools grep --no-skills --no-prompt-templates --no-context-files

As a project-local extension

Put it at:

.pi/extensions/pi-lean-grep/index.ts

---

Tests

npm test

Current automated coverage:

• precise grep stays normal when an explicit limit is provided
• omitted limit falls back to 20
• broad search + context returns an actionable constraint message

---

v1 trade-offs

This version is not trying to be “the smartest.” It is trying to be:

• simple
• controllable
• minimally invasive to native grep behavior

If what you want is:

• lower token burn
• less context pollution
• a stronger locate-first, read-second workflow

then it should be useful.

If what you want is:

• the raw full grep output whenever possible

then this extension will feel conservative — by design.