# pi-lean-grep

![pi-lean-grep preview](https://raw.githubusercontent.com/RunMintOn/pi-lean-grep/main/product-image.png)

---

[**中文文档**](README-Zh.md)

---

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:**
```text
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:**
```text
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:

```text
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
```bash
pi install npm:pi-lean-grep
```

### Install for the current project only
```bash
pi install -l npm:pi-lean-grep
```

### Temporary load
```bash
pi -e npm:pi-lean-grep
```

### Local development load
```bash
pi -e ./pi-lean-grep
```

### Lower-noise test setup
```bash
pi -e ./pi-lean-grep --tools grep --no-skills --no-prompt-templates --no-context-files
```

### As a project-local extension
Put it at:
```text
.pi/extensions/pi-lean-grep/index.ts
```

---

## Tests

```bash
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.