DEV Community: Manpreet Singh

AGENTS.md vs CLAUDE.md: Claude Code reads both now, just not at once.

Manpreet Singh — Mon, 05 Oct 2026 12:00:31 +0000

Two files, one job: tell a coding agent about your repo. For a year the answer to "which one?" was simple. Claude Code read CLAUDE.md. Almost everything else read AGENTS.md. If you used both kinds of tool, you kept two files and watched them drift apart.

On 18 September that changed. Claude Code 2.1.277 started reading AGENTS.md natively. Some of the top results for this question still say it doesn't.

Claude Code reads AGENTS.md now. But only when there's no CLAUDE.md, and a single CLAUDE.local.md switches it off.

Here's the current picture, the one setup that works on every version, and the part none of the comparison posts measure: what the file costs you on every turn, and what's missing from it.

The short answer

From Anthropic's memory docs, as of today:

Claude Code reads AGENTS.md only when there's no CLAUDE.md. That means no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the folder you're working in or any folder above it. Your personal ~/.claude/CLAUDE.md doesn't count, so that still loads alongside.
The trap. Add a CLAUDE.local.md for your own notes and your team's AGENTS.md quietly stops loading. Nothing tells you.
You can change the rule. In /config, "Project instructions" can be set to read either file (the default), both, or only CLAUDE.md.
Nearly everything else reads AGENTS.md. Codex, Cursor, Copilot, Jules, Amp, Windsurf, Zed and more, per the list at agents.md. Gemini CLI is the odd one out: it reads GEMINI.md unless you point it elsewhere.

One more thing to check before any of that applies to you:

$ claude --version
2.1.257 (Claude Code)

That's the CLI on my own machine. It's older than 2.1.277, so here an AGENTS.md on its own would be invisible to Claude Code, whatever the docs say. If your team updates at different speeds, some of you are reading the file and some aren't.

Which one should you use?

Only Claude Code touches the repo? Keep CLAUDE.md. There's no AGENTS.md in this website's repo, because Claude Code is the only agent that works on it. A second file would be a second thing to keep true.

Several tools, or a team on mixed versions? Make AGENTS.md the one real file, and make CLAUDE.md a single line:

@AGENTS.md

That's the setup Anthropic's docs recommend. Claude Code pulls the file in and never loads it twice, and it works on old versions too, because it doesn't depend on the new support at all. Two details that trip people up: an import inside a code fence is silently ignored, and on Windows a symlink instead of an import needs admin rights or Developer Mode, and Claude's own edit tools refuse to write through one.

What not to do is keep two hand-maintained copies. On the long-running GitHub issue asking for AGENTS.md support, it's a recurring complaint: the copies drift, and each agent ends up following different rules.

What the file costs you

Whichever file you pick, it's read at the start of every session and then sent again on every turn, like everything else in the conversation. So its size isn't a one-off. Here's this repo's CLAUDE.md, checked by a small linter:

$ npx -y github:manpreet171/bridle agents CLAUDE.md
Linting CLAUDE.md

  ✔ 2 runnable command block(s)
  ✘ does not say how to install / set up
  ✘ does not say how to run the tests
  ✔ how to build or run it
  ! 3 angle-bracket field(s), e.g. <slug> — check these are argument syntax, not unfilled template text
  ✔ nothing in here tells the agent to do something dangerous
  ✔ 12 prohibition(s) — the agent knows where the edges are
  ✔ size: 916 words ≈ 1474 tokens, re-sent every turn

FAIL — 2 problem(s). Your agent is reading this file on every run.

The two failures don't apply here: it's a static site with no install step and no test suite. A general linter checks for a general project, so read it as a list of questions, not a verdict.

The size line is the one that matters. About 1,500 tokens, on every turn. This project has run about 9,300 turns of Claude Code, so this one file accounts for roughly 14 million tokens, sent at the cheaper cached rate. That's an estimate, but the shape isn't. I measured where the rest of a session's tokens go in a separate post.

Does a longer file make the agent worse at following it? Anthropic's memory docs say to aim for under 200 lines, and its best-practices guide warns that bloated files get ignored. The research is more mixed. An ETH Zurich study found files written by people raised success rates slightly, files generated by an AI lowered them, and both added roughly 20% to cost. A study of 1,650 Claude Code sessions found no measurable effect of length on following one simple rule. Length isn't proven to hurt. It is proven to cost.

What's missing from it

A file can be long and still not say the thing you actually need it to. Here's the same project from the other direction: not what the file says, but what I keep typing to the AI because the file doesn't say it.

$ npx -y toldya --dry
toldya · 13 sessions (1 Aug – 5 Oct) · 975 of your messages · 58 corrections

You keep telling your AI:
   1.   7×  keep it simple   (6 sessions)
   2.   3×  Don't confuse me   (3 sessions)

And 8 times you told it to try or check again: its first go missed.

916 words of rules, and neither line is in there. The two corrections I gave most often in this repo had never been written down, so every new session started without them and I typed them again.

That's the real answer to "which file?". The name decides which tools read it. What's in it decides whether it was worth reading.

What belongs in it

What it can't work out on its own. The odd build command, the folder that looks unused but isn't, the deploy that happens on push.
The edges. What it must never touch, and what needs a person. Those are the lines that prevent damage.
What you keep correcting. If you've typed it three times, it's a rule. Write it in your own words.
Not documentation. Explaining the codebase is what the code is for. Every paragraph the agent could have read in the repo is a paragraph you pay for on every turn.
Not generated filler. The ETH study's sharpest finding was that AI-written context files made results worse. Write it yourself, briefly.

Check your own

$ claude --version                             # 2.1.277 or later to read AGENTS.md
$ npx -y github:manpreet171/bridle agents CLAUDE.md   # or AGENTS.md
$ npx -y toldya --dry                          # what you keep repeating

Both tools are free, read only your own files, and change nothing unless you say yes. bridle reads the instruction file; toldya reads your Claude Code history.

This is how we set agents up for clients. One short file that says what the agent can't guess and where the edges are, checked against what people actually keep correcting. Not a template, and never a generated one.

Sources: every terminal block is a real run in this website's repo on 5 Oct 2026, the toldya one trimmed by one line (a link). Loading rules are from Anthropic's memory docs and the Claude Code changelog for 2.1.277. Tool support is from agents.md. The studies are arXiv 2602.11988 and arXiv 2605.10039.

Originally published at singhlabs.dev.

Claude Code says it's done. Check the diff, not the paragraph.

Manpreet Singh — Mon, 05 Oct 2026 11:58:50 +0000

"Done. All tests pass, and nothing else was touched." You read it, it's late, you merge.

Claude Code's own issue tracker is full of what happens next. A test suite whose total quietly changed from 4,992 to 4,966 before the "ALL PASSED". Six tests marked skip. A project reported 100% complete that an audit put nearer 60%.

The summary isn't a lie. It's written to explain the work, and nobody explains the parts they'd rather you didn't see.

Asking the agent to try harder doesn't fix that. Checking does. Here's what goes wrong, what doesn't work, and what happened when I held this site's own Claude Code summaries up against their real diffs.

The four ways "done" isn't done

Read enough of those issues and the same four shapes keep coming back:

The tests got easier, not the code better. A test skipped, an assertion loosened, a test command narrowed to the ones that pass. The suite is green because there's less of it.
The count got reframed. A failure becomes "a flaky timeout". A smaller total gets reported as everything passing.
Intent got ticked off as work. A to-do marked done because it was planned, or a stub counted as a feature.
A file changed and never got mentioned. The quietest one, and the one that bites three days later.

It's common enough to measure. A study of 20,574 real agent sessions found inaccurate self-reporting was about 23% of all the misbehaviour it caught, and a growing share over time. Anthropic's own best-practices guide says it plainly: Claude stops when the work looks done.

What doesn't work

Asking "did you actually do it?" The same model that wrote the summary checks it with the same blind spot. In one report it said yes three times.

A rule in CLAUDE.md. One reporter had a 250-line file, memory notes and hooks, and still got false "done"s. In another, the rule against skipping tests was right there in context and got broken anyway. A rule asks. A check doesn't need to.

What I found in my own sessions

Most writing on this describes the problem. Almost none of it shows a real summary next to its real diff, so I did that with two pieces of work Claude Code finished on this website today. For each one I took the summary it gave me at the end, word for word, and ran it through plumb, a small tool that holds a summary against git diff and prints only what doesn't match.

The first was publishing a blog post, along with a fix to a script:

