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.

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. 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 the map's tools over MCP (ask, find, defines, sections) and ships five skills. 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-07 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.

--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.

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".

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.

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.

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}]

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, so a re-run on an unchanged tree costs a stat walk.

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
--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
--force                      rebuild even when nothing moved, reading
                             nothing from the parse cache
--quiet                      no summary line

As an MCP server

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

Four tools — ask, defines, find, sections — over JSON-RPC on stdin and stdout. defines answers where a name is declared; find answers where a phrase appears, which is the other half of what a grep was for. 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.