prune

prune is a survey-first CLI for coding agents that need to inspect repositories without drowning in shell output.

Traditional commands such as find, grep, cat, and raw git diff were designed for humans who can visually scan large screens. Agents read output serially, pay for every noisy line, and often over-explore before reaching the evidence they need. prune changes the default inspection pattern: show the structure first, then drill into a bounded slice.

It is not a shell replacement. It is an information layer for repository understanding.

Why this exists

A common failure mode in coding agents is poor context acquisition:

• opening too many files before knowing where the answer likely is
• reading entire files when a 30-line slice is enough
• searching the whole repository when two likely paths would do
• treating command output as evidence even when the relevant line was never inspected
• losing the trail between “what I searched” and “why I stopped”

prune tries to make the good path easier:

survey -> search -> read
 diff  -> read
batch  -> a short visible chain when the next steps are already obvious

Core idea

prune optimizes for staged disclosure.

Human-first habit	Agent-friendly alternative
dump the tree	summarize groups, sizes, extensions, recency
grep everything	group matches by area before showing previews
cat the file	read a bounded slice from start/end/around a line
inspect raw patch	summarize changed files before reading hunks
chain shell commands	run a short visible batch of inspection steps

Every command aims to return:

• compact text by default
• --json for stable machine-readable output
• primary_target / targets for routing the next focus
• next suggestions for bounded follow-up actions
• truncation hints when output is shaped by a budget

Commands

prune survey . --budget 8
prune search 'fn main' src --file-type rs
prune search 'merge_setting|prepare_request' requests/sessions.py test_requests.py --regex
prune read src/main.rs --around 120 --lines 30
prune diff . --stat
prune batch --plan '{"steps":[{"command":"read","file":"src/main.rs","start":1,"lines":20}]}'

survey

Builds a compact map of a directory before opening files.

Useful for:

• seeing the largest or densest groups
• spotting dominant file types
• choosing where to search next

prune survey .
prune survey . --group-depth 2 --budget 12
prune survey . --sort files --json

search

Finds text or regex matches while keeping results grouped and budgeted.

Useful for:

• locating likely files without dumping every match
• searching a few likely paths together
• getting a suggested read --around <line> follow-up

prune search TODO .
prune search 'pub fn run_(survey|search|read|diff)' src/commands.rs --regex
prune search 'handler' src --group-depth 2 --preview-matches 1 --budget 5

read

Reads a bounded slice of one file.

Useful for:

• inspecting the exact region surfaced by search or diff
• reading from the start, end, or around a known line
• avoiding full-file dumps

prune read src/commands.rs
prune read src/commands.rs --start 320 --lines 40
prune read src/commands.rs --around 320 --lines 24
prune read tests/cli.rs --section end --lines 80

diff

Summarizes local changes before raw patch inspection.

Useful for:

• seeing changed files and hot hunks
• routing into read --around <line>
• checking staged vs working-tree changes

prune diff .
prune diff . --stat
prune diff . --mode staged --budget 3

batch

Runs a short JSON plan of explicit inspection steps.

Useful when the next few actions are already known, such as “read these three hinted locations”. It does not run shell commands, does not plan hidden follow-ups, and keeps every step visible.

prune batch --plan '{
  "steps": [
    {"command":"search","pattern":"merge_setting|prepare_request","paths":["requests/sessions.py","test_requests.py"],"regex":true},
    {"command":"read","file":"requests/sessions.py","start":34,"lines":30}
  ]
}'

Evaluation and self-evolution

This repository also contains an eval harness for testing whether prune actually improves agent context-gathering behavior.

The primary comparison is:

baseline: agent uses normal inspection habits
prune:    agent must inspect the repository through prune

The eval harness records whether the agent:

• reached the key file and evidence
• gathered enough context without over-reading
• used the right tool for the job
• stopped once the answer was supported
• produced a complete final answer

There is also a small self-evolve loop. The goal is not to let an agent change code aimlessly, but to give it a narrow purpose: improve prune or its immediate harness, verify the change, and leave a structured summary for the next run.

Relevant entry points:

eval/README.md          eval harness overview
eval/runners/           single-run and matrix runners
evolve/run_once.py      one self-evolve pass
docs/evolve.md          self-evolve operating guide
skills/prune/SKILL.md   agent-facing usage protocol

Current status

prune is an early local-inspection MVP.

Implemented:

• survey, search, read, diff, batch
• compact text output and --json
• machine-routable next actions
• grouped and budgeted output
• file-type filtering and regex search
• line-centered reads
• working-tree and staged diff summaries
• eval harness for baseline vs prune comparison
• self-evolve runner for small, documented improvement passes

Known limits:

• not a semantic code intelligence engine
• not a dependency graph tool
• not a build/test/log analyzer
• not a background indexer or daemon
• no precise tokenizer accounting guarantee
• eval task set is still small and should grow slowly

Install

git clone https://github.com/wowyuarm/prune
cd prune
cargo install --path .

For local development:

cargo run -- survey . --budget 8
cargo test
cargo clippy --all-targets --all-features

Documentation

Start here:

• docs/vision.md — product thesis and non-goals
• docs/usage.md — command examples and practical usage
• docs/schema.md — output contract notes
• docs/roadmap.md — priorities and guardrails
• eval/README.md — evaluation harness
• docs/evolve.md — self-evolve loop

Design guardrails

prune should stay small and honest:

• help agents look before they act
• keep evidence visible
• prefer bounded reads over dumps
• prefer better product shape over prompt hacks
• do not become a shell wrapper
• do not hide uncertainty behind compressed summaries

The goal is simple: help an agent acquire the right repository context with less noise, less wandering, and clearer stopping judgment.