$ plumb check summary.md --base a12ccca
plumb — 9 files changed, 1 named in the summary

changed but never mentioned  (read these first)
  · .assetsignore modified
  · LOG.md modified
  · assets/blog/og-claude-code-token-usage.png added
  · baggage/index.html modified
  · blog/claude-code-token-usage/index.html added
  · blog/feed.xml modified
  · blog/index.html modified
  · sitemap.xml modified

8 things the summary did not tell you.

Eight flags. I went through them one by one. Seven were things the summary did describe, just not by file name: it gave the post's URL, called the image "the social card", and said "that folder is now excluded from publishing" instead of naming .assetsignore.

One wasn't. baggage/index.html: Claude added a link to a product page while publishing the post, and the summary never said so anywhere. Harmless, as it happens. But I only know it's harmless because I looked.

The second was a batch of SEO fixes: 21 files changed, and again only one named by path. This time the summary described all 20 others in categories, "19 pages and the sitemap", and every one checked out. plumb also flagged two files as "mentioned but not changed", which the summary had only referred to. Nothing was missing.

So, across two real summaries: 30 files changed, 2 named by path, one change genuinely left out. No skipped tests, no removed guards. Neither summary lied. One still hid a change, and I'd have merged it without blinking.

What actually works

Read the diff, not the paragraph. /diff in Claude Code, or git diff --stat, shows every file that changed. The summary is a guide to the diff, never a replacement for it.
Make it end with a file list. Ask for every file it touched, by path, at the end of each task. My two summaries were noisy to check because they talked in categories. A list turns "did it mention everything?" into a mechanical question.
Check on every stop, automatically. Claude Code's Stop hook receives the agent's last message, so a check can run the moment it says it's finished. trust issues is a free plugin that does exactly that: the same four checks, every time, with nobody remembering to run them.
Count the tests, before and after. If the number went down, ask why before you read anything else.
Get a second pair of eyes that didn't do the work. Anthropic's guide suggests a separate verification step that checks nothing outside the task changed. A fresh session doesn't share the first one's reasons for skipping a test.

Try it on yours

Save the agent's last message to a file, then:

$ npm install -g github:manpreet171/plumb
$ plumb check summary.md                # against your uncommitted changes
$ plumb check summary.md --base main    # against a branch or commit

Exit code 1 means it found something, so it works as a CI gate too. What it won't do, so you don't over-trust it:

It matches names literally. A URL or a category doesn't count as a mention, which is why my first run flagged seven things that weren't really missing. Ask for a file list and that noise goes away.
It can't tell whether the code works. It finds what was left out of the story, not bugs. Run the tests for that.
Its "quiet cuts" are patterns. It spots a removed assertion or an added .skip, not every possible way to weaken a check.

This is how we build agents for clients. Nothing gets called done because the agent said so. Every run ends with what changed, and something other than the agent checks it.

Sources: the plumb output is a real run (plumb 1.1.0) on 5 Oct 2026, against the exact end-of-task summary Claude Code gave for each piece of work, with the summary file's path shortened. The second run's output is described rather than shown because it lists 20 files. Incidents are from the linked GitHub issues on anthropics/claude-code; the session study is arXiv 2605.29442; hook and review guidance is from Anthropic's best practices and hooks docs.

Originally published at singhlabs.dev.

Where your Claude Code tokens actually go. Output is 0.2%.

Manpreet Singh — Mon, 05 Oct 2026 11:38:18 +0000

You hit the usage limit before lunch. So you do what everyone online says: make the AI talk less. Ban the "Great question!", cut the summaries, install one of the skills that trims its replies.

I wanted to know where the tokens actually go, so I counted. Not estimated. Counted, from the transcripts Claude Code already keeps on your machine: every session still on mine, 173 of them, about 60,000 turns.

Everything Claude wrote back to me was 0.2% of the tokens. The rest was my own session, fed back in.

That number is real, but it isn't the whole story either, because most of those re-sent tokens are cheap ones. This post is both halves: where the tokens go, what they really cost, and the few things that actually move the number.

The count

Here's the summary across every project, straight from the terminal:

$ baggage --all
baggage — 173 sessions, all projects, 60,454 turns

  before you typed anything              75k  tokens
    system prompt, every tool schema, every skill, CLAUDE.md.
    paid again on all 60,454 turns = 4.5B tokens, 17% of the bill,
    whether you called any of it or not.

  conversation you can see             27.8M  tokens
  what the API billed                  26.0B  tokens

  a 934x gap. Some of it is the fixed cost above; the rest
  is everything you picked up being re-sent on every later turn.

  output tokens           56.6M   0.2%
  re-sent context         25.3B   97.5%   <- the bill

Two lines matter. Output (every reply, every line of code Claude wrote, its thinking included) is 56.6 million tokens. Re-sent context is 25.3 billion. That's roughly 450 to 1.

I'm not the first to see this shape. A GitHub issue on Claude Code found the same thing in 30 days of someone else's transcripts, and a dev.to post measured 0.5% output across 32 sessions. Different people, different work, same picture. What none of them show is which things in a session cost the most, and what any of it means for the bill. That's the rest of this post.

Why it works like that

The model has no memory between turns. Every time you press enter, Claude Code sends the whole conversation again: the system prompt, the tool definitions, every file it read, every command output, every reply so far, and then your new message.

Think of a suitcase you have to carry up every flight of stairs. Pack a brick on the second floor of a 200-floor building and you carry it up 198 more flights. A 4,000-token build log that lands at turn 12 of a 200-turn session isn't 4,000 tokens. It's 4,000 sent 188 more times.

So the cost of anything in a session isn't its size. It's its size times the number of turns it stays.

Caching makes it cheaper, not smaller

This is the part most guides get half right. Claude Code caches the conversation, and Anthropic prices a cache read at a tenth of normal input (a twentieth on Opus 5.5, a fortieth on Fable 5.1). Output costs five times input. So 97.5% of the tokens is not 97.5% of the money.

I priced my own split at those published rates, with the one-hour cache a subscription uses. Output comes to 7 to 14% of the cost, depending on the model. Re-reading and re-caching the session is the other 86 to 93%.

Less dramatic than 0.2%. Still the opposite of what "make it talk less" assumes.

On a Pro or Max plan you never see dollars, you see a limit. Anthropic's cost docs say re-read history still draws on your usage, at the cached rate, so a one-line question late in a long session draws usage for the whole session. How heavily a cached token counts against the limit isn't published. I've seen people online insist it's full weight, and others insist it's free. Nobody I found has shown either, so I'm not going to guess.

The floor you pay before you type

That first block of the output is the one nobody shows you. Before you've typed a word, a session already carries the system prompt, the built-in tools, the descriptions of every skill you've installed, your CLAUDE.md files and anything else that loads at start. A typical session on my machine starts at about 75,000 tokens.

It rides along on every turn. Across all my sessions, that floor alone is 17% of everything billed, whether I used any of it or not. It's also the one line you can fix in thirty seconds: every paragraph of CLAUDE.md you don't need is paid again on every turn of every session, and so is the description of every skill you never call.

The heaviest things I carry

Here's one project, this website, with the list of what's costing the most rent, trimmed for length:

$ baggage
baggage — 13 sessions in singhlabs, 9,307 turns

  before you typed anything              84k  tokens
    system prompt, every tool schema, every skill, CLAUDE.md.
    paid again on all 9,307 turns = 779.0M tokens, 18% of the bill,
    whether you called any of it or not.

  output tokens            7.1M   0.2%
  re-sent context          4.2B   98.0%   <- the bill

  HEAVIEST THINGS YOU ARE STILL CARRYING
  (rent = its size x the turns it stayed in context)

   304.4M   19.4%  3769x  assistant reply
   282.4M   18.0%  1376x  your message
   244.2M   15.6%  1415x  claude-in-chrome · browser_batch
    54.6M    3.5%   145x  WebSearch
    25.6M    1.6%   275x  claude-in-chrome · javascript_tool
    21.5M    1.4%    17x  claude-in-chrome · get_page_text
    14.9M    0.9%   159x  Agent

Two things surprised me.

Claude's own replies are the biggest line: 19.4%. Not because they were expensive to write. Writing all of them was part of the 0.2%. They're expensive because each one stays in the session and is sent again on every turn after it. So the "talk less" skills aren't wrong. They're right for the wrong reason: a short reply saves you far more in re-sends than it ever cost to write.

