{"slug": "show-hn-readfirst-a-repo-map-your-coding-agents-read-before-they-edit-a-file", "title": "Show HN: Readfirst – a repo map your coding agents read before they edit a file", "summary": "A developer released readfirst, an MIT-licensed tool that stores team knowledge about a codebase in a single `.readfirst/map.json` file and serves it file by file to coding agents such as Claude Code, Cursor, Codex and Gemini before they edit code. The tool requires Node 20+, runs with no server, account or model calls, and ships with `init`, `read` and `verify` commands plus a GitHub Action. Building maps for open source projects surfaced real bugs already fixed or filed with maintainers, including a saleor option that recalculated every discounted price instead of only changed ones (saleor/saleor#19984), a wagtail moderation email sent to the submitting superuser (wagtail/wagtail#14790), a Tandoor `?category=` API filter that never applied (TandoorRecipes/recipes#4917), and a mealie household safety filter that never applied (mealie-recipes/mealie#8964).", "body_md": "**What to read and check before you — or your AI agent — change a file.**\n\nCoding 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.\n\nNo server, no account, no model calls. MIT. It reads your git checkout and `.readfirst/map.json`.\n\nMaking maps for open source projects, a check for lines whose result is thrown away found real bugs. The ones already with their maintainers:\n\n- **saleor** : an \"only recalculate what changed\" option recalculated every discounted price\n([saleor/saleor#19984](https://github.com/saleor/saleor/pull/19984) ).\n- **wagtail** : a superuser who submits a page for moderation got the moderation email about their own submission\n([wagtail/wagtail#14790](https://github.com/wagtail/wagtail/pull/14790) ).\n- **Tandoor** : a`?category=` filter on an API endpoint never applied\n([TandoorRecipes/recipes#4917](https://github.com/TandoorRecipes/recipes/pull/4917) ).\n- **mealie** : a safety filter on households never applied; the maintainers fixed it\n([mealie-recipes/mealie#8964](https://github.com/mealie-recipes/mealie/issues/8964) ).\n\nAny language; needs Node 20+.\n\n```\nnpx readfirst init --agent --ci   # a first map, your agents wired to it (Claude Code, Cursor, Codex, Gemini, ...), the PR Action\nnpx readfirst read <file>         # before changing a file: its rules, risks, checks, tests and callers\nnpx readfirst verify              # before you finish: run the checks for everything your branch changed\n```\n\nCommit `.readfirst/map.json`. Filled maps for real repositories (vercel/ai, cal.com, excalidraw and two more):\n[examples/](https://github.com/jeonghun917/readfirst/blob/main/examples).\n\nEverything else (Claude Code plugin and hook, MCP for any agent, Cursor rules, the GitHub Action, the map format,\n`audit`, `find`, monorepos, pinning a version): **[the guide](https://github.com/jeonghun917/readfirst/blob/main/docs/guide.md)**.\n\nThe CLI, hook, MCP server and Action are free and never send your code anywhere. The\n[readfirst-app](https://readfirst-cloud.vercel.app/) GitHub App can write the first map for you (free once per\naccount) and, on Pro, keep it in step after merges and comment on pull requests. Details in\n[the guide](https://github.com/jeonghun917/readfirst/blob/main/docs/guide.md#hosted-readfirst-app).\n\nMIT", "url": "https://wpnews.pro/news/show-hn-readfirst-a-repo-map-your-coding-agents-read-before-they-edit-a-file", "canonical_source": "https://github.com/jeonghun917/readfirst", "published_at": "2026-11-04 06:49:10+00:00", "updated_at": "2026-11-04 07:20:21.158243+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["readfirst", "Claude Code", "Cursor", "Codex", "Gemini", "saleor", "wagtail", "mealie"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-readfirst-a-repo-map-your-coding-agents-read-before-they-edit-a-file", "markdown": "https://wpnews.pro/news/show-hn-readfirst-a-repo-map-your-coding-agents-read-before-they-edit-a-file.md", "text": "https://wpnews.pro/news/show-hn-readfirst-a-repo-map-your-coding-agents-read-before-they-edit-a-file.txt", "jsonld": "https://wpnews.pro/news/show-hn-readfirst-a-repo-map-your-coding-agents-read-before-they-edit-a-file.jsonld"}}