Show HN: Readfirst – a repo map your coding agents read before they edit a file

What to read and check before you — or your AI agent — change a file.

Coding agents can follow imports. What they don't know is what your team knows: "amounts here are in cents", "this table is read by the mobile app, keep old columns", "run the payment e2e after touching this". readfirst keeps that knowledge in one file next to the code and hands it out, file by file, at the moment someone is about to change something.

No server, no account, no model calls. MIT. It reads your git checkout and .readfirst/map.json.

Making maps for open source projects, a check for lines whose result is thrown away found real bugs. The ones already with their maintainers:

npx readfirst init --agent --ci # a first map, your agents wired to it (Claude Code, Cursor, Codex, Gemini, ...), the PR Action npx readfirst read <file> # before changing a file: its rules, risks, checks, tests and callers npx readfirst verify # before you finish: run the checks for everything your branch changed

Commit .readfirst/map.json. Filled maps for real repositories (vercel/ai, cal.com, excalidraw and two more): examples/.

Everything else (Claude Code plugin and hook, MCP for any agent, Cursor rules, the GitHub Action, the map format, audit, find, monorepos, pinning a version): the guide.

The CLI, hook, MCP server and Action are free and never send your code anywhere. The readfirst-app GitHub App can write the first map for you (free once per account) and, on Pro, keep it in step after merges and comment on pull requests. Details in the guide.