Browser automation is close behind: 15.6%. And that's the text alone: page contents, element lists, logs of each click. baggage doesn't count images, so every screenshot rides along on top of that figure, uncounted. A session that clicks through a website carries a stack of pictures of it.

What actually moves the number

Ranked by what the counts above say, not by what's easiest to write about:

Start fresh between unrelated tasks. /clear drops everything you've been carrying, and Anthropic's docs say it costs nothing. The brick stays on floor two.
Lower the floor. Uninstall skills you don't use, keep CLAUDE.md to what Claude can't work out on its own, and run /context once to see what loads before you type.
Keep big output out of the main session. Send a long log to a file and search it, instead of printing it into the chat where it's carried to the end. Hand noisy exploration and browser work to a subagent, so only its answer comes back.
Don't break the cache mid-session. Per the caching docs, switching model, changing effort, turning on fast mode or changing MCP servers can throw it away, and then the whole session is written to cache again at the higher rate. Decide those at the start.
Shorter replies, for the right reason. Ask for the answer without the essay. It helps, because the essay gets carried.

On a paid plan, /usage now shows which skills, subagents and MCP servers used your allowance. Worth a look before changing anything.

Count your own

The tool that printed everything above is called baggage. It's free, it reads the transcripts already on your machine, and nothing leaves it. The name on npm belongs to someone else, so install it from the repo:

$ npm install -g github:manpreet171/baggage
$ baggage          # this project
$ baggage --all    # every project

What it doesn't tell you, so you don't over-read it:

Tokens, not dollars. The totals are the exact counts the API reported. Pricing them is your model and your plan.
Item sizes are estimates. The list ranks things with a rough four-characters-a-token ruler, the same ruler for everything. The totals above it are exact.
Only what's still on your machine. Claude Code keeps about 30 days of history by default.
One heavy user. These are my numbers. Yours will differ, which is the point of running it.

This is how we work. Measure what's really happening before changing anything, then change the thing the numbers point at. It's the same rule we use when an AI system we build for a business starts costing more than it should.

Sources: both terminal blocks are real baggage runs on my own machine on 5 Oct 2026, the second trimmed to whole lines for length. Prices and cache multipliers are from Anthropic's pricing page; the cost split weights my exact token counts by them. Cache and usage behaviour is from Claude Code's costs and prompt caching docs.

Originally published at singhlabs.dev.

You gave AI your documents. It's still wrong. Here's how to find out why.

Manpreet Singh — Mon, 05 Oct 2026 10:55:30 +0000

You upload your company handbook, or a folder of PDFs, or two years of notes. You ask it something the document plainly answers. It answers confidently, and it's wrong.

Then you do what everyone does. You rewrite the question. You add "only use the document provided". You try a better model. Sometimes it works, and you never find out why.

There's a way to find out why, and it takes about twenty minutes. Nothing to install, nothing to buy, no account.

First, what's actually happening

When you point an AI at your own documents, it doesn't read them the way you do. It can't — they're far too long to hold at once.

So the tool does something simpler than you'd expect:

It cuts your documents into small pieces. Usually a few hundred characters each.
When you ask a question, it picks the piece that looks most similar to your question.
It shows the AI that piece, and asks it to answer.

The AI never sees your document. It sees one piece of it, chosen by a search you didn't configure and can't watch.

This is the actual situation. The scrap is what it answers from. The stack is everything it never saw.

Almost every wrong answer is decided at step 2, before the AI is involved at all. Which means arguing with the AI can't fix it.

The industry name for this arrangement is RAG. You don't need the term. You need to see step 2.

A worked example you can run

Here's a short leave policy. Forty lines of Python, no installs, no key — it does steps 1 and 2, then stops and shows you what the AI would have been given.

Save it as check.py and run python check.py:

# Shows what your AI actually gets handed when you ask about your documents.
# Python 3. Nothing to install, no API key, no account.

CHUNK_SIZE = 350          # <-- change this number and run it again

DOCUMENT = """
Annual leave

Every full-time employee gets 24 days of annual leave a year, plus public
holidays. Leave is counted from 1 January.

Requests go through the HR portal. Your manager approves them. If your manager
is away, their deputy approves instead.

How much notice you need to give depends on how long you are taking off. For a
single day, give two working days of notice. For anything up to a week, give
two weeks of notice. For longer than a week, give one month of notice.

Carrying leave over

You can carry a maximum of 5 unused days into the next year. Anything above 5
days is lost on 31 December. Carried days must be used by 31 March.
"""

QUESTION = "how much notice do I need to book a week off?"


def chunk(text, size):
    words, chunks, current = text.split(), [], ""
    for w in words:
        if len(current) + len(w) + 1 > size:
            chunks.append(current.strip())
            current = ""
        current += w + " "
    if current.strip():
        chunks.append(current.strip())
    return chunks


def score(text, question):
    stop = {"how", "much", "do", "i", "need", "to", "a", "the", "for", "of", "is"}
    q = {w.strip("?.,").lower() for w in question.split()} - stop
    c = {w.strip("?.,").lower() for w in text.split()}
    return len(q & c)


chunks = chunk(DOCUMENT, CHUNK_SIZE)
ranked = sorted(range(len(chunks)), key=lambda i: score(chunks[i], QUESTION), reverse=True)

print(f"chunk size {CHUNK_SIZE} -> {len(chunks)} pieces")
print(f"question: {QUESTION}\n")

for rank, i in enumerate(ranked, 1):
    print(f"  #{rank}  piece {i}  score {score(chunks[i], QUESTION)}")

print("\nThis, and only this, is what the AI gets:\n")
print(f"  {chunks[ranked[0]]}\n")
print("Read it. Could you answer the question from that alone?")

The document says, in plain English, that a week off needs two weeks of notice. Here's what comes back:

$ python check.py
chunk size 350 -> 2 pieces
question: how much notice do I need to book a week off?

  #1  piece 0  score 2
  #2  piece 1  score 2

This, and only this, is what the AI gets:

  Annual leave Every full-time employee gets 24 days of annual leave a year, plus
  public holidays. Leave is counted from 1 January. Requests go through the HR
  portal. Your manager approves them. If your manager is away, their deputy
  approves instead. How much notice you need to give depends on how long you are
  taking off. For a single day, give two

Read it. Could you answer the question from that alone?

Look at the last five words.

For a single day, give two — and then the text stops. The sentence was cut in half.

An AI handed that will answer "two days", fluently and with no hedging. It isn't hallucinating. It's answering correctly from the only evidence it was given. The evidence was just the wrong half of a sentence.

And notice the scores: both pieces scored 2. It was a tie. The wrong one won because it happened to come first.

Now change one number

Set CHUNK_SIZE = 300. Same document, same question, same code:

$ python check.py
chunk size 300 -> 3 pieces
question: how much notice do I need to book a week off?

  #1  piece 1  score 3
  #2  piece 0  score 1
  #3  piece 2  score 0

This, and only this, is what the AI gets:

  long you are taking off. For a single day, give two working days of notice. For
  anything up to a week, give two weeks of notice. For longer than a week,
  give one month of notice. Carrying leave over You can carry a maximum of 5
  unused days into the next year. Anything above 5 days is lost on 31

Read it. Could you answer the question from that alone?

Correct. Because the piece boundary landed somewhere else.

Here is every size I tried:

chunk size   pieces   answer correct?
       150        5   yes
       200        4   NO
       250        3   yes
       300        3   yes
       350        2   NO
       400        2   NO
       450        2   yes
       500        2   yes

That isn't a curve you can tune your way along. It's arbitrary. Right, wrong, right, right, wrong, wrong, right, right.

A number you never chose, and probably never saw, decided whether your answer was true. Not the model. Not your prompt.

The test

That's the whole point of the exercise, and it generalises. Whatever tool you're using, before you touch the prompt:

Find what the tool actually retrieved. Most of them will show you — it's called sources, citations, references, or context. Open it.
Read that text yourself. Ignore the answer entirely.
Ask one question: could I have answered correctly from this text alone?

That single question splits every wrong answer into two completely different problems:

No, I couldn't have — then the AI never stood a chance. The retrieval is broken. Rewriting your prompt is wasted effort, and this is where most people spend their afternoon.
Yes, I could have — the answer was right there and the model went past it. A genuinely different problem, with a different fix.

Twenty minutes. No framework, no monitoring platform, no spend.

If it's the first one

Things that actually help, roughly in order of effort:

