reposcout

RepoScout

Use RepoScout to gather evidence before reading a repository broadly, or to read an explicitly known definition under a shared output budget. Ordinary scouting and context reports retain body-free facts, rankings and confidence gaps. The coding agent decides which source is needed and which validations the task requires.

Start safely

• Target the narrowest path that covers the task. Run one scan at a time, retain the cache, and

keep results on stdout unless the user requests an artifact.

• When several related focus paths are already known, pass every path to one context-planning

invocation with repeated --focus flags. They then share one token budget and file limit; do not request a separate full-budget plan for each known focus.

• Use --profile safe for an unfamiliar or untrusted checkout. It ignores repository-owned

configuration and applies conservative resource guardrails.

Never start reposcout daemon, a frontend, or another long-running process unless the user explicitly authorizes it.

Choose the smallest start

On Unix, if a file and symbol or line are already known and its source is needed, use reposcout read directly; load the focused source-query guidance below. If the exact complete small span is already known and no snapshot, hash or coverage evidence is needed, use a targeted native read. Do not repeat unchanged source already available in context. Optional --outline is not a required first step. When the entry point is unknown, use lexical find only if its declaration candidates answer the next question. Known definitions can share a plan; known error logs can seed context. Use the matching focused guidance below and preserve snapshot/hash identity on follow-up reads.

For a known comparison, start with bounded reposcout changes when the next decision needs changed definitions; request --source only for bodies needed by that decision. The change-analysis guidance describes this route and optional broader report integration.

For compact agent scouting, start with:

reposcout --agent-summary <path>

This JSON-only view defaults to the agent profile, caps each ranking and context tier, and keeps the complete document under 16 KiB. Read coverage and omission counters before treating absence as evidence. For a focused or change-seeded plan, first check context.outline_only.entries for explicit seeds that exceed the body budget, then read context.direct_evidence; inspect expand_if_needed only when the direct files do not answer the next decision. An unseeded context plan has no direct evidence by design; its expansion entries are only a bounded orientation shortlist.

Use ordinary -f json --summary only when the task needs a detailed graph, impact, review, baseline, directory block, or a predicate the native view does not expose. Then discard unrelated fields before stdout enters model context. Use a targeted compact projection, not bare jq (which only pretty-prints the full payload), and preserve the producer's status with pipefail:

set -o pipefail

reposcout -f json --summary --profile agent <path> \
  | jq -c '{
      coverage: (.diagnostics | {
        discovered_files, analyzed_files, unsupported_files,
        unreadable_files, walker_errors,
        scan_truncated: (.scan_truncated // false)
      }),
      assessment: .summary.assessment,
      scope: {basis: .work_scope.basis, inventory: .work_scope.inventory}
    }'

Use a bare reposcout only when the exact zero-argument/default behavior is requested. A terminal receives a human table, but captured or redirected stdout receives full JSON; read the repository scouting guidance before interpreting that default.

Load focused guidance

Read only the references required by the current task. Load more than one only when the task spans those workflows.

Require configuration consent

Never create or modify a global/project reposcout.toml, .reposcout.toml, or .reposcoutignore without explicit user approval. Before requesting approval, explain the exact keys or patterns, affected paths/analyzers, precedence, and inventory-versus-health consequence. Reading existing configuration and running reposcout config are non-mutating.

Report conclusions

State the scanned target, profile, and diff scope. Lead with relevant coverage gaps, then report only the findings, reading order, tests, and dependents that affect the task. Include totals, omissions, and unavailable signals; never turn a disabled analyzer into a measured zero.

Distinguish measured facts from heuristics: runner-backed test-file selection is not measured coverage, risk is a versioned ranking, graph resolution can be partial, and compact duplicate lists are projections over retained raw findings. Do not present graph components or numeric thresholds as proof that work should be delegated or split.

Trust the CLI boundary

Use only an already-installed reposcout binary whose provenance the user trusts. The official source is gordon1210/reposcout, and official binaries come from GitHub Releases. If provenance is uncertain, stop and direct the user to the verified installation flow. Never clone, build, install, or update the CLI without explicit authorization.

Do not spend calls on routine command -v, --version, or capability preflights. Run the selected task command directly. If the shell reports that reposcout is not installed, tell the user and stop.