AI

What an agent learns about your repo belongs in the repo

boyscout-rule is an open-source plugin for Claude Code, Codex and OpenCode. When an agent runs into a stale doc or a wrong command, it fixes the source in a small draft PR. Many small fixes improve a repository without a cleanup project.

Sasa Fajkovic12 min readAI
What an agent learns about your repo belongs in the repo

boyscout-rule is open source under the MIT licence. Get it on GitHub: github.com/sasa-fajkovic/boyscout-rule. Install steps for Claude Code, Codex and OpenCode are in the README.

I published boyscout-rule, a plugin for Claude Code, Codex and OpenCode. When an agent runs into a wrong instruction, a stale doc or a small bug next to its work, it fixes the source in a small draft PR. It does not write a note to its own memory.

One PR changes a few lines. Over weeks they add up: the docs match what people actually run, the scripts work, and the repository gets better without anyone planning a cleanup.

On 19 November I am speaking at the GDS Herbsttagung in Berlin (details), and on 3 and 4 December at the DACH AI, Data in Finance & Insurance Summit in Frankfurt (details). Both talks are about agents in production: what an agent may do without asking, and how a person checks its work. This plugin had to answer the same two questions, because it opens pull requests nobody asked for.

The lesson that goes nowhere

This website’s README said to run the local preview on port 4321. The right port is 4325. An agent that followed the README opened a different project’s site, worked out why, and finished its task.

The task was done. The README still said 4321.

What the agent learned can go to one of three places.

Nowhere. The session ends and the next one starts from the same README.

The agent’s memory. Claude Code writes notes for itself into ~/.claude/projects/<project>/memory/, on by default in local sessions. The documentation is clear about the scope: “Auto memory is machine-local”, and the files “are not shared across machines or cloud environments”. Codex has its own version, off by default and stored under ~/.codex.

A note there helps me, on this laptop, in this tool. My colleague’s agent reads the same README tomorrow and makes the same mistake. So does a new hire. And nobody reviewed the note. If the agent drew the wrong lesson, every later session loads it anyway.

The README. That is where the mistake came from, and it is the one place every person and every agent on the team reads.

A rule older than agents

Robert C. Martin called it the Boy Scout Rule: “Always leave the campground cleaner than you found it.” For code he turned it into “Always check a module in cleaner than when you checked it out.”

It is hard to disagree with, and it still gets skipped. The reason is mechanical. I find the stale README while I am in the middle of something else. Fixing it properly means setting my work aside, a new branch, a second pull request and someone to review it. So it goes on a list, and the list does not get done.

For an agent most of that cost is gone. A second worktree, a three-line diff and a pull request cost it almost nothing, and the main task keeps running while a sub-agent does the publishing. The part that still costs something is the review, and that part should stay with a person.

What boyscout-rule does

boyscout-rule is a plugin for Claude Code, Codex and OpenCode 2, under the MIT licence.

session ── hooks notice ───────► skill decides ──► worktree ──► draft PR
           failed, then fixed       lesson / small fix / repo skill
           user correction          (fix ≤ 20 lines, own worktree)
           repeated sequence

Hooks watch for three signals:

  • A command fails, and a different command for the same program works within the next five commands. Read-only commands such as ls, grep and git do not count.
  • I correct the agent: “no, …”, “I told you”, “that’s wrong”.
  • The same sequence of three or more commands runs twice.

When one fires, the hook adds one sentence to the agent’s context. For the first signal it reads:

boyscout-rule: npm failed and a different npm command then ran. If a repo doc, script or instruction pointed you to the failing form, fix that source with the boyscout-rule skill.

That is all a hook does. The engine is 675 lines of Python with no dependencies and no model call. It never blocks a command, sends at most three of these sentences per session, and keeps counters and hashes only, never prompt text or command output. On my laptop a call takes about 26 ms.

The decision belongs to a skill. It accepts three kinds of finding, and only ones the agent verified during the session:

  • A lesson. An instruction, doc, script or config sent the agent or me the wrong way.
  • A small fix. A self-contained defect next to the work, under about 20 changed lines.
  • A repo skill. A procedure of three or more steps that worked and will come up again. If the procedure is deterministic it becomes a script plus one line of documentation, for the reasons in A skill is not a markdown file.

It skips personal preferences, facts about one machine, guesses, and the task I actually asked for. If I asked the agent to fix a failing test, that failure is my task and it does not get a side PR.

Publishing happens in a separate git worktree created from the default branch on origin, so my checkout and my uncommitted work are never touched. The agent confirms the problem exists on the default branch, makes the change, scans the outgoing commits for secrets and for text from our conversation, pushes a boyscout/<session> branch and opens a draft PR. Then it removes the worktree and tells me in one line what it fixed, with the link.

For Claude Code the install is two commands:

claude plugin marketplace add sasa-fajkovic/boyscout-rule
claude plugin install boyscout-rule@boyscout-rule

The steps for Codex and OpenCode are in the README.

The decisions behind it

Hooks point, the model decides. A regular expression can see that a command failed and a different one worked. It cannot tell whether a doc caused that or the agent mistyped. So the hook only raises the question, and “do nothing” is a valid answer. The sentence sent after a correction says so itself: “if it was a personal preference, do nothing.”