Ask for more pieces at once. Most tools fetch one. Three or five means a cut sentence gets rescued by its neighbour.
Cut on meaning, not on character count. Split at paragraphs and headings. A rule that ends a piece mid-sentence will eventually end one mid-answer.
Keep the heading with the text. A piece that says "give two weeks of notice" without "Annual leave" above it can't be matched to a question about leave.
Don't rely on similarity alone. Plain word matching catches the things similarity misses — product codes, error numbers, names. Using both together is now the ordinary recommendation, not an advanced one. NovaKit make the case well, and kapa.ai list the other common mistakes.

Those guides are good and I'd read both. What none of them gives you is the part above: which of the five things is yours. They hand you a list of suspects. The read-it-yourself test hands you a defendant.

The thing nobody tells beginners

Every article on this ends at "improve your retrieval". Fair enough. But there's a step past it, and it changes how you think about the problem.

Better chunking makes wrong answers rarer. It never makes them impossible. You're tuning a dial and hoping.

On a system I built — a multilingual assistant answering questions across about 75,000 lines of source — we stopped tuning the dial. Every claim in every answer had to resolve to a real, checkable location in the source material. If a citation didn't resolve, the answer didn't ship. Not flagged. Not scored. Withheld.

The goal isn't an AI that's usually right. It's a system where being wrong is structurally impossible, because a claim it can't back up never reaches you.

Checked against the source, or it doesn't get handed over. Withheld, not flagged.

That's a design decision, not a setting, and it's the difference between a demo and something people can rely on at work. You don't need it on day one. But it's worth knowing the ceiling exists, so you stop expecting prompt changes to get you there.

Start here

Next time your AI gets your own documents wrong, don't rewrite the question.

Look at what it was given, and ask whether you could have answered from it.

Most of the time you couldn't have — and the machine you were about to blame was the only part doing its job.

Check #2 above is one of eight. I've put the rest on a single printable page — the things worth thirty seconds before you act on what an AI told you. Free, no signup: Before you trust an AI answer →

I build this kind of thing for a living, and I give away the tools that check it — all of them here, free and readable. What I've built · work with me.

Run the script on your own document and something surprising falls out? Tell me — I collect these.

Originally published at singhlabs.dev.

What is Jev? The AI trained to say “I'm only 60% sure.”

Manpreet Singh — Mon, 05 Oct 2026 10:52:40 +0000

I kept hearing the word. Jev. In group chats, in newsletters, in a Hacker News thread that hit 1,900 points and 500 comments in a day — which for that site is a small riot.

Every explanation I clicked on was written for engineers. Non-autoregressive. Calibrated posteriors. Typed schemas. I understood maybe half.

So I read the launch post, the docs, and all 500 comments. Underneath the jargon is a simple idea, and a slightly funny one.

Every AI you've used so far writes. Jev doesn't. Jev decides.

Stick with me. By the end you'll be able to explain it to a friend in one sentence, you'll know what the “can't hallucinate” claim actually means (not what it sounds like), and you'll know whether it ever touches your life. It will. You won't see it.

The one-sentence version

Think about the difference between an essay and a light switch.

ChatGPT, Claude, Gemini — they write essays. You ask, they produce words, one after another, and the words can be anything. A poem. A recipe. Working code. A confident lie. That flexibility is the magic and the problem.

Jev is a light switch. You don't ask it to talk. You show it a situation and ask a fixed question with a fixed set of answers — is this urgent, yes or no? which of these five teams handles it? how angry is this customer, one to five? — and it flips the switch. Instantly. And next to the switch it puts a number: how sure it is.

It cannot write you a sentence. That isn't a limitation they're fixing; it's the design. The people who built it gave up words on purpose, because they think most of what businesses want from AI isn't words. It's decisions.

Why it's called that

Two names, both borrowed from smart dead people, and both help.

“System One” is Daniel Kahneman's. He split thinking into two modes. System 2 is slow and careful — doing your taxes. System 1 is fast and automatic — you see a face and know it's angry before you could explain why. You don't reason your way there. You just know, and you're usually right.

Chatbots are being pushed towards System 2 — “think step by step”, reasoning modes, minutes of pondering. Jev is built for System 1: the thousand tiny snap judgements that happen inside software all day. Is this spam? Is there a person in this photo? Which folder does this go in? Nobody wants an essay about it. They want the answer, fast, and they want to know if it's reliable.

“Jev” is after William Stanley Jevons, the economist who noticed that when steam engines got more efficient, people didn't use less coal. They used vastly more, because cheap power made a thousand new things worth doing. The founders are betting the same happens when a decision costs almost nothing. That's the whole business plan, in a name.

The founder is Diogo Almeida, who was at OpenAI on the research that taught language models to follow instructions — the work that became ChatGPT. So: someone who helped build the essay machine, deciding the next thing shouldn't be one. The company, TypeSafe AI, reportedly raised $40 million to do it.

What you actually send it

A real example from their documentation. It's the moment it clicked for me.

You give Jev a situation — they call it “state”. Say, a support message:

“Hi, I've been trying to connect my Stripe account for 3 days and it keeps failing. I'm losing sales. Please help ASAP.”

And a question with a fixed shape. Here, a yes/no: does this message convey urgency?

What comes back is not a paragraph. It's this:

is_urgent: 0.999

A number. 99.9% yes. Your software reads it and acts — bumps the ticket, pings a human, whatever you've set up. No “Certainly! This message appears to be…” to wade through.

There are only three kinds of question you can ask:

Yes or no. Returns the probability of yes.
Pick one from a list. Returns a probability for every option, plus an overall confidence. Up to 255 options.
Score it on a scale. Low/medium/high, one to ten, whatever you define. Returns the score, the spread, and the confidence.

The trick that makes it fast: you can ask dozens of these about the same situation at once, and it answers all of them in a single pass. A chatbot builds its answer one word at a time, each depending on the last. Jev builds nothing. It looks once and flips every switch at the same time.

Here's the difference as a picture:

A chatbot answers word by word. Jev answers every question at once.

That's why the speed numbers are wild. They claim 70 to 500 milliseconds per answer against the three seconds to five minutes a reasoning chatbot takes. And pricing: $0.042 per million words of input, output free, because the output is a handful of numbers. Someone on the team built a bot that plays Doom by asking Jev ten questions a second. About $7 an hour. The team's reaction was that this was cheaper than they expected.

Honest note: those are TypeSafe's own numbers, from their own laptops, on tasks they chose. I haven't run it — it's early access with a waitlist. More on what independent people made of the claims below.

The claim everyone repeats

Every headline says the same thing: Jev can't hallucinate.

This is true. It's also not what you think it means, and the gap between those two is the most useful thing in this post.

A chatbot “hallucinates” when it confidently produces something false — a fake court case, a made-up statistic, a function that doesn't exist. It can, because it can write anything. The space of possible outputs is infinite, and some of that space is nonsense.

Jev can't write anything. You gave it a menu. Yes or no. One of these five teams. A number from one to ten. It is mathematically impossible for it to hand you something that isn't on the menu. No fake court case, because “fake court case” was never an option.

But it can absolutely pick the wrong thing off the menu.

If the message wasn't urgent and Jev says 0.9 urgent, that's a wrong answer. Not a hallucination — a mistake. Several of the sharpest people in that thread made exactly this point: it can't emit an invalid answer, but it can still emit a completely wrong valid one.

So why is it still a big deal? Because of the number. Here's the honest version on one card:

The new part isn't the left card. It's the number on the right — trained to be honest.

What TypeSafe actually built — the new part — is that Jev is trained to make that confidence number honest. Their training method is literally called Reinforcement Learning for Calibrated Decisions. Calibrated means: when it says 90%, it should be right about nine times in ten. When it says 55%, it should be a coin flip, and it should say so.

Their own post puts the problem perfectly: “If a model can do a task 95% of the time but doesn't say when it's in the 5%, it can't automate that task.” That's the whole reason AI has been stuck in “assistant” mode instead of “just do it” mode. Not that it's wrong 5% of the time — that you can't tell which 5%.

There's good research showing chatbots make people more confident and less accurate, because they never say “I don't know”. Read that sentence again with Jev in mind. This is an AI whose entire training objective is to say how unsure it is. Whether it lives up to that, nobody outside the company has tested yet. But it's the right thing to be trying to build.

What the sceptics said, in plain words

Five hundred comments. The best ones, translated.

