scope — code intelligence for LLM agents

// the problem

agents read too much.
they understand too little.

without code intelligence, agents navigate by loading full source files. a typical refactoring task burns 8,000–12,000 tokens on navigation before writing a single line.

scope builds a local structural graph — call hierarchies, type relationships, dependency chains. agents query exactly what they need. source loads only when they're ready to edit.

// without scope — 25:1 navigation-to-edit ratio

$0.58 per task · 2.4 edits

// with scope — 12:1 navigation-to-edit ratio

$0.39 per task · 4.0 edits

↑ 32% cheaper · 67% more edits · every read counts

// see it in action

one command. complete picture.

an agent runs scope sketch and knows class structure, caller counts, and type signatures — without reading a single source file.

~/projects/api — claude code session

PaymentService class src/payments/service.ts:12–89

─────────────────────────────────────────────────────────────────────────

deps: StripeClient, UserRepository, Logger, PaymentConfig

extends: BaseService

impl: IPaymentService

methods:

processPayment (amount: Decimal, userId: string) → Promise<PaymentResult> [11 callers]

refundPayment (txId: string, reason?: string) → Promise<bool> [3 callers]

validateCard (card: CardDetails) → ValidationResult [internal]

getTransaction (id: string) → Transaction | null [2 callers]

fields:

private readonly client: StripeClient

private repo: UserRepository

private logger: Logger

// ~180 tokens · source file is 6,200 tokens

// agent reasoning — based on this output:

claude code · agent decisions claude-sonnet-4-6

✓processPayment has 11 callers — will run scope refs processPayment before touching the signature.

✓depends on StripeClient — uses the correct import without reading the imports file.

✓validateCard is internal — correctly excludes it from the public interface refactor.

✗did not read service.ts — the 6,200-token source file was never loaded. saved ~6,020 tokens on this single command.

// tokens saved vs loading source directly ~6,020 tokens

// command reference

every command has a purpose.

designed for agents. terse, labelled, consistent. every output is structured for immediate action.

scope sketch

<symbol> [--json]

Compressed structural overview. Methods with caller counts, deps, type signatures. ~200 tokens instead of ~4,000.

use before: reading source or editing a class.

scope refs

<symbol> [--kind calls|imports|extends]

Every reference grouped by kind — instantiations, imports, type annotations, call sites — with file and line.

use before: changing a function signature.

scope callers

<symbol> [--depth 1-5]

Direct and transitive callers. At depth 1, shows who calls this. At depth 2+, shows the blast radius — which entry points are ultimately affected.

use before: any refactor that changes a public API.

scope find

"<intent>" [--kind function|class]

Semantic search by what code does, not what it's named. Local embeddings — no API key, works offline.

use when: navigating unfamiliar code by intent.

scope deps

<symbol> [--depth 1-3]

What does this symbol depend on? Direct imports, called functions, extended classes. Transitive with --depth.

use when: understanding what must exist first.

scope trace

<symbol> [--depth 1-3]

Show how requests reach a symbol. Traces the call graph backward from target to entry points. Use for debugging — see how a bug is triggered.

use when: checking if an internal change is safe.

scope map

[--json]

Full repository overview in ~500-1000 tokens. Entry points, core symbols ranked by caller count, architecture layers. Start here for complex tasks.

use when: starting work on an unfamiliar codebase.

scope entrypoints

[--json]

List API controllers, workers, and event handlers. Symbols with zero incoming calls — the starting points for every request flow.

use when: understanding how requests enter the system.

scope index

[--full]

Build or refresh the code index. Incremental by default. --full rebuilds from scratch.

use: once on setup. re-run after major changes.

// setup

zero infrastructure.
three steps.

everything lives in .scope/ in your project root. no server, no docker, no api key required.

install

single binary. installs from source.

cargo install --git https://github.com/rynhardt-potgieter/scope.git scope

index your project

run once. incremental from then on.

                scope init

                scope index

add to CLAUDE.md

paste the snippet. scope works for every agent session from that point.

CLAUDE.md

## Code Navigation

This project uses `scope` for structural code
navigation. Always use it before editing.

**Before editing a class or function:** `scope sketch <ClassName>` — structural overview `scope refs <symbol>` — find all callers first `scope callers <symbol>` — check blast radius
**Finding code:** `scope find "<description>"` — search by intent `scope map` — full repo overview
**Understanding flow:** `scope trace <symbol>` — how requests reach it `scope entrypoints` — list all entry points
// always scope sketch before reading source. // load source only when ready to edit.

know before
you touch.

agents read too much.
they understand too little.

one command. complete picture.

every command has a purpose.

zero infrastructure.
three steps.

install

index your project

add to CLAUDE.md

your stack, covered.

know before you touch.

agents read too much.they understand too little.

one command. complete picture.

every command has a purpose.

zero infrastructure.three steps.

install

index your project

add to CLAUDE.md

your stack, covered.

know before
you touch.

agents read too much.
they understand too little.

zero infrastructure.
three steps.