What Is Readfirst? The Beginner's Guide to the Repo Map Your Coding Agents Read Before Editing

CodexFuse Team · 2026-11-05T10:14:47.179Z · 22 min read min read

What Is Readfirst, the Repo Map for Coding Agents?

What is Readfirst? It is a free, open-source tool that keeps your team's per-file rules in a committed map and hands them to your coding agent before it edits a file. This guide is readfirst explained in plain English, for developers whose agents keep breaking rules the team already knows.

A readfirst repo map is a single JSON file, .readfirst/map.json, that lives next to the code it describes. For every file, it records the rules that file must keep, the risks a newcomer would get wrong, the checks that prove the rules hold, and the tests and callers. When an agent is about to change a file, Readfirst prints that file's entry first, so the agent reads the team's knowledge instead of guessing it.

Readfirst launched on Hacker News on November 4, 2026, one day before this guide was written. The repository was created on October 31, 2026, and by November 5 it had 67 commits, 1 star, and 1 fork, with version 0.15.1 published on npm that morning. Everything in this guide carries its date, because a project this new can change fast.

The problem Readfirst solves is easy to recognise. Coding agents can follow imports, but they do not know what your team knows: that amounts in one file are in cents, that a table is read by the mobile app so old columns must stay, or that the payment test must run after touching billing code. That knowledge usually lives in people's heads, or scattered through chat messages, and the agent never sees it.

Readfirst puts that knowledge in one file next to the code. The README puts it this way: the tool keeps team knowledge in one file next to the code and hands it out, file by file, at the moment someone is about to change something.

Three facts shape everything else in this guide. Readfirst has no server, no account, and no model calls: it reads your git checkout and the map file, and nothing else.

It is MIT licensed, and the command-line tool, the hook, the MCP server, and the GitHub Action are free. It works for any language, as long as Node 20 or newer is installed to run it.

Two quick anchors before the detail. Readfirst records the commit where a rule last held, using the commit hash as the proof, and a SHA-256 hash generator shows how a hash can stand in for content without revealing it. Because the tool runs locally and never sends your code anywhere, it fits on a machine you control, and VPS hosting gives you a private server for local-first tools.

Why Do Coding Agents Keep Breaking Your Team's Rules?

The failure mode is familiar to every team that hands a repository to an agent. You ask for a small change, the agent edits the right file, and the change breaks a rule nobody wrote down: it renames a column the mobile app still reads, or it changes an amount from cents to dollars, or it skips the payment test that would have caught the mistake.

The agent is not being careless. It reads the code, and the code does not contain the rule.

Imports tell it which files a change touches, but nothing about the promises the team made around those files, or the traps a newcomer would fall into. Without that context, the agent fills the gap with a guess, and guesses about money, migrations, and public APIs are usually wrong.

A written rule in a prose file helps, but only if the agent reads it. Instruction files such as AGENTS.md and CLAUDE.md are the usual answer, and a census of 22,854 popular, active GitHub repositories found them in 26.3 percent of repos, rising to 59.6 percent of the most-starred ones. The same study found those files behave like configuration code: they grow through frequent, small additions, and go stale the same way code does.

Staleness is the real enemy. A prose rule has no check that it still matches the code, so a rule written six months ago can quietly describe a file that no longer exists, or a test that no longer runs. Readfirst closes that gap: the map is data, not prose, and the tool checks it against the repository every time it runs.

How Does a Readfirst Repo Map Work?

The model has three parts: a map, a read step, and a verify step. The map is the committed JSON file that describes the repository in groups, rules, and risks.

The read step prints the entry for a file before anyone changes it. The verify step runs the checks the map lists for everything a branch changed, and fails the build if one fails.

Groups are the map's unit of organisation. Every tracked file belongs to exactly one group, or to the ignore list, and the check command fails if a file belongs to neither. That single constraint is what stops the map from falling behind the code: a new file either joins a group or the check tells you it is unplaced.