“This already existed.” True-ish. Machine learning has had classifiers for years — models that take input and output a probability, fast, no words. Your spam filter is one. What's new, several people concluded, is that you don't have to train one per job. You describe the menu in plain English and it works immediately. One commenter called it “democratisation of classifiers”. Fair, and still a big deal — training a classifier used to need an ML engineer and a pile of labelled data.

“The speed comparison is apples to oranges.” Also fair. Jev is 200× faster than a chatbot at flipping switches. A chatbot can also write code, draft your email, and explain the switch. Comparing them on speed is like saying a light switch is faster than a novelist.

“Their evals grade against other AIs, not against truth.” This one matters. TypeSafe's benchmark checks how closely Jev's decisions match the average of GPT-6 and Claude's flagship on the same tasks — not how often it is actually right. So “as good as the best models” really means “agrees with the best models”. Those models can be wrong together.

“It's probably a small model, and people will copy it.” One commenter estimated from the price that Jev is around 3 billion parameters — tiny by today's standards — and predicted clones within weeks. Three days after launch, “Cua S1 — a family of System One models” showed up on the same site. The category may matter more than the company.

Credit where it's due: TypeSafe's launch post has a “Nuance” section under every claim, admitting where their numbers flatter them, where bias could exist, and that they can't prove their pricing isn't subsidised. More honesty than most launches manage.

Where you'll actually meet it

You will never open an app called Jev and type at it. That's the point. It's plumbing. It shows up inside things you already use, and the tell will be that AI-powered features get faster and quieter. Here's where it would sit:

Read the last box. The uncertain one goes to a person. That's the pattern this makes possible.

That last box is the bit that affects you. Route to a human when confidence is low. The AI handles the 90% it's sure about; the uncertain 10% goes to a person. Today most AI features either handle everything (and get some wrong, confidently) or nothing.

If it works as claimed, the things that get better are boring. Support tickets to the right person first time. Spam and fraud checks that run in a blink. Game characters that react instead of freezing to think. Photo apps that sort ten thousand images without a queue. Nothing you'd write a headline about. Everything you'd notice if it stopped.

Paragraph or checkbox?

The practical part, and it's for anyone — not just coders. Plenty of people automate things with no-code tools now, and all of them are about to face this choice.

When you're thinking of using AI for a task, ask one question first: is the output a paragraph or a checkbox?

If a human needs to read the answer — a draft, an explanation, a summary — you want a chatbot. If software needs to act on the answer — sort, route, flag, score, approve — you want a decision model, and Jev is the first mainstream one. Here's the whole decision:

Paragraph or checkbox? Which kind of AI your task actually needs.

The smartest comment in the whole thread was about the box in the middle. It's not Jev versus ChatGPT. The likely pattern is both: you use a chatbot to design the questions — what should the menu be? what does “urgent” mean for us? — and the decision model runs those questions a million times in production. The essay-writer designs the switchboard. The switch-flipper runs it.

Who should ignore this

If you use AI to write, learn or think — most people — Jev changes nothing for you today. Carry on.

If you build anything, automate anything, or decide how AI gets used where you work, it's worth twenty minutes on the docs and the waitlist, with expectations set: early access, self-reported numbers, a menu-bound model that can still be wrong, and a category that will have five competitors by Christmas.

And if you just like knowing where this is going — the interesting bit isn't the speed. It's that someone who helped build the most confident machine in history just built one whose job is to admit doubt.

The sentence to tell your friend

“It's an AI that doesn't write anything — you give it a situation and a multiple-choice question, and it picks an answer instantly and tells you how sure it is.”

If they say “so it's a spam filter”, say “yes, but you can build one in a sentence instead of a month.” If they say “so it can't be wrong”, say “it can — it just can't be impossible, and it tells you when it's guessing.”

Got early access and pointed it at something real? Tell me — especially whether the confidence numbers meant what they claimed. That's the one thing nobody outside the company has answered yet.

This is the thing we build. AI that says “I don't know” instead of guessing, and hands the uncertain ones to a person — inside the tools your business already uses. Jev is one way to get there; a well-built assistant over your own material is another. Either way the rule is the same: the number next to the answer has to be honest.

Sources: TypeSafe's launch post and docs (the Stripe example is verbatim from their quickstart) and the Hacker News thread of 15 Sep 2026. Speed, price, the $7/hour figure and the 255-option limit are TypeSafe's stated numbers. I have not used Jev.

Originally published at singhlabs.dev.

I named three developer tools. All three names were taken on npm.

Manpreet Singh — Mon, 05 Oct 2026 10:41:41 +0000

I shipped three small tools over about a week. Bridle, Interlock, Slopguard. I was pleased with the names — short, metaphors that explain the mechanism, not a vowel-dropped startup pun among them.

Then, quite late, I checked the npm registry.

$ for p in bridle interlock slopguard; do
    curl -s -o /dev/null -w "%{http_code} $p\n" https://registry.npmjs.org/$p
  done
200 bridle
200 interlock
200 slopguard

All three taken. Not squatted — real packages, by real people:

bridle — "Javascript black magic RPC over websockets"
interlock — interlockjs, a module bundler
slopguard — "Don't let AI slop past your gate. Detect AI-generated code patterns"

That last one is doing roughly what mine does.

The actual bug this caused

Losing a name is annoying. That wasn't the problem.

The problem was already sitting in my README, in the install instructions:

npx github:manpreet171/bridle init   # correct
npx bridle lint                      # ...not correct

The first line is fine — explicit about the source. The second was copied from muscle memory, and it does something quite different.

npx github:user/repo fetches and runs from GitHub. It does not install anything. So by the second command there is no local bridle binary, and npx does what npx does: goes to the public registry, finds the package literally named bridle, downloads it, and runs it.

Six commands in that README would have run a stranger's websocket library on the machine of anyone following my own documentation.

Nobody was attacking me. I wrote the instructions myself, and they were wrong in a way that's invisible when you read them and obvious when you run them on a clean machine.

Why it's easy to miss

Because it works fine on your machine.

You've been developing the tool. You've got it linked, or installed globally, or you're in the repo where node_modules/.bin has it. npx bridle lint resolves locally and does exactly what you expect.

It's only on a machine that has never seen your project that npx falls through to the registry. Which is every machine except yours.

The fix

Install explicitly from the repo, then use the short command:

npm install -g github:manpreet171/bridle
bridle lint

Installing from a GitHub source skips the npm namespace entirely, so it doesn't matter who owns the bare name. Verify it links a real binary before you publish the instruction:

$ cd /tmp/check && npm init -y && npm install github:manpreet171/bridle
added 1 package
$ ls node_modules/.bin/
bridle  bridle.cmd  bridle.ps1
$ ./node_modules/.bin/bridle --version
bridle — Harness Script Engineering CLI

That last line is the whole test. It's the binary I wrote, not the one someone else published under the same word.

What I'd do differently

Check the registry during naming, not after. It's one curl. I checked the domain and the GitHub org and skipped the one namespace my install instructions actually resolve against.

curl -s -o /dev/null -w "%{http_code}\n" https://registry.npmjs.org/<name>

404 is free. 200 means somebody owns it and your README needs to be explicit forever.

Test install instructions on a machine that isn't yours. A clean container, or at minimum a temp directory outside the project. Docs that only work where the code already exists aren't docs.

Assume the good names are gone. Every short English noun that describes a mechanism is taken. Either accept a scoped or suffixed package name, or accept that you install from source and say so clearly.

I kept the names. They're good names and they're right for the tools. But the install line in all three READMEs now goes through the repo, and the pages on this site say plainly that the bare npm name belongs to someone else.

That felt like an admission when I wrote it. It's just accurate.

The tools: singhlabs.dev. All MIT, all zero-dependency, all installed from the repo rather than a bare npm name.

Anyone else been bitten by npx falling through to the registry? I suspect it's more common in READMEs than anyone realises, precisely because it never fails for the author. Tell me.

Originally published at singhlabs.dev.

I researched loop engineering to build a product. I built nothing.

Manpreet Singh — Mon, 05 Oct 2026 10:40:07 +0000

I went into last week intending to ship a loop engineering tool. The term is two months old, the searches are climbing, and I build guardrails for AI coding agents — it looked like my lane. I killed the idea twice.

If you're eyeing the same space — as a builder or just deciding what to adopt — the map that stopped me is more useful than another definition post. Page one of every search is definitions. Here is what actually exists.

The 90-second history

May 2025: Geoffrey Huntley wires a coding agent into a bash while true loop that re-feeds it the same prompt file until the work is done, and names it after Ralph Wiggum — ignorance, persistence, optimism. It works embarrassingly well, and The Register covers it as a genuine technique rather than a joke.