A draft PR and nothing else. A commit to the default branch has no review. An issue is one more item nobody picks up. A pull request carries the diff, the reason and the evidence, and a person decides. The description has to name the commands that failed and the ones that then worked. It is a draft because nobody asked for it.

Small on purpose. A fix is capped at about 20 changed lines. A session gets one PR, and a new one starts once that PR passes about 100 lines. Anything bigger gets one line to me and no PR. I will read a five-line diff between two other things. I will not read a refactoring I did not expect.

GitHub is the only state. The plugin keeps no list of what it has proposed. Before publishing, the agent reads the open boyscout/* PRs and skips a finding that one of them already covers. It also reads the closed, unmerged ones and treats those as rejected. Closing a PR is how I say no, and I only have to say it once.

A narrow standing permission. Installing the plugin is my permission to push boyscout/* branches and open draft PRs. It never pushes to the default branch, force-pushes, merges or closes a PR, and it never forks the repository or changes a remote. In a fork with an upstream remote it reports the finding and publishes nothing. In CI pipelines, which set the CI variable automatically, the hooks do nothing.

Native memory off. The plugin warns at session start while the harness’s own memory is on. Automatic memory keeps what the agent learned with the agent. I want the problem fixed at its source, where everyone who works in the repository benefits, which is usually the whole team.

What it did in my own repositories

Over ten days, agents working in five of my repositories opened 22 pull requests from boyscout/* branches. 21 are merged and I closed one.

The median PR changed 4 lines. Twenty of the 22 stayed at 20 changed lines or fewer.

Most of them corrected a README, an AGENTS.md or a skill. In the repository behind this website, one fixed the port in the README and, in the same PR, a session time in my previous post that was ten minutes off from the conference programme. Others were code:

One of the 22 was 130 lines across seven files. I merged it, but a change that size should be a conversation first. Under the current rules the agent tells me about it in one line and opens no PR.

No cleanup project

The usual way to fix a repository that has drifted is a project. Someone writes a ticket for a docs overhaul or a refactoring, it waits until there is time, and when it finally runs it is large, hard to review, and out of date again a few months later.

The Boy Scout Rule works the other way. Each change is small enough to review between two other things. It lands while the problem is fresh, and it comes from whoever just hit the problem. No single PR matters much. Together, the 22 fixed a port, a Docker build, an upload limit and a CI job that skipped lint, and none of it was planned.

The repository gets better as a side effect of working in it. The only cost is the review.

Limits

  • Detection is pattern matching. The correction signal is a list of English phrases. Say it another way, or in another language, and the hook misses it. The agent still has its instruction from session start, but nothing prompts it at that moment.
  • Hooks see shell commands and my prompts. A wrong path the agent finds by reading files produces no signal.
  • Publishing goes through the GitHub CLI, gh, so today it works with GitHub only. Nothing in the idea depends on GitHub, and the skill should work the same way with GitLab or Bitbucket.
  • On native Windows only the session-start part works. Codex skips the hooks until you trust them in /hooks, and again after every plugin update.
  • It produces review work. Twenty-two PRs in ten days is twenty-two things I had to read. They were short, but the queue is real.

The objections I expect

This is what AGENTS.md is for. Yes, and that is where many of these PRs land. The plugin adds no new place to store knowledge. It is a write path, with review, to the files the team already has.

Unrequested PRs are noise. Three nudges per session, one PR per session, drafts only, duplicates skipped, rejections remembered. If a repository still gets a PR from every session, its docs are wrong that often, and I would rather know.

I do not want an agent pushing to my repo unasked. Then do not install it. That is a reasonable call for some repositories. What it may do is listed above, and the list is short. In Claude Code the git and gh commands still go through the normal permission prompts unless your rules already allow them.

The vendors will fix memory. They are improving it, and it will stay per vendor. The plugin runs on three harnesses, and the repository is the one place all of them read, along with the people on the team.

If you run the team

Stale docs are a cost that appears in no report. It used to show up as onboarding time. With agents it also shows up as the same wrong turn taken in every session, by every engineer’s agent, paid for in tokens each time.

Per-person memory hides this instead of fixing it. An engineer who has corrected their agent for six months has an agent that knows the repository. The person who joined last week has one that knows nothing. The gap that used to sit between people now also sits between their tools, in files nobody else can read or review. I made the same argument about AI employees: a correction should improve the system for the whole team, not only for whoever typed it.

The Boy Scout Rule always depended on people having a few spare minutes in the middle of other work. An agent does not need them. What it needs from the team is review, so that is the norm to set: a boyscout PR gets read within a day and is merged or closed. Forty unread drafts are the same stale-docs problem, moved to the PR list.

The PR list is also a measurement you did not have before. The repositories that collect the most lessons are the ones whose docs have drifted furthest.

Where I stand

What an agent learns about a repository is a change to that repository, and it should go through the same review as every other change. The plugin is on GitHub.

If you are at the GDS Herbsttagung in Berlin on 19 November, or at the DACH summit in Frankfurt on 3 and 4 December, tell me what your agents learned last week and where it ended up.

Back to Blog