Rules are promises the code must keep, and a rule can span groups. Risks are the things a newcomer would get wrong about a file or a group. Checks are the commands that prove a rule still holds, such as a test suite or an end-to-end run, and each check carries a short reason.

The read step adds something a prose file cannot: the code around the file. A read list includes the tests that reach the file through imports, the files that use it, and the hot spots inside it, so the agent sees the blast radius before it edits. Verify then runs only the checks for the changed files, which keeps the gate fast.

What Is Inside .readfirst/map.json?

The file is plain JSON with the format name readfirst/map@1. In search results the file is usually called the readfirst map.json file, and the guide documents every field it can hold. The guide's billing example shows the shape: a group called src-billing, titled charging cards, with the risk that amounts are in cents, plus a rule called no-double-charge that runs the payment end-to-end test.

Two fields deserve a closer look. Requires ties files together: if a change touches src/billing/models.ts and nothing under migrations, verify fails, the Claude Code stop hook sends the agent back once, and the read list says change these too. Dependents records that another repository, such as acme/web, calls a route in this one, and verify reminds you of that link.

Hotspots and deprecated groups are usually written by a tool rather than by hand. A hotspot names a file, a symbol, a line, and labels such as db-write or money. A deprecated group tells the hook not to add to the old code, and lets audit count the files outside it that still import it.

How to Set Up Readfirst in Five Steps

Setup takes one command and a short review pass. Step one runs readfirst init agent, typed as npx readfirst init --agent --ci, which builds a first map from your folders, takes the checks from your scripts, adds the read-before-editing line to your agent notes, and installs the GitHub Action. The repository is jeonghun917/readfirst on GitHub, so searches for readfirst jeonghun917 land on the same project.

1. Run npx readfirst init --agent --ci to create the first map, wire your agents, and add the pull-request Action.
2. Run npx readfirst prompt to get a brief for your coding agent, then let the agent fill in titles, checks, risks, and rules.
3. Run npx readfirst check to confirm every tracked file sits in exactly one group and every rule points at a real file.
4. Commit .readfirst/map.json so the map travels with the code and every reviewer sees it.
5. Run npx readfirst read on a file you are about to change, and npx readfirst verify before you finish, to make the habit stick.

The init command suggests the checks your project already has, from npm test and pytest to go test, cargo test, and bundle exec rspec, so you record commands the team runs. If writing the first map by hand feels like too much, the hosted GitHub App will write it: install readfirst-app, comment /readfirst fill on any issue, and a pull request arrives in 5 to 20 minutes, each risk and rule citing its file and line.

Version pinning is worth doing from the start. Every release is published from GitHub Actions with npm provenance, and the guide shows how to pin the exact version you reviewed: npx [email protected] read for the command line, and jeonghun917/[email protected] for the Action. Version 0.15.1 was the latest on November 5, 2026, published that morning, four days after the npm package first appeared.

What Are the Three Commands You Use Every Day?

Most days you need three commands: read, find, and verify. Read comes before you change a file, find comes before you write something new, and verify comes before you finish. The rest exist for setup, inspection, and automation, and you can learn them as you need them.

Find deserves a closer look, because it stops the commonest waste in agent-written code: a second copy of a helper that already exists. The command npx readfirst find payment retry lists the functions, classes, and types whose names hold those words, the files whose paths do, and the groups, rules, and risks that mention them.

Find matches words, not meaning, and the guide is honest about the limit. Retries meets retry, and pay meets payment, but try_again is not found for retry, and words such as add, new, or helper are ignored. On a 4,700-file Django repository, find takes under two seconds, and audit takes about two seconds, with no model and no index.

Verify is the gate, and the guide defines done precisely. A change is done when every check the map lists for the changed files passes and no file the map ties to them was left out.

Verify also names the rules on those files that no check covers and the other repositories that depend on them, but those two do not fail the gate: they say what is still unproven. Passing verify means the checks you wrote passed, and nothing more.