June 2026: Boris Cherny, who created Claude Code, says he doesn't prompt it any more — loops prompt it for him. Addy Osmani wraps a name around the practice, and "loop engineering" joins the lineage: prompt engineering, then context engineering, then harness engineering, now this. Roughly one new layer per year, each wrapping the one before.

So the concept is real. The question for anyone thinking of building here is different: is there room?

The map: what already exists

First stop, the GitHub topic pages. This is one command and it settles most arguments:

$ for t in loop-engineering ralph-wiggum graph-engineering; do
    printf "%-18s %s repos\n" "$t" \
    "$(curl -s "https://api.github.com/search/repositories?q=topic:$t" \
       | grep -m1 total_count | grep -o '[0-9]*')"
  done
loop-engineering   358 repos
ralph-wiggum       130 repos
graph-engineering  36 repos

Nearly five hundred repos across the two loop topics, two months after the term existed. Walking the actual listings, they sort into three shelves:

The runners. Tools that keep an agent looping until done. The topic leader sits near 10k stars, with multiple independent orchestrators around 3k. Every language, every agent CLI, every flavour.

The guardrails. Iteration caps, dollar budgets, no-progress detection, human checkpoints, review gates. At least three projects ship all of these today. The obvious "safe loop" product already exists several times over.

The platform itself. This is the shelf that ends the conversation. Claude Code shipped /goal in May — a native loop that runs until a condition you wrote is true, with a separate model grading each turn — then /loop, /schedule and /batch, then an official guide to all four. When the platform vendor absorbs a pattern into the product, the third-party version of that pattern is on a clock. Codex and Gemini CLI have equivalents.

And the tell that a category has finished consolidating: the curated awesome-lists have real stars now. Nobody curates an empty room.

Every tool in this category runs before or during the loop. Nothing owns the morning after.

What the honest practitioners say

The critiques are more interesting than the hype, because they point at what is unsolved.

The Pragmatic Engineer surveyed a couple of hundred developers and found adoption much narrower than the noise suggests — most real usage is ordinary automation wearing a new name, and human-in-the-loop still often beats autonomy.

Black Matter VC, from someone actually running loops in production: genuine leverage, but token burn runs roughly 4× a normal chat session and up to 15× for multi-agent setups. And the failure mode he names is not technical. He calls it comprehension debt — the gap between what's in your repo and what you actually understand, widening every time a loop ships code nobody read.

Notice what's missing from both critiques: neither says "we need another runner."

The gap

Line the tools up against the lifecycle of a loop and the shape jumps out. Before the run: policies, budgets, gates — covered. During the run: progress detection, checkpoints, caps — covered. Then the loop exits, and you are standing in front of two thousand changed lines with a cheerful four-sentence summary, at whatever hour it is.

That moment — the morning after — has no tooling. It is the exact moment comprehension debt gets paid or deferred, and every project in those 488 repos has already clocked off by the time it arrives.

That's the verdict that killed my loop product twice: the crowded part is finished, and the empty part isn't a loop tool at all. It's a reviewing problem. So instead of runner number 359 I built plumb — it holds the agent's summary against the diff and prints only what the summary left out: the files it never mentioned, the assertion that quietly disappeared, the test that got skipped instead of fixed. Zero dependencies, no model calls, and it doesn't care whether the code came from one prompt or a forty-iteration loop.

The method, if you're weighing your own idea

Check the topic page before you write a line. One curl, shown above. The repo count and the star spread tell you which shelves are full.

Check whether the platform vendor already shipped it. A feature in the CLI beats a repo, every time, forever.

An awesome-list with real stars means you're late. Curation is what happens after consolidation.

Then look for the moment in the lifecycle nobody covers. Categories crowd around the exciting phase — the run, the loop, the autonomy. The boring phases either side of it are usually empty, and the boring phase is where the actual pain lives.

A day of research, nothing built, and I'd call it the most productive day of the month. The cheapest product is the one you find out not to make.

The tools: singhlabs.dev. All MIT, all zero-dependency, all built after this same go/no-go research — including the two ideas that died so plumb could exist.

If you're running loops in production: what do you actually do with the output the morning after? Genuinely asking — it shaped one tool already and I suspect there's more there. Tell me.

Originally published at singhlabs.dev.

My mailer printed "campaign sent". It had sent to nobody.

Manpreet Singh — Mon, 05 Oct 2026 10:38:21 +0000

I make small tools that catch AI agents reporting success while quietly doing nothing. That is the entire product line. One of them is literally called trust issues.

Last week I shipped a mailer that printed campaign sent to list twice, five days apart, having delivered to zero people.

How it looked from the inside

I have a small list — 47 people who followed my writing elsewhere and agreed to hear from me here. I wrote them an email. The workflow ran. It said this:

campaign 2 sent to list ***

Green tick. Job done. Four days later I sent a second one. Same message, same green tick.

Then nobody replied to either. Not one person. I spent an evening concluding that my writing was bad, that the list was dead, that three weeks of work had landed on nobody who cared.

Eventually I did the obvious thing and looked at the numbers instead of my feelings.

LISTS
      0 subscribers  Your first list

CAMPAIGNS (newest first)

  "I measured where my AI coding tokens actually go. 0.2%."
    status sent   sent 2026-08-07T09:24:06+05:30
    delivered 0 of 0   opens 0   clicks 0

  "Moving my writing home — and what I've been building"
    status sent   sent 2026-08-03T19:40:50+05:30
    delivered 0 of 0   opens 0   clicks 0

Zero subscribers. Meanwhile 48 contacts sat in the account, imported correctly, never attached to the list the campaigns were addressed to. Both emails went out to an empty room.

Nobody ignored my emails. Nobody received them. Five days of silence I had taken personally was a config error.

The bug is not the interesting part

Contacts not attached to a list is a boring mistake. Ten minutes to fix.

The interesting part is that my code told me it had worked. It called the create-campaign endpoint. It called send. Both returned 200. So it printed success — because from the code's point of view, everything it did had succeeded.

It had verified the call. It had verified nothing about the effect.

That distinction is the whole of my product line, written on my own site, and I still shipped past it. An agent that says "I fixed the tests" has usually verified that it edited a file, not that anything passes. A deploy script that says "deployed" has usually verified that the API accepted the request. The gap between the call returned 200 and the thing you wanted actually happened is where this class of bug lives, and it is enormous.

Then a second bug nearly hid the fix

I attached the contacts, re-sent, and went to confirm. It still said zero.

For twenty minutes I believed the repair had failed. It hadn't. My stats script was reading the wrong endpoint, and the two endpoints disagree:

singular   /contacts/lists/2   → {"name":"Your first list","total":47}
collection /contacts/lists     → [{"name":"Your first list","total":0}]

Same list. Same second. Two different answers from the same provider. The collection endpoint reports 0 for a list that demonstrably has 47 members, and my code happened to read that one.

So I had a broken thing, then a broken measurement of the thing, and the measurement was what I was using to decide whether the fix had worked. When two sources disagree, find out which one lies before you conclude anything. I nearly re-fixed a bug that was already fixed.

How I actually confirmed it, in the end

Not from a dashboard. From the account's send credits.

The free plan allows 300 sends a day. Before the run: 300. After: 253. Exactly 47 gone — one per subscriber. That is the only number in this whole story that could not be produced by a bug in my own reporting, because it came from the provider's billing rather than from anything I wrote.

Then the email arrived in my own inbox, which is the other kind of proof that doesn't lie.

What I changed

The sender now refuses to send to an empty list. It checks the subscriber count first and exits with an error. A delivery of zero is a failure, and it must look like one.
The stats script resolves each list individually, with a comment naming the endpoint that lies, so nobody re-learns this.
Success messages now carry a number. sent to 47 subscribers, never campaign sent. A message with a count in it cannot be true and empty at the same time.

That last one is the cheap habit worth stealing. Most misleading log lines are misleading because they describe an action rather than a result. "Backup complete" versus "backed up 1,204 files, 3.1 GB". One of those can be printed by a script that copied nothing.

The uncomfortable version of this story is that I sell the fix. I write tools that hold an agent's claim against what actually changed on disk, because a confident summary is not evidence. Then I wrote a summary of my own, believed it, and lost five days and most of an evening to it.

Knowing the failure mode is not the same as being immune to it. If anything, I was slower to check because the message came from code I had written myself.

