// Blog / orientation cost

How to stop coding agents from repeatedly scanning the whole repository

The point is not to make agents read less source. The point is to stop spending context on the same broad orientation crawl every session.

technical blog Pain, optimization, and cost reduction Published May 24, 2026 Updated May 25, 2026

View .knowledge hub Inspect GitHub

// direct answer

Short answer

Repeated repo crawls are reduced by replacing the broad first pass with a maintained routing bundle, then spending the saved attention on current source, tests, evidence, and any stale or suspect areas.

Reduce cold-start orientation work while keeping source review strict where it matters.

// the problem

Every new session scans the repository again

Every new session repeats the same repo walk: README, package files, source tree, tests, docs, and old summaries.

That crawl is sometimes useful, but it is also noisy. It does not tell the agent which notes are stale or which module summaries are only heuristic.

The waste is not only tokens. It is attention spent rediscovering project shape instead of checking the code path that matters.

// focused start

Start from a maintained task map

Replace the broad first pass with a routing bundle as the first operational read.

Use the bundle to find target modules, trust status, critical files, and maintenance reports.

Then spend the available time and context where it matters: current code, tests, evidence, and any area that needs review.

// concrete example

A cautious measurement method

Measure the baseline cold-start path first: the files an agent tends to read before it knows where the task belongs.

Measurement template: Initial files read: __. Task-map files read: __. Estimated context: __. Required source/test reads: __. Conclusion: __.

Then compare it with a focused path: routing_bundle.json, the relevant module summary, current source/tests, and evidence for the task.

Keep the claim narrow. A local smoke estimate can show orientation reduction, but it should not be sold as universal token savings for every repository.

// files you can inspect

Files behind the focused starting path

Some repository-specific files appear only after setup or a health check. Run the documented setup workflow to create routing, confidence, freshness, search, metrics, and PR summary outputs.

Focused starting point CREATED DURING SETUP

`.knowledge/maintenance/routing_bundle.json`

The bundle replaces an aimless first crawl with a smaller first-read path.

Use it for

Choosing module and source paths
Finding stale and suspect knowledge

Do not use it for

Avoiding source review
Claiming exact token savings

Local metrics CREATED AFTER A HEALTH CHECK

`.knowledge/metrics/`

Metrics make orientation claims inspectable instead of anecdotal.

Use it for

Comparing local runs
Tracking health and context estimates

Do not use it for

Publishing universal benchmarks
Comparing unrelated repos without caveats

Benchmark notes INCLUDED IN THE DOWNLOAD

`.knowledge/docs/metrics-benchmarks.md`

Benchmark docs explain the limits of the estimator and the scope of the result.

Use it for

Documenting methodology
Keeping claims cautious

Do not use it for

Guaranteeing production savings

PR summary CREATED AFTER A HEALTH CHECK

`.knowledge/maintenance/pr_summary.md`

The PR summary turns trust and repair state into reviewable output.

Use it for

Review handoff
Checking what changed since the last run

Do not use it for

Replacing reviewer judgment

// commands to try

Commands and expected checks

node .knowledge/tools/collect-metrics.js

what it does: Local health, token estimates, file counts, and graph metrics are collected.
where to look: .knowledge/metrics/ and .knowledge/docs/metrics-benchmarks.md
before you run it: Treat estimates as local smoke data unless validated with a tokenizer-specific benchmark.

node .knowledge/tools/flow.js release --no-color

what it does: The task map and related repository context are rebuilt and checked together.
where to look: .knowledge/maintenance/quality_report.json

Before / after files and checks

First-orientation path

01 Before: README -> manifests -> source tree -> tests -> docs -> old summaries

02 After: routing_bundle.json -> target module -> source/tests -> evidence

03 Synthetic SaaS-shape fixture: 14 orientation files -> 1 routing bundle

04 Published smoke result: ~22% in the published synthetic SaaS-shape smoke fixture

// practical reference

How to interpret the measurements

Use metrics to improve workflow, not to overclaim precision.
Metric	Use it for	Do not claim
Orientation file count	Compare a broad scan with a task-map path.	Exact effort saved for every agent.
Estimated context	Spot rough direction and regression risk.	Tokenizer-verified universal savings.
.knowledge health check	Check repository context before handoff.	Proof the product code is correct.

// quick FAQ

FAQ

Does .knowledge guarantee lower token use?

No. It is designed to reduce aimless first-orientation work. Actual token impact depends on repository size, task type, model behavior, and how much source must be re-read.

Should an agent read fewer tests after routing is added?

No. Routing should help the agent find the right tests faster. It should not reduce test review for behavior-changing work.

// next step

When repeated repository scans become visible cost

Measure the broad scan, start from a task map, and keep the claim narrow: less aimless orientation, more targeted source review.

Read the hub Read metrics benchmarks See the Inspector