How Does Readfirst Wire Into Claude Code, Cursor, Codex and Gemini?

Wiring makes the map automatic instead of a document nobody opens. The init --agent flag and the setup command add one line to the agent notes your repository already has, whether that is CLAUDE.md, AGENTS.md, .cursorrules, GEMINI.md, .windsurfrules, or .github/copilot-instructions.md, creating an AGENTS.md if there is none. The line tells the agent to run read before changing a file, find before writing a new function, and verify before finishing.

The same setup adds Readfirst's MCP server to each agent's own project config: the Claude Code hook in .claude/settings.json, .cursor/mcp.json, .vscode/mcp.json for Copilot, .gemini/settings.json with GEMINI.md, .codex/config.toml, and opencode.json. It keeps what is already in those files, does nothing the second time, and never writes outside the repository. Two limits are worth knowing: a file it cannot parse, such as JSON with comments, and settings in your home folder, such as Windsurf's, are printed for you to add by hand, and Codex reads .codex/config.toml only in a project you have marked as trusted.

The MCP server is npx readfirst mcp, with five tools: read_list, changed_read_list, find_existing, check_map, and audit_repo. It answers from the checkout as it is and writes nothing, so any agent that speaks MCP can use the map without a new integration. If you want the protocol background, What MCP over MOQT is explains how MCP messages travel between an agent and its tools.

The Claude Code hook is the most automatic option. Running npx readfirst hook --install adds a hook to .claude/settings.json, and before each Edit or Write, Claude Code receives the rules, risks, and checks for that file as context, once per file per session.

The edit is never blocked, and there is nothing to remember, which is the point: the agent gets the rules without being asked. If you use Claude Code as your main agent, How to use Claude Code covers the setup around it.

Adding --verify to the hook install adds a Stop hook with teeth. Before Claude Code finishes its turn, it runs the map's checks for the files it edited, and if one fails, Claude Code cannot finish yet and gets the failure to fix. It gets one try per turn, so a check it cannot fix never traps the session, and it runs only check commands the map on the main branch already lists: a command a branch adds is named, not run, until it is merged.

Plugins package the same instructions for two more hosts. Claude Code 2.1.275 or later can install it with /plugin install readfirst --marketplace jeonghun917/readfirst, and Paradev users run the superset marketplace add and install commands. On Paradev the skill reaches every agent in the workspace, and it runs the command line locally, with no MCP server and no network.

What Does the GitHub Action Do on Every Pull Request?

The Action is one workflow file, .github/workflows/readfirst.yml, triggered on pull_request, with read access to contents and write access to pull requests, running jeonghun917/readfirst@v0. Each pull request gets one comment, updated on every push, listing the rules, risks, and checks for the files it changes, with the checks as boxes to tick, and the tests that reach the changed code.

A new file next to files the map already places joins their group. The check passes, the comment notes where the file went, and npx readfirst fix writes that placement down whenever you like. The check fails only on what needs a person: a new top-level folder, a rule whose files are all gone, or a map that is broken in itself, and the comment lists what fix would change.

Five inputs tune the Action. Fail-on-map-problems defaults to true, strict to false, comment to true, auto-fix to false, and limit to 30, which caps the tests and users listed per section. Turning on auto-fix needs write access to contents, and then the Action commits what fix settles to the pull-request branch, skipping forks and skipping the commit if the branch's map changed since the run started.

Fork pull requests get a read-only token, so the list goes to the job summary instead of a comment. A commit made with the default GITHUB_TOKEN does not start new workflow runs, and if branch protection requires checks, pass a GitHub App or personal token as the token input.

How Does Readfirst Audit a Whole Repository?

Check asks whether the map covers the files, and audit asks whether the map still tells the truth about them. Audit reads the checkout and its git history, runs nothing, and changes nothing, and it reports in plain terms what has drifted. Run it when the map feels stale, or on a schedule.