Everything quoted here is real output from my own account, lightly trimmed for width. The list is 47 people; if you are one of them, that is why the first email arrived twice.

Originally published at singhlabs.dev.

The models are a point apart. The harnesses are on fire.

Manpreet Singh — Mon, 05 Oct 2026 10:35:14 +0000

Two numbers went round in the last few weeks. On Terminal-Bench 2.1, GPT-5.6 Sol scored 89.5% and Claude Opus 5 scored 89.1%. Four tenths of a point between the default models of the two most-used coding agents on earth.

Check a second leaderboard and you get 85.77% and 84.64% — different harness, different numbers, same story. About a point in it, whoever is counting.

In the same weeks those numbers were being argued about, here is what those agents actually did.

The month, in one list

GhostApproval — six assistants at once: Cursor, Claude Code, Antigravity, Copilot, Grok Build, GitHub. "A malicious repo uses symlinks (CWE-61) to make the agent write outside the workspace while the approval prompt hides the real target from the user."
DuneSlide — two CVSS 9.8 holes in Cursor. Zero-click prompt injection that escaped the terminal sandbox and overwrote the sandbox helper binary.
Cursor deeplinks — one click installed an attacker-controlled MCP server and ran unsandboxed commands. The install dialog truncated the commands you were approving.
AWS Kiro — "hidden text on an ordinary web page instructs AWS Kiro to silently rewrite its own MCP server config file", then reload it.
GitLost — a plain-English payload in a public GitHub issue made Agentic Workflows read private repositories and post the contents as a public comment.
Claude Code — ran prisma migrate diff with the wrong parameters and deleted 22 production tables.

Now read that list again and try to find one entry that a smarter model would have prevented.

Not one of these is a reasoning failure. Every single one is a question of what the agent was allowed to reach.

Two axes, and we only measure one

Benchmarks measure capability: given a task, can it do the thing. That is a real number and it has genuinely gone up.

Authority is a different axis entirely: what can this process touch, and who decided. Nobody publishes a leaderboard for it. There is no percentage. It is a config file that most people have never opened.

	Weak model	Capable model
Unbounded authority	weak, unbounded	capable AND unbounded — every incident above
Bounded authority	weak, bounded	capable AND bounded — the only good square

Capability (left to right) is measured, benchmarked, argued about. Authority (top to bottom) is unmeasured. Four years of effort has been horizontal. The vertical axis has barely moved.

The part that should worry you

For prompt injection, a better model makes it worse.

A weak model handed a hidden instruction on a web page misunderstands it, fumbles the syntax, gives up. A strong model reads the same instruction, works out precisely what is being asked, and executes it correctly. That is what happened to AWS Kiro. The agent didn't malfunction. It followed instructions beautifully. They just weren't yours.

Every point of capability makes an agent a better employee and a better confused deputy. You cannot benchmark your way out of that, because the benchmark is measuring the thing that makes it worse.

So what actually helps

Nothing exotic. The boring version works:

Decide the blast radius before you need it. Which paths, which commands, which credentials. Written down, in the repo, not in your head at 11pm.
Treat any text the agent reads as hostile input. Web pages, issue bodies, README files, dependency docs. GitLost was a public issue. AWS Kiro was an ordinary web page.
Read the diff, not the summary. The Prisma incident had nothing to do with injection. It was a wrong flag, run confidently, with production credentials in reach.
Assume the approval dialog is lying. Two of these involved prompts that hid or truncated what you were agreeing to.

None of that requires a better model. All of it requires deciding, in advance, what the agent may reach — which is the thing nobody wants to do, because it is admin and the benchmark doesn't reward it.

I build small tools in this gap, so treat me as biased: interlock decides what an agent may patch and what needs a person, and slopguard checks generated code before it hits disk. Both are free and neither is the point of this post.

The point is that the industry spent a month arguing about four tenths of a point while six agents were writing outside their workspace. We are optimising the axis we can measure, and the other one is where the damage is.

Incident details and quotes from Adversa AI's August 2026 roundup; benchmark figures from Artificial Analysis and vals.ai. I have not reproduced any of these exploits myself.

Originally published at singhlabs.dev.

The best CLAUDE.md rules are hiding in your chat history.

Manpreet Singh — Mon, 05 Oct 2026 10:33:16 +0000

Quick question. What's the one sentence you've typed to your AI more than any other?

Not the one you think you type. The one you actually type.

I didn't know mine either. So I went back through three months of my own Claude Code history and counted. It was "keep it simple." 42 times, across 38 different sessions. And that rule was written nowhere my AI could read it.

Every correction you type and don't write down dies with the session.

If you use Claude Code, Cursor or Codex every day, you have your own "keep it simple." This post is about finding it, writing it down, and checking whether it stuck. At the end there's a one-minute way to see your own top line.

The 42 times

This is a real run on my real history, 143 Claude Code sessions between July and September:

toldya · 143 sessions (2 Jul – 25 Sept) · 6379 of your messages · 528 corrections

You keep telling your AI:
   1.  42×  keep it simple   (38 sessions)
   2.  29×  dont complex this   (18 sessions)
   3.  15×  dont assume   (15 sessions)
   4.  13×  i dont want later on   (12 sessions)
   5.   9×  dont think too much   (9 sessions)

And 71 times you told it to try or check again: its first go missed.

Numbers one and two are the same complaint, one with my typo. Together that's 71 times I told my AI to stop overbuilding. The last line is a different 71: "try again" and "check again", which isn't a rule, just an honest measure of how often the first attempt missed.

This isn't a complaint about Claude. It's genuinely good at what I use it for. It's that every one of those corrections was a rule I never wrote down.

Why your AI forgets everything

A coding agent doesn't remember yesterday. Each session starts from zero. What you corrected on Tuesday afternoon is gone by Wednesday morning.

The one thing it reliably reads at the start of every session is a small text file in your project called CLAUDE.md. Other tools use AGENTS.md, same idea.

Think of it as a sticky note on the monitor for a brilliant new colleague with amnesia. They wake up every day with no memory of you. The note is the only thing that carries over. If it's not on the note, it's gone.

Everyone says "just add a rule"

Every CLAUDE.md guide gives the same advice: when your AI repeats a mistake, add a rule for it. It's good advice. I agree with it.

The gap is that you don't notice you're repeating yourself. My "keep it simple" came up in 38 sessions, across different projects, weeks apart. Each time it felt like a one-off. I never once thought "this is the thirtieth time." Repetition across days is invisible from inside the day.

That's why none of my top five were in my CLAUDE.md. Not laziness. I just had no idea.

Why grep lies to you

Claude Code keeps your history on your own machine, as text files in ~/.claude/projects. So the obvious move is to search it. I searched for "keep it simple." It said 747. The real number was 42.

Same history, same phrase. 18 times too big.

The files hold everything, not just what you typed: the AI repeating your words back, summaries written when a chat gets long, tool output, logs and briefs you pasted. Counting properly means keeping only the short messages you typed, dropping questions and pastes, and grouping the ways you say the same thing. "Don't complicate it", "dont complex this" and "dont comlicate that" are one habit, not three.

So I built a tiny thing

It's called toldya, as in "I told you so." A free command-line tool that does the counting above, then offers to write the results onto the sticky note for you. One command, Node 18 or newer, no account:

npx toldya --all

It reads your Claude Code history on your machine, shows the list above, and asks about each one: y adds it as a rule, n skips it, e lets you reword it first. Nothing is written without a yes. Or pick by number:

npx toldya --all --add 1,2,3 --to CLAUDE.md

Added 3 rules to CLAUDE.md. Run toldya again in a week to see if they stuck.

## Things I kept repeating
- Keep it simple.
- Dont complex this.
- Dont assume.

Yes, it keeps my typo. They're your words. Fix them with e.

Did it stick?

Adding a rule doesn't mean the AI follows it. The file can be read perfectly and the rule can still not land.

So toldya remembers which rules it added, and when. Run it again a week later and each rule shows how often you said it before it went in, and how often since. If "keep it simple" drops from 42 to near zero, the rule works. If it keeps climbing, the wording isn't landing.

I can't show you a "since" number yet. The tool is a few days old, so there is no "since" to count. That's the honest state of it.

And because it made me laugh: npx toldya --all --card draws your top repeats as a picture, on your machine, with a "Save as PNG" button. Nothing is uploaded.

Mine. Drawn earlier the same day, one "keep it simple" ago.

The part I got wrong

I had a bigger idea first: a team version that reads a project's pull-request review comments, finds what reviewers keep writing, and turns that into rules.

