pip install where-are-we
where-are-we --repo . --agent-file AGENTS.md

That is the whole setup. The next agent session opens already knowing where it is.

Who this is for

You run agents on a codebase. Every session opens with the same forty tool calls: where do the tests live, what may a step call, how is a scenario launched, which environment variables must be set, what does the product expose. At a minute a turn that is half an hour of your budget, per session, for answers that never change between sessions and need no model to produce.

You maintain a pipeline that fans out. Seven branches means seven copies of that half hour, in parallel, every run. This was built when three runs in a row died at their deadline with the branches still reading.

Someone new is joining. The same map is the onboarding document, and it cannot go stale: it is rebuilt from the checkout, not written by hand.

You inherited a repository nobody can explain. Point it at the thing and read what comes out — routes, data model, queues, schedules, dead code, who has been touching what.

What you get

--agent-file writes the brief between markers into AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md — anything else in the file survives.

What it reads

Supported

Test runners — behave · pytest · jest · vitest · playwright · cypress · robot · JUnit · TestNG · Cucumber-JVM (Java, Kotlin, Scala) · cucumber-js (TypeScript, JavaScript) · cucumber-ruby · rspec · go test · xUnit · NUnit · SpecFlow · PHPUnit · Behat · Rust · XCTest · karate · gauge · k6 · gatling

Languages — Python · TypeScript · JavaScript · Go · Java · Kotlin · Scala · Ruby · Rust · C# · PHP · Swift · C/C++ · Shell · SQL · Protobuf · Elixir · Erlang · Dart · Groovy · Clojure · Haskell · Lua · Perl · R · Julia · Objective-C · F# · VB.NET · Solidity

More test runners — ExUnit · Flutter · Spock · clojure.test · hspec · busted · Perl Test · Foundry · Julia · Espresso · XCUITest · Detox

Frontend — React · Vue · Svelte · Angular · Storybook

Data — dbt · Airflow · Spark · notebooks

Contracts — OpenAPI · GraphQL · AsyncAPI · JSON Schema · Avro · Thrift · SOAP/WSDL · tRPC · Pact

Web frameworks — Flask · FastAPI · Django · Express · Nest · Go net/http and chi · Spring · Rails

Infrastructure — Docker · Compose · Kubernetes · Helm · Terraform · CloudFormation · Pulumi · Bicep · Ansible · Chef · Puppet

CI — GitHub Actions · GitLab CI · Jenkins · CircleCI · Azure Pipelines · Travis · Buildkite · Drone · Bitbucket

Build — Make · Gradle · Maven · Bazel · sbt · CMake · Rake · npm/pnpm workspaces

Datastores and brokers — PostgreSQL and friends · MongoDB · Elasticsearch · DynamoDB · Cassandra · ClickHouse · Kafka · RabbitMQ · SQS · NATS · Pulsar · MQTT

Observability and policy — Prometheus rules · Grafana dashboards · OpenTelemetry · OPA/Rego · LaunchDarkly · Unleash

Load testing — JMeter · Locust · Artillery · k6 · gatling

Detection is by shape, not by directory name: a page object is a class that owns selectors — wherever it lives, whatever the team calls it. Point it at a repository before you know what is in it.

When the repository knows better

Autodetection gets the shape right and the vocabulary wrong. A repository states its own, and what it states wins:

where-are-we --repo . --init      # a starter manifest, from what was detected

{
  "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."]
}

.framework-map.json at the root, or the same block fenced as ```framework-map in README.md.

Directories can explain themselves too:

wawe-readmes --repo .   # a README in every content directory that lacks one,
                        # derived from what is in it, one TODO line for a human

The map reads them back.

Keeping it current

The commit and the newest file in the tree are recorded with the map, so running it on every checkout costs a stat walk and nothing else.

where-are-we --repo . --install-hook git     # post-checkout, post-merge, post-commit
where-are-we --repo . --install-hook agent   # SessionStart, before the first turn
where-are-we --repo . --diff                 # what changed since the last map

Options

--repo PATH                  the repository to index
--product PATH,…             source roots of the application under test
--out DIR                    where the three files land
--agent-file FILE            also write the brief into AGENTS.md / CLAUDE.md / …
--only "routes,data model"   keep only these sections in the brief
--skip "coverage,history"    drop these
--max-lines N                cap the brief; the full map is untouched
--diff                       what changed since the map already in --out
--init                       write a starter .framework-map.json
--install-hook git|agent     wire it into something that already runs
--rules PATH                 a corpus of rules to list by name
--runs-api URL               a runs database, to carry what earlier runs concluded
--force                      rebuild even when nothing moved
--quiet                      no summary line

.wawe-ignore (falling back to .gitignore) keeps build output out; WAWE_MAX_FILES bounds the walk.

As a library

from where_are_we import build, brief

m = build("/path/to/repo")
print(m["counts"], len(m["routes_served"]))
open("AGENTS.md", "w").write(brief(m))

Why it exists

It was built inside an agentic QA pipeline where seven branches ran at once and each opened the same way: forty greps to find where the steps live, which page object owns the portal, how the driver is built, what environment.py does. Identical in every branch, identical every run, derivable without a model — and three runs died at their deadline with the branches still reading.

Nothing about it turned out to be specific to that pipeline, that agent, or that language.

Contributing

Issues and pull requests welcome — see CONTRIBUTING.md. Changes are expected to keep the JSON contract in SCHEMA.md and to come with a case in tests/ built from a real directory.

License

MIT