Stale rules are the first thing audit reports. If the line that holds a rule or a risk was written before ten or more commits changed the files it covers, audit names it, says when it was written, and says how much has moved since. Hot spots get the same treatment: audit reports those no longer at their line, and those nothing checks, because no test reaches their file and no check of their own covers them.

Audit also reports what was never filled in. Groups still titled TODO from init, and rules no check verifies, are listed so the team can finish them or delete them.

Code no test reaches is listed most-used first, with a count per group, and code being replaced that is still used is counted through the deprecated groups. With .readfirst/held.json, audit lists rules never recorded as holding and rules whose files changed after they last held.

Two honest limits come with the audit. First, readfirst cannot see some code at all: languages whose imports it does not read, and modules loaded by a computed name, such as a plugin path built from a variable or a settings module loaded by name.

An empty used-by list for those means unknown, not none, and read lists say so too. Second, held rules need the record step: npx readfirst verify --record writes .readfirst/held.json with the commit and date for every rule whose checks all passed, and a rule with no check is never recorded, so give it one.

One more view makes the map visible to people who will never read JSON. Running npx readfirst view renders the map as a city in one HTML page: groups are neighbourhoods, files are buildings that grow taller when more code depends on them, and traffic between neighbourhoods is the imports between them.

A red-lit building has a risk on it, and an amber one is under a rule. The page loads three.js from a content delivery network, which is the only network fetch in the local tooling, and labels written with prompt --labels stay on your machine, because .readfirst/local is excluded from git.

Readfirst vs AGENTS.md: Product vs Format

Developers searching for readfirst vs agents.md usually want one answer: is this another instruction file, or something different. The answer is that AGENTS.md is a format and Readfirst is a product, and AGENTS.md is a plain Markdown file at the repository root that tells an agent how the project works, with no front matter, no schema, and no special syntax. Claude Code reads its sibling CLAUDE.md, while Codex resolves AGENTS.md by proximity to the file being edited.

Readfirst uses the same idea, a file the agent reads before editing, but it stores the knowledge as structured data and checks it. The guide puts the comparison in three parts: a Readfirst map cannot go stale quietly, because check fails in continuous integration when a file is in no group, and audit lists rules written before their files changed a lot; it knows the code around the file, because read lists add the tests that reach a file through imports and the files that use it; and one source feeds every tool, from the Claude Code hook to the pull-request comment and Cursor rules.

The distinction matters most for teams, not for solo projects. A solo developer can keep an AGENTS.md file accurate by hand, because one person knows when it drifts.

A team with several agents editing the same repository cannot, because the drift is silent and the prose has no test. Readfirst is built for that second case: the map is data, the data is checked, and the checks run where the work happens.

None of this makes AGENTS.md wrong. The two work together, and Readfirst's setup writes its line into the AGENTS.md or CLAUDE.md file you already have. The census shows why the combination is timely: agent instructions appear in 26.3 percent of 22,854 popular repositories, and in 59.6 percent of the most-starred ones, so the question has moved from whether to write one to whether anyone checks it.

What Did Readfirst Catch in Real Repositories?

The strongest evidence in the README comes from the hosted version, which scans for fixed bug shapes taken from real bugs. The team ran it over 44 open-source repositories and checked every finding by hand. The counts below are the project's own numbers, and the README says to read them as what is there, not as precision, because they come after tuning on the same repositories.

The 36 tests share one shape, and it is worth seeing, because it is easy to write by accident. Each test used expect with a promise and resolves, but with no await and no return, so the test ended before the assertion ran.

The test passed every time, and it proved nothing. A map that ties a file to its tests makes that shape visible.

Four of the bugs were fixed by the maintainers of the projects where they were found. In Saleor, an option meant to recalculate only what changed recalculated every discounted price, in issue 19984. In Wagtail, a superuser who submitted a page for moderation received the moderation email about their own submission, in issue 14790.

