One tree walk writes entry points, routes, data model, step signatures, and every duplicate or dead test into AGENTS.md — or JSON for your own harness. Your agent starts working at turn one, not turn 41.

What you save

Measured on a real 184-feature behave suite and one production agent run:

The map (121 KB) stays on disk to grep; a 616-byte pointer is what an agent carries. You pay a ten-second tree walk once and stop paying for rediscovery on every turn. The same walk pays for itself a second way in CI: the call graph it already wrote is what says which scenarios a commit reaches, so what to re-run after a change is a selection the map hands you rather than the whole suite every time.

What it does

One command turns a repository into a map an agent reads before it works: layers, entry points, routes, data model, contracts, tests, and where every name is defined. It reads the tree offline in seconds, and the same tree gives the same map every time.

Without it a session spends its first turns rediscovering the repo:

# turn 1   ls; find . -name "*steps*"
# turn 7   grep -rn "def click_pay" .
# turn 19  cat conftest.py; cat tox.ini; cat Makefile
# turn 34  grep -rn "BASE_URL" .
# turn 41  first line of actual work

With the map, turn 1 is the work. Measured on a real suite: forty-odd orientation turns become one --ask, and the agent reads an 849-byte pointer instead of grepping a repository it has not seen.

$ where-are-we --repo . --agent-file AGENTS.md --max-lines 200

framework map: 66 step modules, 1359 steps, 179 features, 1782 scenarios -> ./framework_map.md

AGENTS.md gets a pointer - 849 bytes, not the map:

## The framework map

`framework_map.md` (123 KB) is a generated map of this suite and the product it
tests. It is on disk on purpose: read from it, do not carry it. Ask it before
grepping the repository — it already knows.

    where-are-we --ask "the words you need"

That prints only the rows that mention those words, whole, and says how much of each section it left out. `--sections` lists what
is in it.

It has these sections:

- Where things are
- What a step may call
- Steps that overlap (14 pairs) — check whether one already does what you need
- What past runs measured (slowest first)
- …

And the map answers questions instead of being read:

$ where-are-we --ask "refund settled invoice"

## What past runs measured (slowest first)
- `billing/`
  - `refund.feature:88` Refund a settled invoice — ~252s, failed 3×
  - `credit_note.feature:12` Refund a settled invoice by credit note — ~40s
… 61 rows in this section do not mention these words

## Steps that overlap (14 pairs)
- 0.88: "the invoice is settled" (`billing_steps.py`) ≈ "an invoice has settled" (`api_steps.py`)
… 2 more matching rows; 11 rows in this section do not mention these words

An answer is whole rows, never a row cut in the middle, and it fits the limit it was given (12,000 characters for the CLI and the MCP) rather than filling it. The one exception is a continuation: where a more: handle lands on a single row longer than the whole budget, that row comes back cut and marked … (row cut to fit; N of M characters) with the handle on the row after it, because the alternative is a chain that dead-ends and strands every row behind it. Rows under one directory are printed under it once. Each section ends by saying what it left out — how many matching rows did not fit, and how many rows did not mention the words at all — so the reader knows whether to ask again with more words or to open framework_map.md.

As a Claude Code plugin

/plugin marketplace add ngavrish/where-are-we
/plugin install where-are-we@where-are-we

The plugin builds the map at session start, puts its pointer into the session's context, serves all eighteen of the map's tools over MCP (affected, ask, at, callees, callers, context, dead, defines, find, hot, impact, more, path, range, rank, reaches, sections, unreached) and ships nine skills (ask, orient, rank, readmes, spec-map, where-defined, and three for the graph answers: what-to-rerun for affected, reaches and unreached, lines-to-edit for range and path, what-to-look-at for hot and dead). It needs where-are-we on PATH (pipx install where-are-we). Details in plugin/README.md.

Everything it does, and what it is measured to save

Each row names what the tool does and what that is measured to save. Where a number exists it is cited; where none exists the row says so and names the measurement that would settle it. Numbers come from one real run unless said otherwise: a 184-feature behave suite and one production agent run (1,409 turns, $59.65), read from that run's event log. Estimates are marked as estimates.

The map itself

What an agent carries vs what it asks

The other map

Semantic answers (optional extra)

Docs the repository is missing

Ways in

See it on a repository you know: FastAPI 0.115.0 mapped.

Honesty features (not savings, guarantees)

How to measure it on your own sessions

wawe-measure reads Claude Code's own transcripts (~/.claude/projects/<project>/<session>.jsonl) and counts, per session, how many turns were spent looking around versus doing something else:

pip install where-are-we
wawe-measure --since 2026-09-01           # table, one row per session, a median row
wawe-measure --since 2026-09-01 --json    # the same rows as JSON
wawe-measure --sessions /path/to/jsonls   # a directory of transcripts instead of ~/.claude/projects

Definitions:

• A turn is one assistant message.
• A search is a Grep or Glob tool call, or a Bash call whose command starts with (after an optional cd ... &&) grep, rg, find, ls, ag, ack, fd or tree.
• A map call is a tool call whose name contains where-are-we (the MCP tools) or a Bash call whose command contains where-are-we --.
• orientation_turns is how many turns went by before the agent did something other than look around (an edit, a write, a test run): the count of turns before the first turn with a non-search, non-read, non-map tool call.