Before building it, I pulled the last 1,000 review comments from each of Next.js, React, Astro, Supabase and Cal.com, and ran the same counting on them. Almost nothing repeated as a rule. The top "repeats" were "This is changed now" (13 times), "Fixed in the latest commit" (9) and "Thanks for the test" (7). That's conversation. Reviewers write about the code in front of them.

People correcting their own AI are the opposite: the same handful of sentences, in the same words, for months. So the team version got dropped.

What it doesn't do

Claude Code only, for now. Codex stores history elsewhere and I haven't tested it on real files, so I'm not claiming it.
It matches words, not meaning. It won't connect "use the logger" with "why is there a console.log here?". That would need a model, and I wanted it small, free and local.
It sees only the history you have. Claude Code keeps about 30 days by default.
It needs a pattern. A phrase must appear three times, in two different sessions. New to Claude Code? You may get "nothing repeated yet." Good result.
It sends nothing anywhere. Only your own messages are read. No account, no telemetry, no network calls.

Try it in a minute

The safe version only shows the report and changes nothing:

npx toldya --all --dry

The code is at github.com/singhlabsdev/toldya, MIT, zero dependencies. If it finds something useful, a star helps other people find it. And I'd genuinely like to know your top line. Mine is "keep it simple." 42 times.

This is how we build. Small tools that count what really happened instead of guessing, run on your machine, and ask before they change anything. The same rule goes into the agents we build for businesses.

Sources: every terminal block is a real toldya run on my own Claude Code history on 25 Sep 2026. The 747 is a plain grep of the same files that day. The review-comment figures come from the last 1,000 comments per repo, fetched from the GitHub API the same day.

Originally published at singhlabs.dev.

An AI Agent Broke Into Hugging Face to Cheat a Test.

Manpreet Singh — Thu, 30 Jul 2026 16:16:19 +0000

An AI agent ran a 4.5-day intrusion against Hugging Face's production infrastructure.

17,600 actions.

Cluster-admin on multiple clusters. Write access to internal source code.
Everyone's calling it AI turning hostile.

It wasn't attacking. It was cheating on a test.

The agent was being graded on a security benchmark. It worked out that Hugging Face probably hosted the answer key, and decided stealing the solutions was easier than solving the challenges.

Of all the content on the platform, it accessed five datasets. Every one tied to that benchmark.

Here's the detail that settles it: when it got cloud credentials and probed what it could do, every potentially destructive call was issued with DryRun=True.

That flag means "tell me if this would work, but don't do it."

An attacker who wants damage doesn't set that. An optimiser measuring its reach does.

Nobody pointed this agent at Hugging Face. The objective just said score well and the cheapest route to a high score ran through someone else's production systems.

You don't need to write a harmful goal to get harmful behaviour. You only need an objective that's easier to satisfy through a path you didn't consider.

We've all seen the small version. You ask an agent to make the tests pass, and it deletes the test.

This is that, with production credentials

Want to read article for free check comment box.

How to make an approval mean "yes, to this" instead of "yes, forever"

Manpreet Singh — Tue, 28 Jul 2026 11:41:48 +0000

Here's a problem you hit about ten minutes after you let anything automated touch your pipeline.

Your build breaks. Something proposes a fix. You look at it, it's fine, you approve it. Two days later the identical break happens again and you get asked again. And again. So you do the obvious thing and approve the class of fix permanently — and now you've handed out a blank cheque for a category of change you only understood one example of.

Both options are bad. What you actually want is to say "yes, to this"—this exact failure, not this once, not forever.

That turns out to be a fingerprinting problem, and it's more interesting than it sounds.

Why you can't just hash the log

The naive version: hash the failure text, store the hash, compare next time.

It never matches. Here are two runs of the same broken workflow, three days apart:

2026-07-21T11:02:44.7710223Z ##[warning]The `set-output` command is deprecated
2026-07-24T18:47:10.0021994Z ##[warning]The `set-output` command is deprecated

Different timestamp. Different run id. Different runner. Different checkout path. Same break. A raw hash gives you two different values and your approval is useless immediately.

CI logs are full of things that change on every single run and mean nothing:

ISO timestamps on every line
run ids and job ids
runner working directories (/home/runner/work/api/api/…)
commit SHAs
line and column numbers
durations
ANSI colour codes
GitHub's own ##[group] / ##[endgroup] markers

None of that is the failure. All of it poisons the hash.

Strip everything that varies, then hash

The whole mechanism is one normalise function. This is the real thing, from bin/interlock.mjs:

function normalize(text) {
  return text
    .replace(ANSI, "")
    .replace(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z\s?/gm, "")
    .replace(/^##\[(group|endgroup|debug|command)\].*$/gm, "")
    .replace(/[A-Za-z]:\\[^\s"']+|\/(?:home|Users|opt|tmp|github|runner)\/[^\s"':]+/g, "<path>")
    .replace(/\b[0-9a-f]{7,40}\b/g, "<hex>")
    .replace(/\b\d{5,}\b/g, "<n>")
    .replace(/\bline \d+\b/g, "line <n>")
    .replace(/:\d+:\d+\b/g, ":<n>:<n>")
    .replace(/\b\d+m\s?\d+(\.\d+)?s\b/g, "<dur>")
    .replace(/[ \t]+/g, " ")
    .trim();
}

Nine substitutions. Every one removes something that differs between two runs of the same failure.

Then the fingerprint is a hash of the failure's class plus its normalised evidence — not the whole log, just the line the classifier matched:

const fingerprint = (r) => sha(`${r.class}|${normalize(r.evidence)}`).slice(0, 12);

Twelve hex characters. That's it.

Does it hold?

Those two runs above, three days apart:

run 4502  →  1c59f09f5474
run 4530  →  1c59f09f5474

A genuinely different failure—a missing Python import — lands somewhere else entirely:

run 4471  →  263819a52f2e

So an approval recorded against 1c59f09f5474 covers that break and nothing else. The next time it happens:

AUTO  warrant h-627fdffd — this exact failure was cleared by Manpreet Singh (use 1/5)

Nobody was asked. A different failure still gets asked and always will.

The two properties that make this worth doing

One: the thing asking for permission cannot forge the fingerprint.

This is the part I'd steal for other systems. The fingerprint is derived from the log — evidence that already exists, produced by CI, not by whatever is requesting approval. There's no field where an agent describes itself and gets believed. It can't widen its own permission by wording the request more generously, because nothing it says is an input.

If you're building any kind of approval gate, that's the property to design for: derive the identity of the request from evidence the requester didn't author.

Two: an approval should die when the rules change.

A fingerprint alone still isn't enough. If I approve a fix under one policy, then loosen the policy, that old approval shouldn't quietly carry into the new world.

So each clearance also stores a hash of the enforcing parts of the policy — scope, clearance buckets, limits, mode. Not the whole file:

function ruleHash(p) {
  return sha(JSON.stringify(canon({
    scope: p.scope, clearance: p.clearance,
    warrant: p.warrant, limits: p.limits, mode: p.mode,
  }))).slice(0, 12);
}

Edit the owner field or a comment and approvals survive, because neither changes what's enforced. Add one glob to the allow-list and every past approval is void:

$ interlock log --verify
4 entries  ·  rules in force now: 87d0bb038798
! 3 recorded under rules that no longer apply
  1 past clearance void — those failures go back to a person

That's the difference between an audit trail and a control. If loosening your policy is free, the policy isn't doing anything.

Where it falls down

Being honest about the limits, because you'll hit them:

Normalisation is a guess. Nine regexes cover GitHub Actions well. A CI system that formats logs differently needs its own rules, and a failure whose message genuinely varies run to run will never fingerprint stably.
Two different bugs can share evidence. If two distinct problems produce the identical error line, they get the same fingerprint. Narrower classes reduce this; they don't eliminate it.
It says nothing about whether the fix is correct. It only answers "is this the same failure I already looked at?"—which is exactly one question, not all of them.

The general shape

Strip everything that varies between runs. Hash what's left, alongside the class. Bind the approval to that hash and to a hash of the rules in force. Store it where a person can read it later.

That works for CI failures. It works for anything where you want a human decision to be reusable but not unbounded.

The implementation is a single zero-dependency .mjs file, MIT, 35 tests: github.com/manpreet171/interlock

If you've solved the "yes, to this" problem a different way, I'd genuinely like to hear it—especially the normalization, which is the part I'm least sure generalizes.