In Mealie, a safety filter on households never applied, in issue 8964. In django-allauth, a provider callback returned a 500 error instead of a clean failure on a non-ASCII value, and it was fixed the day it was reported.

One finding is still with its maintainers: a Tandoor filter that never applied, in issue 4917, and further findings were sent privately to other projects, which stay unnamed until they are fixed. The honest reading is narrow: a new tool with a small scan found real bugs, and four maintainers fixed them. It is not a benchmark, and it is not a claim that the free command line would find the same bugs, because the scan came from the hosted version.

Who Should Use Readfirst, and Who Should Wait?

Readfirst fits teams whose coding agents edit shared code every day. If your agents keep breaking rules the team already knows, or your AGENTS.md file is long enough that nobody can tell which parts are still true, a checked map is worth the hour it takes to set up. The free command line, hook, MCP server, and Action cost nothing.

The hosted side is where money enters the picture. The GitHub App writes the first map free once per account, for repositories up to 200 files, and the pull request arrives in 5 to 20 minutes. Pro costs 19 dollars a month, covers fills for up to 3 private repositories, and after each merge proposes a small pull request when the map needs it, plus comments where lines look like they break a rule.

A one-time map setup costs 290 dollars for up to 3 repositories, takes 5 business days, and includes the first month of Pro. Over a year, Pro alone costs 228 dollars, which is 19 dollars times 12 months.

The launch is quiet so far: the Show HN thread had 2 points and 0 comments when checked on November 5, 2026. That is not a criticism, because every tool starts at one star. It is a reminder to pin the version you reviewed, to read the guide before trusting the defaults, and to treat the map as a living file, not a one-time setup.

Two practical notes close the verdict. First, Readfirst will not write your rules for you: the free tooling records what your team knows, and only the hosted app drafts the first map.

Second, nothing here promises a CodexFuse Readfirst tool: this guide explains the product as it exists, and the tool to try is the one on GitHub. If you run agents in disposable sandboxes while you evaluate it, how to use E2B shows a clean way to do that.

Sources

All sources were fetched on November 5, 2026. Product details are as stated on those pages on that date.

• Readfirst launch record, VibeHacker, November 4, 2026 — vibehacker.com
• Readfirst repository, README and guide — github.com
• Readfirst guide, map format, commands, and hosted pricing — github.com
• Show HN thread, item 50362206, November 4, 2026, via the Hacker News Firebase API — news.ycombinator.com
• Readfirst package record, version 0.15.1, November 5, 2026 — npmjs.org
• Agent READMEs census, arXiv 2610.31715, October 2026 — arxiv.org
• AGENTS.md how-to, dev.to — dev.to

Frequently Asked Questions

What is Readfirst, in one sentence?

Readfirst is a free, MIT-licensed command-line tool that keeps your team's per-file rules, risks, and checks in a committed .readfirst/map.json file, so coding agents read them before they edit a file.

Does Readfirst replace AGENTS.md?

No. Readfirst writes its read-before-editing line into the AGENTS.md or CLAUDE.md file you already have, and the two work together: the instruction file holds the prose, and the map holds the checked, per-file rules.

Does Readfirst send my code anywhere?

No, for the free tooling. The command line, hook, MCP server, and Action read your git checkout and the map file, and never send code anywhere. Only the hosted GitHub App reads your repository, and what it reads and keeps is listed on its site.

What does Readfirst cost?

The command line, hook, MCP server, and Action are free. The hosted GitHub App writes the first map free once per account for repositories up to 200 files, Pro costs 19 dollars a month for up to 3 private repositories, and a one-time map setup costs 290 dollars.

How do I start using Readfirst today?

Run npx readfirst init --agent --ci in a repository with Node 20 or newer, let the prompt brief fill in the rules, run check to confirm every file has a group, and commit .readfirst/map.json. Then use read before changing a file, find before writing new code, and verify before finishing.