Measured 2026-09-05, wawe-measure --since 2026-09-01 against 30 sessions on this machine (one developer, several projects, not a controlled run):

Five sessions used the map at all in this window, and those five ran longer and searched more, not less: this is one developer's mixed transcripts, not a before/after comparison, and settling the "orientation replaced by one --ask" claim above needs matched sessions on the same task, one with the map and one without.

Does the budget lose answers

Every answer ask gives is cut to a byte budget. wawe-eval measures what that cut costs. It generates questions from the map itself (every declared name, every step phrase's distinctive word, the longest word of every section heading), asks each one at no budget at all to get the rows the map holds for it, and then asks it again at each budget.

First-answer recall is the share of the rows of the full answer that the budgeted answer shows before any more, averaged over the questions.

wawe-eval --map .wawe --questions 100 --budgets 350,1500,12000

Two averages are published, because they answer different questions and neither is "the" recall:

• first-answer recall is the macro average: each question's recall is computed, then those are averaged, so a question with two rows counts as much as a question with three hundred. This is the number for "what does a typical question lose".
• pooled recall is the micro average: all rows shown over all rows there were, so the biggest questions dominate. This is the number for "what share of everything the map could have said was said".
• top-5 recall is rank aware: ask ranks what it shows, so this is the share of the first five rows of the full answer that survived the cut, averaged per question. It is the number for "was the answer at the top still there".
• rows over budget is not a recall at all. It counts reference rows longer than the whole budget, which nothing can print at that budget: not the first answer, and not more, which reports such a row rather than skipping it. On the suite fixture one 446 character row does this, and it turns up in 34 of the 100 questions at 350 bytes and in none at 1500. These rows count against first-answer recall, because a reader who asked for them did not get them; they are left out of the recall the exit code asserts, because that one is about rows a handle could have returned.

Measured 2026-09-08 at 1.6.0 on the three golden fixtures with more in the build, 100 questions per fixture (fewer where the map has fewer), seed 0, built under the fixed root /tmp/wawe-eval the CI step uses:

Read the suite row at 350 bytes together: a 303 byte answer holds under half of what a typical question could have said and a tenth of every row across all of them, and about two thirds of the five rows that ranked highest. That is the shape of the cut. It is not a claim that nothing was lost.

The claim that nothing is lost belongs to more, the tool that fetches what a tail line says was left out. recall_with_handles counts the rows that fit the budget after every more: handle in the answer has been followed, and every handle in the replies after that. At 1500 bytes, the MCP server's floor, and above, it is 1.000 on every fixture: the budget cuts the first answer, the handles give all of it back. At 350 it is 0.98: an answer that small cannot always hold a row and the handle that points at the rest, so wawe-eval asserts 1.0 only from --assert-from (default 1500) and prints the smaller budgets. The CI step wawe-eval: the budget loses no row the map holds is that exit code.

How first-party a tree's calls are, and how big the graph came out

The cross-file call graph is built by name: a callee is placed in the files the walk saw declare it. call_graph_stats, a top-level key of framework_map.json, counts what that came to, per language group.

Three of its counters describe the tree that was read. sites is the callee names the walk looked at, one per function per distinct name; resolved is how many of those names some indexed file declares; ambiguous is how many several files declare. resolution_rate is resolved / sites, so it is the share of what a function calls that is first-party: Python builtins, string and dict methods and every standard library name sit in the denominator and can never leave it, and a call to a name the caller's own file declares sits in the numerator without ever becoming an edge. It is a fact about the code, not a score the graph can raise by resolving more.

Two more describe the graph that was written. edges is the cross-file edges the walk wrote, and marked how many of them carry a ? because several files declare the callee and nothing in the caller says which is meant. Those are the numbers that move when the graph gets better or worse.

All five are taken over the whole walk, before call_graph_files is cut to its 60 keys, so they measure the walk rather than the cap.

wawe-eval --map .wawe --graph          # a table
wawe-eval --map .wawe --graph --json   # the same numbers as JSON

Measured 2026-09-07 at 1.5.0, the three golden fixtures built under /tmp/graphfix and this repository, exported with git archive to /tmp/wawe-self/repo, mapped with --product none --no-semantic:

The code fixture's 0.0 is the honest reading of a repository whose only calls are into argparse and a decorator: nothing it calls is declared in it, so the graph has no edges and the rate is 0. Read the two halves together, though. The poly fixture scores 1.0 in both languages and holds one edge, because a rate of 1.0 says every name it calls is declared nearby, not that a graph was drawn; edges is the half that says a graph was drawn.

This repository's 0.2615 is what a Python tree looks like when most of what a function calls is a builtin, a method on an object or a standard library name. Of its 2818 sites, 727 are Python builtins and 847 are str, list, dict and set method names no file here declares, so 1,574 of the 2,818, more than half the denominator, is unreachable by any name graph; and 516 of the 737 first-party names never become a cross-file edge, most of them a call to a name the calling file declares itself, which the cross-file graph does not hold either. The graph under it is 214 edges, 7 of them marked.

Of the 60 keys the map keeps, 1 edge carries the mark. It is pool[kind] .add(word) in eval.py, a call on a subscript: nothing written in that file says what the container holds, so the map names both files with a def add and says it is choosing. 1.4.1 mapping this same tree writes the same 60 keys, the same 129 edges and the same 1 mark, so that count is 1.4.1's receiver rules holding rather than anything this release changed; the release before them wrote 20 marks over the same 60 keys. Some of those edges did not vanish, they were corrected: the edge hooks.py:_ensure_map used to carry for build named two candidate files, and is now build (build.py), read off mapper.py's own from ._mapper.build import build. The rest are gone from the graph rather than corrected: out.add(key) in a function that wrote out = set() two lines up is set.add, and no def add in this tree is what runs.

With pip install "where-are-we[precise]" the same numbers are computed again for the TypeScript, JavaScript and Go from a tree-sitter parse and printed beside the pattern pass:

regex vs tree-sitter, go: sites 5 vs 2 (-3), resolved 5 vs 2 (-3), rate 1.0 vs 1.0 (+0.0)
regex vs tree-sitter, ts_js: sites 3 vs 1 (-2), resolved 3 vs 1 (-2), rate 1.0 vs 1.0 (+0.0)

That is the poly fixture, and the gap is the pattern pass admitting what it over-counted: its body scan starts at the signature line, so a function's own name reads as a call, and if ( reads as one too. Without the extra the line says so and the run carries on.

--agent is the other half: the same questions asked through the Claude API twice, once with the map tools and once with grep and read over the repository, scored against answers taken from framework_map.json. It needs ANTHROPIC_API_KEY and pip install "where-are-we[eval-agent]", refuses cleanly without them, costs money, and is not run in CI. How to read the table and how to run the A/B: docs/examples/eval.md.

Command line

A CLI is the tool. pip install where-are-we gives two commands:

• where-are-we — build the map and answer from it.
• wawe-readmes — offer a repo the docs it is missing.

where-are-we --repo . --agent-file AGENTS.md   # build the map, drop a pointer
where-are-we --ask "refund settled invoice"    # answer from an existing map
where-are-we --install-hook git                # rebuild on checkout/merge/commit

Every flag is under All options below; the map also answers over MCP (--mcp) and as a library.

Where is it defined

$ where-are-we --ask "MAX_PERSISTED_FORECAST_RESULTS"

## Defined here

- `MAX_PERSISTED_FORECAST_RESULTS` — src/constants/forecastStorage.ts:31

Every name in every file the walk reaches, with its line — functions, classes, constants, types, step phrases, scenario names. A question about a name is a question about where it is, and an answer without the line sends the reader to grep for it anyway.

A name may have more than one home, and --defines names all of them with the line each one ends on:

$ where-are-we --defines charge

charge: billing/core.py:10-24 (function), legacy/pay.py:88-91 (function)

An end of ? is a declaration this map could not measure: a language the pattern table read, which has seen the line a declaration starts on and nothing that says where it stops, or a file over a megabyte, of which the parser was handed the first megabyte and so never saw the end. A guessed end would be worse than none for anyone editing by anchor. Installing the precise extra turns ? into a line for TypeScript, JavaScript, Go, Rust, Kotlin, C# and Ruby, and changes nothing about which names are declared where.

Upgrading to 1.5.0 does not add spans to the map you already have: a build skips a tree that has not moved. Run it once with --force after upgrading, or wait for the next commit. The other direction of the same index is --at, which takes the file:line a stack trace hands you and prints the definition around it, so the next step is not a Read at a guessed offset:

$ where-are-we --at billing/core.py:15

billing/core.py:10-24 charge (function)
def charge(amount):
    ...

When a name is not there, the answer says what was indexed rather than declaring the absence real. A map that overstates its reach turns "I did not look" into "it is not there".

Both of those answer "where is this name". The question before it is which names are worth knowing at all, and no amount of word matching answers that, because importance is a property of the graph rather than of the text. --rank runs PageRank over the graph the map already holds: files are nodes, an edge runs from a file that uses a name to the file that declares it, and the weight is the square root of how often. Aider's repo map is where the idea and the four multipliers come from.

$ where-are-we --rank --limit 4

0.061419466 find_text /repo/src/where_are_we/_mapper/declare.py:135
0.060390690 build /repo/src/where_are_we/_mapper/build.py:283
0.047834365 build /repo/src/where_are_we/ask.py:835
0.033650027 add /repo/src/where_are_we/eval.py:136

That is this repository's own map, unedited: the declaration scanner, the build, ask's inner budget loop and the counter wawe-eval runs over its questions. The scores are of a map that indexes this README, so editing this file moves their last digits; the order is what the CI step pins, across both supported Pythons.

Name the files you are working in and the walk is personalised on them, which turns "what matters here" into the question actually worth asking: what should I read given that I am editing this. On ask.py, find_text goes from 0.0614 to 0.0800, a third, and keeps first place, which is right: ask.py is what calls it. Personalisation shows up here as a score rather than as a swap, because the unpersonalised ranking already has it first.

$ where-are-we --rank src/where_are_we/ask.py --limit 2

0.080008437 find_text /repo/src/where_are_we/_mapper/declare.py:135
0.059723023 build /repo/src/where_are_we/_mapper/build.py:283

The same files bias --ask without changing what it found: --ask charge --files billing/ prints the billing/ rows first inside every section and the rest after them, with the section's usual tail. The handle on that tail carries the scope as one more field, so more reorders the section the same way before it continues: a scoped answer reaches every row an unscoped one does, which is the guarantee the tail is there to make. --files - reads the list on stdin, so git diff --name-only | where-are-we --ask charge --files - asks the map about the branch you are on.

Paths are compared relative to the repository root, and a prefix stops at a directory separator, so --files bill is not billing.py. A path nothing indexed matches is named on stderr rather than answered as if it were the whole repository.

Landing on a name usually raises all five questions at once, and --context answers them together:

$ where-are-we --context charge

Context for `charge`: declared, map rows, callers, callees, impact to depth 1. 12000 characters, floor shares 15/35/15/15/20 percent.

## Declared in
- charge: billing/core.py:10-24 (function)
- charge: legacy/pay.py:88-91 (function)

## What the map says
## Defined here
- `charge` — billing/core.py:10
...

## Callers
- checkout.py:pay

## Callees
- settle (billing/ledger.py)

## Impact
Impact of `charge` to depth 1. How to read it: ...
depth 1: checkout.py:pay

The shares are floors, and the budget is allocated in two passes. The first asks every block what printing all of itself would cost. The second gives each block the smaller of that and its share - 15 percent of the budget for the declarations, 35 for the map's own rows, 15 for the callers, 15 for the callees, 20 for the impact - and then hands what nobody claimed to the blocks still short, in that same order. So when the five answers together fit the budget, every one of them is printed whole; and the same name at the same budget always composes the same answer, since the needs come from the map and the order is fixed.

A block that could not print all of itself ends in … N more lines (more:ctx:...), and --more on that handle returns the rest of that block. A block that could not even be given the room to name itself and carry that handle is left out rather than printed as a count nobody can follow, and the blocks are served in order, so below about a thousand characters the first of them are printed and the rest are not there. That is why the MCP server never asks for less than 1500: under it some rows are out of reach.

The other map: the specifications

A codebase is not the only thing an agent gropes around in. The other is the tracker — the ticket, its parents, what it links to, what mentions it — and it gropes there the same way and for the same reason: no map, so it asks, and asks again.

Measured on one run of a real pipeline: sixteen tickets fetched over and over. One agent pulled fourteen neighbours to understand the task; the next agent pulled the same fourteen again, because a session cannot see another session's memory. Three were fetched three times inside a single session, since finding an answer already in a conversation costs more than asking for it fresh. Every answer then sat in the context for ever, and every later turn paid to re-read it.

$ where-are-we --specs APF-1934 --spec-cmd 'python3 fetch.py {key}'

  APF-1934 (1 so far)
  APF-1860 (2 so far)
  APF-2752 (3 so far)
spec map: 3 ticket(s) -> ./spec_map.md

This tool knows nothing about any tracker, which is the same contract as the rest of it: you hand it a command that turns a ticket key into JSON, it walks the links two hops out, and it writes spec_map.json and spec_map.md. Jira, Linear, GitHub Issues, a text file — it never finds out.

Two trackers it does not need a command for: --spec-source github builds the gh issue view {key} --repo owner/name --json ... call itself, reading owner/name off the repository's origin remote; --spec-source linear builds the GraphQL call over curl and needs LINEAR_API_KEY set. Either way --spec-cmd is filled in rather than typed.

--ask answers from both maps, because a question about a piece of work is as likely to be about what was asked for as about where the code is.

What a map leaves out, it says

Both walks are bounded, because a repository and a tracker are both graphs and a graph will hand over everything if asked. What the bound cut is named in the map itself, at the top:

## This map is incomplete

- the file walk stopped at 40000 files under /work — raise WAWE_MAX_FILES or add
  to .wawe-ignore; what is below that count is mapped and the rest is not

A limit that stops quietly produces a map that looks complete and is not, and the reader has no way to tell — which is worse than a small map, because a small map that says so can be asked to grow. An absence in a silent map reads as a fact about the codebase.

What it has that the others do not

Every other tool in this space does one of three things. Some hand the model a pile of text and hope: repomix, gitingest, code2prompt. Some hand it a search index whose answers move when the embedding model does: claude-context, chunkhound, continue's @codebase, greptile. Some hand it a live language server that has to be installed, started and kept warm per language: serena, mcp-language-server, opencode. This one treats the budget as a contract and publishes what the contract costs. An answer is whole rows or no row, never a row cut in the middle, and only a continuation asked for a row longer than its whole budget returns one cut, marked with how much was taken off. It is at or under its stated ceiling. Every section ends by counting what it left out and carrying a handle that fetches it. And wawe-eval measures, on every CI run, what the cut loses: first-answer recall, pooled recall, top-5 recall, rows longer than the budget, and recall after every handle is followed, with that last number asserted at 1.0 from 1500 characters upward.

Nobody else states that. Repomix counts tokens and never says what --compress dropped. Aider binary-searches its map into --map-tokens and says nothing about what fell out. Every vector-backed tool returns top-k and is silent about rank eleven. Graphify is the only other project that publishes reproducible retrieval numbers and tags where an edge came from, and it still needs a model for anything that is not code.

The same honesty runs through the rest. An absence names what was searched (indexed: suite 260 files) instead of asserting the thing does not exist. ## This map is incomplete names every bound that cut. A cross-file edge the map is guessing at is written charge (a.ts|c.ts)? with every candidate listed, rather than passing a choice off as a lookup. call_graph_stats publishes how much of the call tree resolved, 0.2615 on this repository at 1.5.0, instead of quietly reporting only the edges it managed to draw.

And the test suite is a first class thing here, which it is nowhere else: step phrases with their overlaps and duplicates, feature to step traceability, scenario history and slow steps read out of JUnit XML, quarantine tags, fragile locators, test-id ownership, and the product under test indexed beside the suite that drives it. It builds in one tree walk, offline, for zero tokens, byte identically, out of the standard library, and what reaches the prompt is an 849-byte pointer rather than the map.

Why install it

• The first forty turns stop repeating. The answers never change between sessions and need no model to produce, so produce them once and commit them.
• A step that exists stops being written twice. Overlapping phrases, dead phrases and uncalled page-object methods are listed by name.
• It reads a repo it has never seen. Detection is by shape, not directory name: a page object is a class that owns selectors, wherever it lives.
• It costs a tree walk. 3s on a 6k-file repo, 2.5min on a 36k-file one, cold. Deterministic — same tree, same map, no API bill.

Install

pip install where-are-we
pip install "where-are-we[semantic]"   # + local embeddings for a semantic --ask
brew tap ngavrish/tap && brew install where-are-we
curl -fsSL https://ngavrish.github.io/where-are-we/install.sh | sh

macOS, Debian 13, Ubuntu 24.04, Fedora, RHEL (any of them with Python 3.12 or newer). Or ghcr.io/ngavrish/where-are-we. The [semantic] extra adds fastembed (ONNX on CPU, no service, no database); without it --ask still answers by keyword.

Needs Python 3.12 or newer (stdlib only, no dependencies to install alongside it); 3.10 and 3.11 are no longer supported.

Output

--agent-file writes a pointer into AGENTS.md, CLAUDE.md or .cursorrules between markers. The rest of the file survives.

Why a pointer and not the map

A prompt is re-sent in full on every turn — that is what a conversation is — so anything put in one is paid for on every turn of the session, read or not.

Measured on a real run: the brief inlined whole was 253 KB, the agent carrying it took 424 turns, and the map alone came to 27.4 million tokens re-sent — a quarter of everything that run consumed, and the reason a five-hour allowance emptied in seventy-four minutes. Trimming it to an index still cost 6k a turn for a document most turns never opened.

The sections are still named in the pointer, because an agent that cannot see that a section exists goes back to grepping the repository — which is the thing this was built to end. Naming them costs two hundred tokens; carrying them costs sixty-four thousand, every turn.

A pipeline asks the map what to re-run and then respects an empty answer:

where-are-we --out .wawe --changed "$base" \
  --affected-format behave --affected-out sel.txt
[ -s sel.txt ] && xargs behave < sel.txt || echo "nothing to run"

The [ -s ] is the whole point of the file being empty rather than absent or prose: xargs handed empty input runs behave with no arguments, which is the entire suite, so a commit that reaches no scenario would run everything rather than nothing.

WAWE_EMBED_CACHE=<file> caches the semantic index's embeddings in one sqlite file keyed by model and text, so a rebuild does not recompute vectors it already has. Unset keeps the old behaviour.

What it reads

• Code (UTF-8, or UTF-16/UTF-32 with a byte order mark) — languages, entry points, make targets, npm scripts, container commands, HTTP routes and status codes, data model, module public surface, call and package graphs, cycles, unimported files, complexity hotspots, duplicate blocks.
• Runtime — queues, topics, gRPC, cron, Kubernetes probes and resources, Terraform, Pulumi, Ansible, cache keys, permissions, metrics, spans, log fields, error types, retries, timeouts, breakers, rate limits, transactions, idempotency, outbound services, installed versions from lock files.
• Contracts — OpenAPI, GraphQL, migrations, mocks, feature flags and their branch points, locale keys, pinned images, secret paths (never values).
• Decay — deprecations, coverage, docs pointing at deleted files, git history and who touches what.
• Tests — layers, entry points, callable step signatures, hooks, locators, timeouts, fixtures, tag meanings, overlapping and unused step phrases, dead page-object methods, slow scenarios from past junit.

In a pipeline

- uses: ngavrish/where-are-we@v1
  with:
    agent-file: AGENTS.md
    comment: "true"

- repo: https://github.com/ngavrish/where-are-we
  rev: v1.0.0
  hooks: [{id: where-are-we}]

What to re-run after a change

The map already knows which scenarios reach the code a commit touched. This is the pipeline that runs those and nothing else, and falls back to the whole suite whenever the answer is partial.

where-are-we --out .wawe --changed "$BASE" \
  --affected-format behave --affected-out sel.txt > affected.txt
cat affected.txt                      # the head says what was selected and why
if grep -qE 'No xrefs row names|No calls row lands on' affected.txt; then
  behave                              # the answer says it is partial
elif [ -s sel.txt ]; then
  xargs behave < sel.txt
else
  echo "nothing to run"
fi

--changed "$BASE" reads git diff --name-only "$BASE", so the pipeline passes no file names of its own; with no argument it is HEAD, which is the working tree against the last commit.

Five things that shape make true, each of which a shorter version gets wrong:

• The file is the selection and nothing else. One argument pair per line, no head, no prose, no tail, whatever the size: xargs behave < sel.txt is all the parsing a pipeline does. The head and the blocks go to stdout, which is where a person reads them.
• An empty file means run nothing, and [ -s ] is what says so. A commit that reaches no scenario writes zero bytes, and a --changed run over a tree nothing has touched writes zero bytes too and says so on stdout. Both are exit 0. GNU xargs with empty input runs the command with no arguments, and behave with no arguments is the whole suite, so a pipeline that pipes straight into xargs runs everything at the moment it should run nothing. BSD xargs, which macOS ships, runs nothing there, so the fault appears on the CI runner and not on the laptop the pipeline was written on.
• The selection is --name and only --name. One --name per affected scenario, anchored on the whole name (--name '^Pay\ with\ a\ new\ card( -- @|$)'), because --name is action="append" in behave and several of them are a union. Past a couple of hundred scenarios one --name per feature file alternates that file's affected scenarios instead, which is the same selection in fewer arguments. Nothing emits -i or --tags.
• Two scenarios of one name are one selector, and behave runs both. The block head says so on every answer that can be affected by it. That over-selects, which is the safe direction, and it is the one place the selection is not exactly the list printed above it.
• A file the graph has no row for is not "not affected". It lands in ## Unreachable from the graph, the first line says No xrefs row names N of the files given, and the selection file says nothing about it, correctly, because there is nothing to say.
• Nor is a file the map declares and no call row lands on. That one is in the map, so the answer looks complete, and it is either a thing nothing calls or a thing reached by a route no rule places (importlib.import_module plus getattr is the shape). The first line says No calls row lands on N of the files given, so this map does not know what calls them: either nothing does, or a caller the resolver could not place, and follows it with the graph's own resolution rate, which is the number that says which of the two is likelier. Both sentences are what the grep in the pipeline above reads: a partial answer is a full run.

--affected-format pytest is the same shape with node ids from pytest_tests, one per line for xargs pytest < sel.txt.

What this cannot see. affected walks xrefs rows and nothing else. A call the resolver could not place is not a row, so the scenario that reaches the change through it is not in the selection: on a test suite, where a page object is called from step modules, that is few, and on a library it is most of the graph. unreached carries the map's own resolution rate in every first line, affected carries it in the one branch where a reader cannot otherwise tell a real zero from an unplaced caller, and wawe-eval --map OUT --graph prints it per language whenever you want it. Run the whole suite on a schedule, and on every release, whatever the selection says.

What writes and what only reads

A pre-execution guard sees an argv and has to decide. This tool ships the answer instead of leaving it to guess: where-are-we --effects prints what every flag does to the disk, and a command's class is the highest class any of its flags carries.

The order is read < writes-map-dir < writes-repo < writes-config < network. --effects --json prints the same table as {"schema": "where-are-we-effects/1", "flags": {...}, "order": [...], "notes": {...}}, where notes says per class what it touches, including the answer log a read can append to. That JSON is installed beside the code as effects.json, so a guard written in something other than Python reads the file instead of the table, and reads the same caveats a human does.

--effects -- <command line> classifies one command line with this tool's own parser, running nothing:

$ where-are-we --effects -- where-are-we --out /tmp/m --ask x
writes-map-dir
--out writes-map-dir
--ask read

A flag is resolved the way argparse resolves it, so --eff is --effects and the class of an abbreviated line is the class of the line that runs.

A command line naming none of --ask, --more, --defines, --at, --context, --affected, --changed, --reaches, --unreached, --path, --rank, --callers, --callees, --context, --affected, --changed, --path, --range, --rank, --callers, --callees, --context, --affected, --changed, --path, --range, --dead, --hot, --rank, --callers, --callees, --impact, --sections, --cost, --export, --pointer, --mcp, --lsp, --init, --install-hook, --specs, --dry-run, --effects or --help builds the map into --out, so where-are-we --repo . is writes-map-dir on the strength of the build alone and says so as a build writes-map-dir line.

--dry-run prints every path the command can write, one per line, and exits without writing any of them:

$ where-are-we --repo . --install-hook git --dry-run
would write /repo/.git/hooks/post-checkout
would write /repo/.git/hooks/post-merge
would write /repo/.git/hooks/post-commit

would write when nothing is there, would replace when a file is. The paths come from the same expressions the writers use, so the preview names what the real run names; whether a listed file is then written depends on what is already in it, since a target that already says what this tool would say is left alone.

It covers every command line, not only the ones that write:

The optional semantic index adds semantic_index.json and semantic_index.npy to the same directory as the map.

Environment

Every variable the tool reads. A flag always wins over the variable it defaults from.

Each variable is read in one place, and named there. WAWE_NO_CACHE, WAWE_DEBUG_PARSES and WAWE_POINTER_MAX are read once when _mapper/state.py is imported (NO_CACHE, DEBUG_PARSES, POINTER_MAX), WAWE_MAX_FILES when _mapper/walk.py is (MAX_FILES), WAWE_VOCAB when _mapper/render.py is (VOCAB_CAP), WAWE_ASK_LOG when ask.py is (LOG_ANSWERS), the three WAWE_EMBED/WAWE_RERANK ones when semantic.py is, and the two WAWE_SPEC ones when specs.py is. So a process that sets one of those after importing the package keeps the value it started with.

The rest are read per call. Five of them are the ones a flag writes back into the environment for a later stage to pick up (AGENT_REPO, PRODUCT_SRC, RUN_DIR, RULES_REPO, RUNS_API_READ). Three more are argparse defaults, which main() evaluates when it builds the parser (SPEC_ROOTS, SPEC_FETCH_CMD, SPEC_SOURCE). The last is WAWE_JUNIT_DIRS, which a caller that builds several maps in one process sets per build.

Keeping it honest

where-are-we --init                 # starter .framework-map.json
where-are-we --docs                 # list the docs the repo lacks (--docs write to create)
where-are-we --install-hook git     # post-checkout, post-merge, post-commit
where-are-we --install-hook claude  # before the first turn of a session (agent = claude)
where-are-we --install-hook cursor  # a Cursor rule plus its MCP config
where-are-we --install-hook codex   # an AGENTS.md block plus ~/.codex/config.toml
where-are-we --install-hook gemini  # a GEMINI.md block plus .gemini/settings.json
where-are-we --diff                 # what changed since the last map

Every --install-hook kind installs as one unit: each target (the three git hooks, a rule file and its MCP config, a markdown block and its settings file) is checked before any of them is written. A target that is a symlink, not valid JSON, or not writable stops the whole install with the cause named and nothing changed; fix it and rerun, and the rest lands. Rerunning on a finished install says "already installed" and touches nothing.

Autodetection gets the shape right and the vocabulary wrong, so a repo states its own in .framework-map.json and what it states wins:

{
  "name": "billing-e2e",
  "purpose": "End-to-end tests for the billing portal.",
  "layers": {"steps": "steps/*.py — steps own no selectors, they call page objects"},
  "product_src": ["../billing-web/src"],
  "conventions": ["After a fix, re-run only what failed."]
}

.wawe.toml holds CLI flags as defaults, .wawe-ignore keeps build output out, existing files are never overwritten, and anything shaped like a credential is redacted before it reaches a file. The commit and the newest file in the tree are recorded with the map, and so is a sha256 over what every indexed file holds, so a re-run on an unchanged tree costs a stat walk and a re-run on a tree whose timestamps lie still sees it.

What is redacted

The map holds every indexed line of every indexed file, and the map gets committed and pasted into prompts, so these rules replace a credential with [redacted] before anything is written:

1. A whole PEM block, -----BEGIN ... PRIVATE KEY----- through -----END ...-----, header and body alike.
2. An issuer prefix at the start of a word: AKIA... (AWS), ghp_/gho_/ ghs_/ghu_/github_pat_ (GitHub), xox?-... (Slack), sk_live_/ sk_test_/rk_live_/rk_test_ (Stripe), sk-/sk-proj- (OpenAI), pypi- (PyPI), a JWT.
3. A base64 blob of forty characters or more that carries a + or ends in = padding.
4. The password inside a URL: postgres://admin:pw@host/db keeps the scheme, the user and the host and loses the password.
5. The value on a line whose left-hand side names a secret. The last segment of the key has to be secret, password, passwd, token, api_key, private_key, credential, auth or authorization, in an assignment, a dict or JSON key, a YAML key or an export. A quoted value and a bare value after = are replaced wherever they sit on the line, so a .env line inside a shell string counts too. A bare value after : is replaced only on a line shaped like YAML: the key starts the line, is not quoted, and nothing after the value turns the line back into code.

Key names are kept, and so are the quotes around a redacted literal, so a question about where a password is set still gets the file, the line and the syntax. What is not redacted, deliberately:

• Code on the right-hand side. No value rule admits a bracket, so token = lexer.next_token() and PASSWORD = os.environ["PW"] stay.
• A name that merely mentions a credential. The secret word has to be the last segment, so token_count, max_token_count, auth_backend, secret_name, api_key_header, private_key_path and credential_kind all stay.
• A number, a True/False/None, or a bare type name, whatever the key is called: has_token = True and the dataclass field token: str = "" stay.
• A commit sha, and a path. Rule 3 needs a + or an =, and a forty-character hex sha has neither. A slash is not a gate either, because src/main/java/com/example/service/impl/CustomerServiceImpl is a run of letters and slashes and nothing else.

.wawe.toml's [synonyms] table adds a project's own words to --ask's built-in groups (login/signin/auth, invoice/bill/billing, and eighteen more):

[synonyms]
invoice = ["proforma", "receipt"]

merges into the group that already has invoice, or starts a new group when none does. --ask "invoice" then also searches proforma and receipt.

--repo PATH                  the repository to index
--product PATH,…             source roots of the application under test
--also PATH,…                other repositories to fold into the same map
--out DIR                    where the three files land
--agent-file FILE            also write the brief into AGENTS.md, CLAUDE.md, …
--docs [write]               offer the repository the documentation it lacks
--for author|coder           author gets the whole vocabulary; coder gets the rest
--only "routes,data model"   keep only these sections in the brief
--skip "coverage,history"    drop these
--max-lines N                cap the brief per section; the full map is untouched
--diff                       what changed since the map already in --out:
                             the files that moved, then the keys
--init                       write a starter .framework-map.json
--install-hook KIND          wire it into something that already runs:
                             git|claude|cursor|codex|gemini (agent = claude)
--watch SECONDS              rebuild whenever the tree moves
--html                       also write framework_map.html
--ctags                      also write <out>/tags, in universal-ctags format
--force                      rebuild even when nothing moved, reading
                             nothing from the parse cache
--quiet                      no summary line
--dry-run                    print every path this command would write, and
                             write none of them
--defines NAME               every place NAME is declared, with its span
--at FILE:LINE               the whole definition that encloses that line
--context NAME               declared, map rows, callers, callees and
                             impact one hop out, in one answer
--affected FILE[,FILE]       which tests a change to those files reaches:
                             scenarios, features, routes, page objects
--changed [REF]              the same, for what `git diff --name-only REF`
                             names (HEAD by default)
--affected-format behave|pytest
                             that selection as the runner's own list,
                             printed whole
--affected-out FILE          write that selection to FILE and print the
                             answer a person reads to stdout; an empty
                             file means run nothing
--affected-depth N           how many hops --affected follows (default 6)
--reaches NAME               which scenarios, pytest cases and routes reach
                             that function or class, with the chain of calls
--unreached                  the product definitions no test reaches, ranked,
                             with the resolution rate
--path A,B                   the shortest call chain from A to B, one hop
                             per line with how each edge was resolved
--path-depth N               how many hops --path follows (default 6)
--range NAME                 every home of NAME, the shortest one's text,
                             and the lines an editor anchors on; a line this
                             map redacted is printed with a warning beside
                             it: it is not the line on disk
--dead                       questions, not dead code: the definitions no
                             call row lands on, by file
--hot                        rank score times commits, both numbers shown;
                             churn covers the forty busiest files
--rank [FILE,...]            the definitions the repository is built around,
                             personalised on the files you name
--files FILE[,FILE]          on --ask: those files' rows first in every
                             section; `-` reads the list on stdin
--limit N                    how many rows --rank, --dead and --hot print
                             (default 200, 40 files, 40)
--cost [THRESHOLD]           what the map and its brief cost per section:
                             rows, bytes and tokens, heaviest first
--export FILE                the map as one self-contained file to paste,
                             or `-` for stdout
--effects [--json]           what every flag does to the disk; with
                             `-- <command line>`, the class of that line

As an MCP server

where-are-we --mcp --out /path/to/the/map

Eighteen tools over JSON-RPC on stdin and stdout: affected, ask, at, callees, callers, context, dead, defines, find, hot, impact, more, path, range, rank, reaches, sections, unreached. defines answers where a name is declared, in every file that declares it, with the line each declaration ends on; at takes the file:line a stack trace names and returns the whole definition around it; context answers all five questions about a name at once, so landing on one costs a single round trip; rank answers what the repository is built around, and takes the files you are editing so the answer is about them; find answers where a phrase appears, which is the other half of what a grep was for. ask takes files for the same reason --files exists. The same index answering the same questions; what changes is that the question is an argument and the answer is a tool result, rather than a shell command and its output sitting in the conversation to be re-read on every turn after.

It reads the JSON the mapper wrote, on the same machine, offline.

As a library

from where_are_we import build, brief

m = build("/path/to/repo")
open("AGENTS.md", "w").write(brief(m))

Examples

Real output on a behave suite, a Go service and a React app — docs/examples. Generated by running the tool, not by hand.

Why it exists

Built inside an agentic QA pipeline where seven branches ran at once, each opening with the same forty greps. Three runs died at their deadline with the branches still reading. None of it was specific to that pipeline, agent, or language.

Contributing

Issues and PRs welcome — CONTRIBUTING.md. A change keeps the contract in SCHEMA.md and comes with a case in tests/ built from a real directory.