DEV Community: Manpreet Singh

I ran Claude Code on DeepSeek V4.1 Flash. It cost 2 cents. Claude Code said 96.

Manpreet Singh — Mon, 19 Oct 2026 13:02:03 +0000

Short answer: yes, Claude Code runs on DeepSeek V4.1 Flash, with nine environment variables. I gave it one real coding task, three times, on fresh copies of a repo. All three passed my own checks. Each run cost about 2 cents at DeepSeek's off-peak price. Claude Code showed between $0.87 and $1.28 for the same runs, because it prices a model it doesn't recognise at Claude Opus 5's rates.

DeepSeek shipped the 1017 update of V4.1 Flash on 17 October, and benchmarked it inside Claude Code itself. Benchmarks are someone else's task. I wanted mine.

On DeepSeek, Claude Code's cost counter is wrong by about 50×. It prices tokens from a model it doesn't recognise as Claude Opus 5.

The setup

These are DeepSeek's own recommended settings for Claude Code, plus one line of mine at the top:

export CLAUDE_CONFIG_DIR=~/.claude-deepseek     # mine: any empty folder
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<your DeepSeek API key>
export ANTHROPIC_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-flash[1m]
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-flash
export CLAUDE_CODE_EFFORT_LEVEL=max
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=786432

The separate config folder means the run can't touch my Claude login, my own CLAUDE.md files or my plugins. Every run started from the same blank setup.

The task

Add a --json option to bridle's agents check, our open-source AGENTS.md linter. With the flag, print one JSON object. Without it, the text report must not change by a single character. Add a test for a passing file and a failing one, then run the whole suite.

Small, but real: the report was printed line by line straight to the screen, so the code had to be reshaped without changing what it prints. Each run got a fresh clone and ran unattended with claude -p.

Did it work? I checked, not its summary

All three runs said they passed. Here's what I checked myself, on each one:

$ node --test
# tests 8
# suites 0
# pass 8
# fail 0

Eight of eight: the six old tests and its two new ones. Then the part tests miss. I ran the new code and the original on all 32 AGENTS.md and CLAUDE.md files from our study of 25 famous repos. The text output was identical on all 32, in all three runs. And the new flag does what it says:

$ node bin/bridle.mjs agents vscode-AGENTS.md --json
{"file":"vscode-AGENTS.md","verdict":"FAIL","failures":1,"lines":["Linting vscode-AGENTS.md","","  · no command blocks — reading this as a policy file, not a project file","  ✘ pointer file: under 80 words, the rest is a link — an agent that does not follow it gets nothing","  ✔ no unfilled placeholders","  ✔ nothing in here tells the agent to do something dangerous","  ! only 0 prohibition(s) — nothing here says what the agent must never touch","  ✔ size: 33 words ≈ 68 tokens, re-sent every turn","","FAIL — 1 problem(s). Your agent is reading this file on every run."]}

One thing I didn't ask for: all three runs also added an entry to LOG.md. The repo's own CLAUDE.md says every change gets logged. The prompt said "do not change anything else". It followed the file over the prompt, and said so in its summary. Your CLAUDE.md still rules, whichever model is behind it.

The numbers

Run	Turns	Time	Tokens: new / cached / out	Claude Code showed	DeepSeek charged
1 · effort max	31	93 s	44,065 / 632,192 / 17,123	$0.96	$0.019
2 · effort max	42	123 s	43,284 / 970,880 / 22,957	$1.28	$0.023
3 · effort high	26	91 s	38,074 / 605,312 / 14,896	$0.87	$0.017

"DeepSeek charged" is the token counts times DeepSeek's off-peak list price. The account balance agrees: it went from $0.49 to $0.46 across all three runs.

Why the counter is wrong

$ python -c "..." run-max1.json   # fields from Claude Code's JSON result
num_turns            31
input_tokens         44065
cache_read_tokens    632192
output_tokens        17123
total_cost_usd       0.964496
costBasis            unknown

Claude Code also printed [claude-code:unrecognized_model] {"model":"deepseek-flash[1m]","query_source":"sdk"}. It doesn't know DeepSeek's prices, so it falls back to a Claude model's. Those token counts at Claude Opus 5's list prices ($5 per million in, $0.50 cached, $25 out) come to exactly $0.964496. If you budget off that number, you're out by about 50×, in the safe direction at least.

The cache works, just not Claude Code's

DeepSeek's docs say its Anthropic endpoint ignores Claude Code's cache_control markers. It caches on its own anyway: 94.6% of input tokens across the three runs were cache hits, at $0.003 per million instead of $0.15. That matters because Claude Code re-sends the whole session every turn. On my own history, re-sent context was 97.5% of all tokens. The cached price is the price that counts.

So is it cheaper than Claude?

Here's the same token mix, averaged over the three runs, at each list price:

Model	Per run
DeepSeek V4.1 Flash, off-peak	$0.020
Claude Haiku 5.5	$0.021
DeepSeek V4.1 Flash, peak hours	$0.039
Claude Sonnet 5.5	$0.34
Claude Opus 5.5	$0.68
Claude Fable 5.1	$1.52

Against Sonnet and Opus, DeepSeek is about 17 to 35 times cheaper. Against Claude Haiku 5.5, it's about the same, and at peak hours Haiku is cheaper. Peak is 01:00–04:00 and 06:00–10:00 UTC on weekdays, which in India is much of the working morning.

Read that table carefully. It prices DeepSeek's tokens at Claude's rates. A Claude model would take a different number of turns and tokens. I didn't run Haiku 5.5 on this task, so whether it passes is untested. What it does tell you: the cheap end of the market is now cents per task, and the question is which model passes your checks, not which one is cheap.

What I'd watch

Ignore the cost counter on any non-Claude model. Read your provider's bill.
"Max" effort isn't free. My two max runs took 31 and 42 turns; the high run took 26. Three runs are a sample, not a trend.
Check the work, not the summary. All three summaries were accurate this time. The only way I know that is that I ran the checks.

Sources: three runs on 19 Oct 2026 between 12:47 and 12:52 UTC (DeepSeek off-peak), Claude Code 2.1.257, each on a fresh clone of bridle at commit d439619, run with claude -p --output-format json --permission-mode acceptEdits. Token counts are from Claude Code's JSON result. Prices: DeepSeek's models and pricing page and its Claude Code guide; Anthropic's pricing page; all read 19 Oct 2026. The Claude rows price uncached input at the base rate and skip cache-write premiums, so real Claude runs would cost a little more. The terminal blocks are real; the test output is trimmed to its summary lines, and the JSON field list was read out of Claude Code's result with a short Python one-liner.

Originally published at singhlabs.dev.

WhatsApp Business API pricing in India, 2026: your chatbot's replies cost money again.

Manpreet Singh — Mon, 19 Oct 2026 12:19:02 +0000

Short answer: since 1 October 2026, Meta charges again for the replies a business sends while a customer's chat is open. In India that's ₹0.115 a message after the first 1,000 free each month per number. Marketing messages are ₹0.8631. And if Meta bills you from India, that billing has to move to rupees by 31 December, or messages stop on 1 January.

Every rate page you'll find lists the numbers. None of them adds up a real month for a business that runs a chatbot on WhatsApp, where the bill comes from three places. So I did, with Meta's own rate card.

In India, Meta now charges more to deliver your chatbot's answer (₹0.115) than a cheap AI model charges to write it (about ₹0.05).

What changed on 1 October 2026

Replies are charged again. A reply your business sends inside the 24-hour window that opens when a customer writes is a "service" message. Those had been free since November 2024. Now each one is charged, after the first 1,000 a month per business phone number.
So are utility messages inside that window. Order updates and receipts sent while the chat is open had been free since July 2025. Not any more.
Billing is per message. That has been true since July 2025, and it matters more now: an answer split into three messages costs three times as much as the same answer in one.

The India rates, from Meta's rate card

Message type	What it is	Per message
Service	Your reply while the customer's chat is open	₹0.115
Utility	Order updates, receipts, reminders	₹0.115
Authentication	One-time passwords	₹0.115
Marketing	Offers and announcements, to people who opted in	₹0.8631
Authentication-international	OTPs sent by a business based outside India	₹2.4971
Meta Business Agent	Replies written by Meta's own AI agent	$2 per million tokens

These are Meta's list rates in rupees, effective 1 October 2026. Tax and any provider's fee come on top. Volume discounts exist, but for India they start late: utility only after 2.5 crore messages a month, authentication after 7.5 lakh.

What's still free

The first 1,000 service messages each month, per business phone number. They don't carry over.
Everything in a "free entry point" window: chats that start from a click-to-WhatsApp ad or a Facebook Page button. Marketing, utility and service messages in that window aren't charged.

A real month for a chatbot

Take a shop that gets 3,000 customer chats a month on WhatsApp. The bot answers each in about four messages, and the shop sends 1,500 order updates. Those volumes are my assumption, not a measurement; plug in yours.

Line	How it's worked out	Per month
Bot replies (service)	12,000 replies, first 1,000 free, 11,000 × ₹0.115	₹1,265
Order updates (utility)	1,500 × ₹0.115	₹172.50
The AI model	Claude Haiku 5.5, about 4,000 tokens in and 150 out per reply: $5.70	≈ ₹541
The server	A small VPS. Ours costs about ₹2,000 a month	≈ ₹2,000
Total	Before any marketing messages	≈ ₹3,979

Three things fall out of that:

The 1 October change alone is ₹1,265 here. Before it, those 11,000 replies were free.
Meta's share is about a third. At this size the server costs more than WhatsApp does. Twice the chats roughly doubles Meta's line and the model's, not the server's.
Short, complete answers save real money. Each message is charged, so one good reply beats three chatty ones.

Sending one offer a month to 1,000 opted-in customers would add ₹863.10 on top.

What a provider adds

Many businesses don't connect to Meta directly. They use a provider such as AiSensy, which shows its own rates. On 19 October its pricing page listed ₹0.145 for service, utility and authentication messages and ₹1.09 for marketing. That's about 26% over Meta's list rates (₹0.115 and ₹0.8631). In the example above it comes to ₹375 more a month.

That isn't a scam. The markup pays for a shared inbox, template tools and support you'd otherwise build or do without. Just know which number you're looking at: Meta's rate, or a provider's.

Two more rules to know

Billing in rupees by 31 December 2026. This applies to providers, and to businesses connected to Meta directly, whose billing country is India. Their WhatsApp accounts must move to INR by 31 December. From 1 January 2027, Meta stops delivering messages from accounts still billed in another currency. Meta has a currency migration tool for it. If you use a provider, ask them.
No ChatGPT-style bots. Since 15 January 2026, Meta has barred general-purpose AI assistants from the WhatsApp Business Platform. A bot that answers about your own business, orders and bookings is fine.

Sources: Meta's pricing page (updated 30 Sep 2026) and its INR rate card and volume tiers, effective 1 Oct 2026, downloaded 19 Oct 2026. AiSensy's pricing page, read 19 Oct 2026. Anthropic's model pricing for Claude Haiku 5.5 ($0.10 per million input tokens, $0.50 output). Dollars converted at ₹94.96, the ECB rate of 16 Oct 2026. The ban on general-purpose assistants: Business Standard. The chat volumes and tokens per reply are assumptions, labelled as such; the server figure is what ours costs.

Originally published at singhlabs.dev.

We checked the AGENTS.md files of 25 famous repos. Our own linter got a third of its fails wrong.

Manpreet Singh — Fri, 16 Oct 2026 07:20:20 +0000

Short answer: AGENTS.md is the Markdown file in a repo that tells AI coding agents how to work on it. On 16 October, 212 of GitHub's 600 most-starred repos had one in the root. I read 25 of the best-known and ran our linter on each. None tells an agent to do anything dangerous. Seven are over 3,000 tokens, re-sent on every turn. Ten forbid the agent to act on GitHub alone. And our linter failed 18 of them, five wrongly. We fixed that the same day.

Search "AGENTS.md examples" and you get advice: keep it short, put the commands first, say what not to do. Good advice. I wanted to see what the projects everyone copies from actually wrote.

AGENTS.md is quietly becoming the AI contribution policy. Ten of 25 tell the agent not to push, open PRs or comment without a person.

How many repos have one: 212 of 600

I took GitHub's 600 most-starred repositories (the smallest has 45,779 stars) and checked each root folder:

212 have an AGENTS.md. That's 35%.
132 have a CLAUDE.md, and 107 of those have both.
Only 25 have a CLAUDE.md and no AGENTS.md.

The 600 include awesome-lists, books and courses, which I didn't separate out. Then I picked 25 well-known ones across JavaScript, Python, Go, Rust, Java, Ruby and C++. A hand pick, not a random sample: I wanted files people actually copy.

The 25, side by side

Sorted by size. "Est. tokens" is our linter's estimate (characters ÷ 4), sent again on every turn of a session. "Setup" and "Test" mean a concrete command, read by hand.

Repo	Words	Est. tokens	Setup	Test	bridle (old)	Fair?	1.2.0
vercel/next.js	4,309	7,658	yes	yes	FAIL	yes	FAIL
astral-sh/ruff	2,926	5,098	no	yes	FAIL	yes	FAIL
langchain-ai/langchain	2,743	5,088	yes	yes	FAIL	yes	FAIL
elastic/elasticsearch	2,110	4,151	partial	yes	FAIL	yes	FAIL
pytorch/pytorch	2,407	4,007	yes	partial	FAIL	yes	FAIL
rust-lang/rust	1,855	3,357	no	partial	FAIL	yes	FAIL
zed-industries/zed	1,888	3,114	no	no	FAIL	yes	FAIL
ggml-org/llama.cpp	1,739	2,892	no	no	FAIL	no	PASS
caddyserver/caddy	1,259	2,358	no	yes	PASS	yes	PASS
microsoft/playwright	1,248	2,185	no	yes	PASS	yes	PASS
rails/rails	847	1,726	no	yes	PASS	yes	PASS
cli/cli	744	1,443	partial	yes	PASS	yes	PASS
spring-projects/spring-framework	598	1,066	yes	yes	FAIL	no	PASS
astral-sh/uv	520	876	no	no	PASS	yes	PASS
huggingface/transformers	476	816	no	yes	PASS	yes	PASS
nodejs/node	423	771	no	no	FAIL	no	PASS
pandas-dev/pandas	303	679	partial	no	FAIL	yes	FAIL
angular/angular	275	513	partial	yes	FAIL	no	PASS
kubernetes/kubernetes	259	471	no	yes	FAIL	yes	FAIL
gohugoio/hugo	266	429	no	yes	PASS	yes	PASS
scikit-learn/scikit-learn	199	329	no	no	FAIL	no	PASS
python/cpython	90	151	no	no	FAIL	borderline	PASS
sveltejs/svelte	77	148	no	no	FAIL	yes	FAIL
ollama/ollama	56	90	partial	no	FAIL	yes	FAIL
microsoft/vscode	33	68	no	no	FAIL	yes	FAIL

The data: the 25 files, with the commit each was read at, and all 600 repos in the census (CSV). Reuse it freely under CC BY 4.0: just link this post.

The biggest: Next.js, about 7,700 tokens a turn

Here's our linter, bridle, on the largest one:

$ node bridle.mjs agents vercel__next.js.AGENTS.md
Linting vercel__next.js.AGENTS.md

  ✔ 15 runnable command block(s)
  ✔ how to install / set up
  ✔ how to run the tests
  ✔ how to build or run it
  ! 15 angle-bracket field(s), e.g. <task> — check these are argument syntax, not unfilled template text
  ✔ nothing in here tells the agent to do something dangerous
  ✔ 29 prohibition(s) — the agent knows where the edges are
  ✘ size: 4309 words ≈ 7658 tokens, re-sent every turn — over 3k tokens per turn is a real cost, cut it

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

It's a good file. It does everything right except stay short. If a session ran 100 turns (my assumption, not a measurement), the file alone would fill 765,800 tokens of context. Caching makes that cheaper, not smaller, so I won't turn it into dollars. What a line costs is priced here.

The middle of the 25 is about 1,070 tokens. Eleven are over 1,500 and seven are over 3,000: Next.js, Ruff, LangChain, Elasticsearch, PyTorch, Rust and Zed.

What's actually in them

Conduct, more than build. Node, CPython, scikit-learn and pandas are mostly rules for AI contributions and say little about building or testing.
Little on setup. Only 4 of 25 give a concrete setup command: LangChain, Next.js, PyTorch and Spring. Thirteen give a concrete test command. Many leave both to CONTRIBUTING.md.
The agent may not act alone. Ten forbid pushing, opening PRs or issues, or commenting without a human: Node, pandas, PyTorch, llama.cpp, Caddy, GitHub CLI, Rust, Transformers, Playwright and Next.js.
They disagree on credit. Kubernetes, Playwright, Elasticsearch and Next.js ban AI co-author trailers. Node and llama.cpp require an Assisted-by: line. One global agent setting can't satisfy both. We compared eleven AI policies and found the same split.
Two are pointers. VS Code's is 33 words and Svelte's 77, mostly links elsewhere. An agent that doesn't follow the link gets almost nothing.

Nothing dangerous, in any of them. No sudo, no curl | sh, no rm -rf, no --no-verify, no force push, no write to your home folder. I re-ran the check with its "this line forbids it" filter switched off: still zero. The only writes outside the repo are to /tmp in Next.js and Ruff, both scratch space with a stated reason.

And CLAUDE.md has become a pointer. Seven of the 25 also have one. None has its own content: three are the same file under two names, two are a one-line @AGENTS.md import, and two just say "see AGENTS.md". Which is the setup we recommended.

Five lines worth copying

Zed sets a bar for adding any rule: "Rules should be traps to avoid, not maps to follow." Anything the agent can learn by reading the code stays out.
Kubernetes pairs its "don't" with the command to run instead: don't hand-edit generated files, run the update target.
GitHub CLI names the one command with side effects: its acceptance tests create real resources, so they need an authorised test host.
Playwright defines consent in words a model can check: it may push only when the user's message contains specific trigger words.
llama.cpp corrects the model's stale memory: a library it may "remember" isn't used here.

Our linter got a third of its fails wrong

bridle failed 18 of the 25. I read every one. Twelve fails were fair: the seven oversized files, plus VS Code, Ollama, Kubernetes, Svelte and pandas for missing steps or thin pointers. Five were wrong, and one was borderline. Node is the clearest:

$ node bridle.mjs agents nodejs__node.AGENTS.md
Linting nodejs__node.AGENTS.md

  · no command blocks — reading this as a policy file, not a project file
  ✘ few imperative rules — an agent cannot act on description alone
  ! 4 angle-bracket field(s), e.g. <agent name> — check these are argument syntax, not unfilled template text
  ✔ nothing in here tells the agent to do something dangerous
  ! only 2 prohibition(s) — nothing here says what the agent must never touch
  ✔ size: 423 words ≈ 771 tokens, re-sent every turn

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

Node's file has a section headed "AI agents must not:" with eight items under it. bridle counted two. Its rules only saw lines that start with one of nine verbs, so it missed indented bullets (Angular), rules mid-sentence (scikit-learn), a terse list (Spring), and a list under a "must not" heading (Node). And llama.cpp's conduct policy was read as a project file because one example block was labelled sh.

Fixed the same day: bridle 1.2.0. It now ignores the label on a code block, reads indented and mid-line rules, treats two to four rules as a warning instead of a fail, follows a CLAUDE.md that imports AGENTS.md, and fails a pointer file under 80 words. Re-run on the same 25: 13 pass, 12 fail. All five false fails now pass, CPython passes with a warning, and the twelve fair fails still fail. Node now reads:

$ node bridle.mjs agents nodejs__node.AGENTS.md
Linting nodejs__node.AGENTS.md

  · no command blocks — reading this as a policy file, not a project file
  ! only 3 imperative rule(s) — an agent cannot act on description alone
  ! 4 angle-bracket field(s), e.g. <agent name> — check these are argument syntax, not unfilled template text
  ✔ nothing in here tells the agent to do something dangerous
  ! only 2 prohibition(s) — nothing here says what the agent must never touch
  ✔ size: 423 words ≈ 771 tokens, re-sent every turn

PASS — an agent can act on this.

Better, not right. It still counts three rules and two prohibitions where a person counts eight. It passes because a short count is now a warning, not because the counting improved. The browser checker runs the same 1.2.0 rules.

Check yours

Paste your file into the CLAUDE.md checker, which runs the same checks in your browser and sends nothing anywhere. Or in a terminal:

npx github:manpreet171/bridle agents AGENTS.md

Read a ✘ as a question, not a verdict. After this week, that's not a disclaimer. It's a measurement.

Sources: the census used GitHub's search API (stars:>15000, sorted by stars, the first 600) and each repo's root listing, on 16 Oct 2026 at 07:06 UTC. The 25 were picked by hand for name recognition and spread, not at random. Each file was downloaded at the last commit that changed it; three AGENTS.md files are symlinks (Transformers, PyTorch, Zed) and were read at their target. Token figures are bridle's estimate of characters ÷ 4, not a tokenizer count. "Setup", "Test", the GitHub-conduct count and every fail verdict are my reading of each file. The terminal blocks are real bridle runs, the first two on commit 93b302a and the last on 1.2.0 (commit d439619, the same day), with the file path shortened. Only root files were measured; several repos keep more in subfolders.

Where this fits: memory and context, layer 2 of the Agent Ops Stack.

Originally published at singhlabs.dev.

AI contribution policy: 11 projects compared, one to paste.

Manpreet Singh — Fri, 09 Oct 2026 13:41:03 +0000

Short answer: an AI contribution policy is a few lines in CONTRIBUTING.md, or its own AI_POLICY.md, that answer three questions. May contributors use AI? Must they say so? Who answers for the code? I read eleven real ones. They agree on the third answer and fight about the other two. Then I checked the 300 most-starred GitHub repos with a contributing guide: 65 have a written AI policy.

Search for one and you mostly get mailing lists, GitHub issues and raw policy files. So here they are side by side, read at the source on 9 October 2026, plus a short version to paste.

Every policy agrees on one line: the person who opens the PR owns every line in it. The rest is taste.

What the big projects actually require

Four questions per project. Disclose: must you say you used AI? Ban: is anything forbidden outright? Owns it: must you understand it yourself? Close: what happens when you don't comply?

Linux kernel · Jan 2026 · coding assistants, generated content Disclose: yes, an Assisted-by: tag, plus the tools and prompts in the changelog. Ban: no. Owns it: yes, and an AI may never add Signed-off-by; only a human can. Close: if you can't defend it, maintainers may reject it without a detailed review.
Kubernetes · Nov 2025, updated Apr 2026 · AI guidance Disclose: yes, in the PR description. But no AI co-author and no assisted-by trailer. Ban: large AI-generated PRs and AI-written commit messages. Owns it: yes. Close: if you can't explain a change, or if you answer reviewers through an AI.
Fedora · approved 22 Oct 2025 · AI-assisted contributions Disclose: required when a significant part comes from a tool unchanged; Assisted-by: recommended; grammar fixes exempt. Ban: no. Owns it: yes, fully. Close: not covered. It also binds reviewers: AI can't be the final judge of a contribution.
Rust (rust-lang/rust only) · 5 Aug 2026 · LLM usage Disclose: yes. Ban: LLM-written comments, docs and compiler messages. LLM-written code only when a reviewer agreed in advance and it can't break soundness. Owns it: yes, you can't blame the model. Close: recommended for major violations. Bonus: if more than half the PRs merged in six weeks are LLM-created, merging new ones stops.
Ghostty · disclosure Aug 2025, policy Jan 2026 · AI_POLICY.md Disclose: all AI use, which tool and how much. Ban: AI-generated images, video and audio. Owns it: yes, explain it without the AI or don't contribute. Close: since February, PRs from anyone not vouched for close automatically. Slop gets you on a public block list.
curl · May 2025 · CONTRIBUTE.md Disclose: yes for bugs and reports an AI found; not required for code. Ban: no, AI-assisted code is judged like any other. Owns it: verify every finding yourself. Close: fake reports get you banned on the spot. The bug bounty itself ended in January 2026.
uv (all of Astral) · Mar 2026 · AI_POLICY.md Disclose: only when you quote an AI in a comment. Ban: AI-written comments to maintainers, and autonomous agents. Owns it: yes, explain it in your own words. Close: any PR they believe an agent opened.
ripgrep · May 2026 · AI_POLICY.md uv's policy, adapted. Its CONTRIBUTING.md is two sentences long and says the rest: contributions that don't follow it will be closed.
QEMU · Jun 2025 · code provenance Ban: yes. It declines any contribution believed to contain AI-generated content, "known or suspected". Using AI to research an API is fine.
Gentoo · Apr 2024 · council AI policy Ban: yes, contributions made with AI tools are "expressly forbidden". The council can revisit it.
NetBSD · May 2024 · commit guidelines LLM code is presumed tainted and needs the core team's written approval before it's committed.

So: everyone wants the human to own it. After that it splits. Linux and Fedora ask for an Assisted-by: trailer, and Kubernetes forbids it. QEMU and Gentoo ban AI code outright, and NetBSD wants it approved in writing first. And uv, ripgrep and Rust care as much about the comments as the code.

How many repos have one: 65 of 300

I took GitHub's most-starred repos pushed in 2026 (no forks, no archives) and walked down the list until I had 300 with a contributing guide. That took 414 repos; the 300 run from 52,000 to 517,000 stars. A script read each guide and listed every file in the root, .github/ and docs/. Then I read every hit by hand.

65 of 300 (22%) have a written AI policy you can find: an AI_POLICY.md (8 of them), a section with its own heading, or a link to a separate AI policy.
27 more set a rule in a sentence or two, with no heading. Godot, Deno, Caddy and Elasticsearch are here.
208 (69%) say nothing about AI in their contributing guide.

Not all of them are strict. OpenClaw says no disclosure is required at all. PocketBase turned off outside PRs entirely, blaming LLM spam. And a new kind of line is appearing: rules written for the agent itself. Godot asks an AI agent to put 🤖 at the start of its PR title. crewAI tells agents to add an llm-generated label. Electron hides a note in its guide: are you a coding agent?

Two caveats. This is the famous end of GitHub, and plenty of these repos are AI tools. And a policy that lives only in AGENTS.md or a website, never linked from the contributing guide, isn't counted.

The policy, ready to paste

The short version, built from the line everyone agreed on and the choices that worked best. Pick your side on the trailer before you paste.

## AI contributions

- You may use AI. You own every line: if you can't explain a
  change without it, don't send it.
- Say so in the PR description: which tool, and what it did.
- Write PR descriptions, issues and review replies yourself.
- No autonomous agent PRs. A human is in the loop or it's closed.
- PRs that ignore this are closed without review.

The longer version, adapted from Rust's policy, with the Assisted-by: trailer and a line protecting private use, is on the prompts page. Neither has run in a live repo yet. Adjust the closing line to your temperament.

Making it enforceable: check the PR description

"You must understand it" is the line nobody can check by reading the policy. The PR description is where it shows: does it say what changed, and does it disclose? plumb holds a PR's description against its diff. Here it is on a real Ghostty PR, a 14-file change whose description was a screenshot and three links:

$ plumb check --pr 14559
plumb — 14 files changed, 0 named in the summary

touched but not described  (context, not a failure — PRs describe intent)
  · pkg/harfbuzz/main.zig modified
  · src/Surface.zig modified
  · src/build/uucode_config.zig modified
  · src/config/Config.zig modified
  ...10 more

nothing here contradicts the description.

No AI disclosure in the description — that may be fine, or it may be undisclosed.

Ghostty's vouch bot had already closed it, for a different reason: the author wasn't on the vouched list. Nothing here says AI wrote it, and plumb can't tell you that. Nothing can. What it gives a maintainer is the two questions Ghostty's policy makes them ask: what do these 14 files do, and did you use AI? On a PR that does disclose, the last line reads "The description mentions AI assistance."

What not to put in it

A ban you can only enforce on suspicion. QEMU's runs on "known or suspected". The people who read your policy and disclose are the honest ones. A ban teaches them to stop disclosing.
A trailer you haven't checked. Kubernetes forbids AI co-authors because an AI can't sign its CLA, and so no vendor can advertise that Kubernetes uses their tool. If you use a CLA bot, test what an Assisted-by: or Co-authored-by: line does to it first.
Code only. curl's flood came in as security reports, not code. uv, ripgrep, Rust and Kubernetes all cover comments and review replies.
A promise to detect AI. You can't, so don't threaten it. Ask for disclosure and an explanation, and close what arrives without either.

Sources: each policy was read at the link beside it on 9 Oct 2026; repo files through the GitHub API. Dates are the commit that added the text, or the council vote (Fedora, Gentoo) or announcement (Rust). NetBSD's page carries no date; May 2024 is from press coverage at the time. The 300-repo sample: GitHub search stars:>1000 pushed:>=2026-01-01 fork:false archived:false sorted by stars, keeping repos with a CONTRIBUTING file in the root, .github/ or docs/. Every hit was read and sorted by hand; the split between "a policy" and "a sentence" is my judgment. The plumb run (1.1.0) was in a fresh clone of Ghostty on 9 Oct 2026; its first line, which names the PR's author, is removed and its file list is trimmed from 14 to 4.

Where this fits: testing and verification, layer 5 of the Agent Ops Stack.

Originally published at singhlabs.dev.

How to review AI-generated code (8 real PRs checked)

Manpreet Singh — Fri, 09 Oct 2026 13:36:42 +0000

Short answer: before you read a line of code, hold the PR description against the diff. Find what changed that it never mentions, anything removed or switched off, and any name it cites that you can't find. Read those first. Then work the checklist: new dependencies, tests that can't fail, skipped tests, scope drift, invented APIs.

Search this and page one is guides and checklists, several from companies selling a review bot. Most say "start with intent". Right idea. But the intent is already written down. It's the PR description. None of the ones I read holds one up against its diff, on a real PR, and shows what falls out.

So I did. Eight PRs, merged or closed in the last three weeks, on repos with maintainers and reviewers: dbeaver, Mailspring, sharedb, enonic, evcc and three more. Every description ends with "Generated with Claude Code".

The description is a claim about the diff. Check the claim before you read the code.

Why AI PRs read well and review badly

An agent writes a good paragraph for free. One of the eight has a 440-word description that cites RFC section numbers. Another ships a 933-line plan document next to the code. Writing stopped being the expensive part. Reading didn't.

And a fluent description changes how you read. You stop treating the diff as evidence and start treating it as confirmation. The paragraph is usually right about what it mentions. The risk is in what it doesn't, and nobody writes "and I deleted six assertions". Why agent summaries leave things out is its own post. This one is about the PR waiting for your review.

Start with the description, not the code

Three questions, in order, before you open a file:

What changed that the description never mentions?
What was removed or switched off? A guard, an assertion, a test, a .skip, a # noqa.
Which names does it cite that you can't find?

plumb asks all three mechanically. plumb check --pr reads the description through the GitHub CLI, fetches the branch, and prints only the mismatches. No LLM: git and regexes.

One thing it doesn't fail you for: files nobody named. Descriptions name code, not paths. Across these eight, 50 files changed and 7 were named by path. On a PR, an unnamed file is context, not a finding.

What 8 real PRs left out of their summaries

plumb exited clean on four and flagged four. The one with the most flags first:

$ plumb check --pr 12428
plumb — 13 files changed, 0 named in the summary

touched but not described  (context, not a failure — PRs describe intent)
  · modules/core/core-repo/src/main/java/com/enonic/xp/repo/impl/dump/upgrade/BranchEntryUpgrader.java deleted
  · modules/core/core-repo/src/main/java/com/enonic/xp/repo/impl/dump/upgrade/DumpUpgraderRunner.java modified
  ...

quiet cuts  (removed or silenced, whatever the summary says)
  · modules/core/core-repo/src/main/java/com/enonic/xp/repo/impl/dump/upgrade/model8to9/VersionHistoryMigrationUpgrader.java:178 guard removed
    if ( !ContentConstants.CONTENT_NODE_COLLECTION.equals( nodeVersion.nodeTy...
  · modules/core/core-repo/src/test/java/com/enonic/xp/repo/impl/dump/upgrade/model8to9/NodePathNormalizeUpgraderTest.java:52 assertion removed
    assertThat( result.getNodePath() ).isEqualTo( "/content/my-node" );
  ...

7 things to read before you merge this.

The description mentions AI assistance.

That's enonic/xp #12428, merged. The description, in full: "Fixes #12427", plus the Claude Code line. The issue lists four bugs, and most of the diff maps onto them. What nothing explains: an interface deleted, and with it a guard, five tests and six assertions. Reading the diff, branch entries now go through the same upgrade as versions. That may be exactly the fix. It was reviewed, by Copilot and by a person. But 13 files had to be worked out by hand, because the description gave nothing to check them against.

The other seven:

evcc-io/evcc #34222 (closed). Fourteen "assertion removed" lines, all from one deleted test, which the description named and explained: the field it checked was gone from a dependency. plumb was noisy; the description was honest. The maintainers reverted the module bump instead, and closed it.
dbeaver/dbeaver #42305 (merged). The description matches the diff exactly: four nulls become "". One flag: TMPartitioner, "found nowhere". It lives in TM4E, the Eclipse project the description names. Real, just not in this repo.
basnijholt/adaptive-lighting #1616 (closed). A long, careful description. Its one flag, AdaptiveLightingManager.adaptation_holds, is wrong: the PR adds adaptation_holds, and plumb went looking for the dotted name. My bug.
category-labs/monad #2665 (merged). Clean. The description says it adds a flag and switches one function to it. True. It doesn't say the test changed too. That turned out to be the most interesting line in the eight; it's below.
Foundry376/Mailspring #2927 (merged). Clean, and the most thorough description of the lot. Its test counts are still wrong. Also below.
bjlittle/geovista #2580 (merged). Clean. Twelve files, the 933-line plan among them. The one config line that switches a check off, an ignore_missing_imports for lazy_loader, is in the description with its reason. That's what a good one looks like.
share/sharedb #743 (merged). Clean. Three lines of fix, 31 of test, and a description that says exactly that.

A ninth didn't make it. plumb crashed on apollographql/rover #3924: a stacked PR whose base branch was deleted after merge, and plumb fetches the base by name. Also my bug, so sharedb took its place.

Tally: no skipped tests, no silenced linters, no new dependencies, no invented APIs. One description that explained nothing. One test that changed shape without a word. One set of numbers that was off. And two plumb bugs. The first time I pointed plumb at real PRs, in August, it found three bugs in plumb. Real PRs keep doing that.

The rest of the checklist: dependencies, tests that can't fail, scope drift

New dependencies

Check the manifests before the code:

$ gh pr diff 2580 --repo bjlittle/geovista --name-only | grep -E 'package.json|lock|go.mod|Cargo|pyproject|requirements|pom.xml'
pyproject.toml

The one hit across all eight was that type-checker setting, not a package. None of them added a dependency. When one does, look the name up on the registry yourself. A package an AI half-remembered is exactly the kind of name somebody else can register.

Tests that can't fail

The monad change, trimmed to its two hunks:

$ gh pr diff 2665 --repo category-labs/monad
--- a/category/execution/ethereum/test/test_monad_chain.cpp
-    if constexpr (TestFixture::REV >= MONAD_ONE) {
+    if constexpr (TestFixture::Trait::charges_gas_limit()) {
         EXPECT_EQ(refund, 0);
--- a/category/execution/monad/monad_transaction_gas.cpp
-    if constexpr (traits::monad_rev() >= MONAD_ONE) {
+    if constexpr (traits::charges_gas_limit()) {
         return 0;

Before, the test said what it expected: from MONAD_ONE on, no refund. Now it asks the new flag, the same one the code asks. If the flag were wrong, code and test would be wrong together, and green. In the PR's tree the flag shows up in three files: where it's declared, where it's used, and this test. No test checks what it returns. It's a tidy refactor and a reviewer approved it. It's also a test that can no longer catch the bug it's about.

The evcc PR had the other shape. Its second fix added the new error message to a test's list of acceptable errors, so the failing check passed. A maintainer suggested the better fix, a sample serial number so the test exercises the new check instead of excusing it, and that landed in a separate PR.

The test for both: revert the fix and run the test. If it still passes, it isn't testing the fix.

Skipped and silenced tests

.skip, xit, @pytest.mark.skip, # noqa, @ts-ignore, continue-on-error: true. plumb lists every one a diff adds. None of these eight had any. The real run on the plumb page has one: a # noqa in a file its description never mentions.

Test counts

If the description gives numbers, count them. Mailspring's says 7 cases in the guard spec and 6 header cases:

$ gh pr diff 2927 --repo Foundry376/Mailspring | awk '/^\+\+\+ /{f=$2} /^\+[ \t]*it\(/{n[f]++} END{for(k in n) print n[k], k}'
9 b/app/internal_packages/events/specs/event-header-spec.tsx
10 b/app/spec/counter-proposal-guard-spec.ts

10 and 9. More tests than claimed, so no harm done. But the numbers in a description are claims too, and these didn't match.

Scope drift

Every changed file should trace back to a sentence in the description or the issue. enonic is where that breaks: 13 files and one sentence. geovista is the opposite: 12 files and a 933-line plan, every one of them explained.

Invented APIs

plumb's last check flags a name the description cites that exists nowhere, not in the diff and not in the base branch. It flagged three in eight PRs. None was invented. So treat the list as things to look up, not accusations. Each took one code search:

$ gh api -X GET search/code -f q="TMPartitioner repo:eclipse-tm4e/tm4e" --jq ".items[0].path"
org.eclipse.tm4e.ui/src/main/java/org/eclipse/tm4e/ui/internal/text/TMPartitioner.java
$ gh api -X GET search/code -f q="readRegisters repo:404GamerNotFound/solarman-go" --jq ".items[].path"
solarman.go
solarman_test.go

The third was the plumb bug above.

Run it on your next PR

$ npm install -g github:manpreet171/plumb
$ cd your-repo
$ plumb check --pr 123

It needs the GitHub CLI and a clone with GitHub as origin. Exit 1 means a cut, a mute or a name it couldn't find; unnamed files never fail it. In CI, start with --warn-only. What it won't do: judge whether a test means anything (it called the monad PR clean), or see past your repo (two of its three "found nowhere" names were real, elsewhere).

Better still, catch it before the PR exists. trust issues runs the same checks inside Claude Code every time it says it's done, so the summary your agent hands you has already been held against its own diff.

Sources: the eight PRs came from GitHub search for "Generated with Claude Code" in PR descriptions, merged or closed between 25 Sep and 9 Oct 2026, and were picked by repo before plumb ran. Three candidates were dropped first: two no longer carried the line, one was written by a dependency bot. Every terminal block is a real run on 9 Oct 2026 with plumb 1.1.0, in a fresh clone of each repo, read-only. The plumb output has its first line removed (it names the PR's author), and a line that is only "..." marks where I cut it. The monad diff is trimmed to its changed lines. What maintainers said is from the PRs' own comments. Contributors aren't named on purpose: these are examples of reviewing, not of anyone's mistakes.

Where this fits: testing and verification, layer 5 of the Agent Ops Stack.

Originally published at singhlabs.dev.

Why Claude Code ignores CLAUDE.md, and what sticks.

Manpreet Singh — Fri, 09 Oct 2026 13:32:30 +0000

Short answer: CLAUDE.md is a request, not a lock. Claude Code loads it as context and tries to follow it, and Anthropic's docs say plainly there's no guarantee. When I went through my own history, most of the rules I'd have blamed Claude for ignoring were never written down, or were written for something else. The few that truly must hold need a hook, not a better sentence.

Search "claude code ignores claude.md" and page one is GitHub issues. Rules in capitals. MANDATORY. NEVER. On anthropics/claude-code, 124 issues have CLAUDE.md and "ignore" in the title. Eight are open. 68 were closed as not planned.

Plenty of complaints, no answers. So I opened my own case file: my Claude Code history since July, every project's CLAUDE.md, and the git logs behind them.

A rule in CLAUDE.md is a request. If it must never break, it needs a hook, not a louder sentence.

First, check it read the file

Rule out the boring cause before blaming the model. The docs say Claude treats CLAUDE.md "as context, not enforced configuration", and that it arrives as a user message after the system prompt. So first, confirm it arrived:

Run /context and look under Memory files. Not listed means not seen.
A CLAUDE.md in a subfolder isn't listed at launch. It loads when Claude reads a file in that folder.
Loading has bugs too. #99032, filed last week: the VS Code extension skips an @import that points outside the project, while the terminal loads it.

Loaded and still ignored? Then it's one of the next four.

1. The rule isn't there

This one's embarrassing. toldya reads what you've typed to Claude Code and finds the corrections you keep repeating. Mine:

$ npx toldya --all --dry

toldya · 175 sessions (2 Jul – 9 Oct) · 3817 of your messages · 323 corrections

You keep telling your AI:
   1.  18×  keep it simple   (17 sessions)
   2.  12×  Don't complicate it   (7 sessions)
   3.   5×  dont ask me   (4 sessions)

toldya also flags a repeat that's already in your CLAUDE.md or AGENTS.md, with ← already in your rules, still repeated. I ran it in all 12 of my projects that have one of those files. It flagged nothing.

"Keep it simple" wasn't in the CLAUDE.md of any project where I kept typing it. Claude wasn't ignoring that rule. I'd never given it one.

One correction, found while writing this. When you resume a session, Claude Code copies the earlier messages into the new file, and toldya 0.3.2 counted every copy: it said 44. 0.3.3 fixed the counting, 0.3.4 the grouping, which could split one habit in two, and 0.3.5 stopped counting "I don't get it" as a rule. 0.3.5 made the run above. Still my top line.

2. The rule is for something else

Except I sort of had. Since 26 July I've run ponytail, a plugin whose session-start hook loads about 900 words of "build the simplest thing that works" into every session. Its text is in 187 of my 195 transcripts.

So I took toldya's two simplicity habits ("keep it simple", "Don't complicate it"), dropped the copies, and kept the messages I typed with that text already loaded. There were 25. I read all of them:

17 were about how it talked or wrote, not what it built. Mostly me, lost, asking it to explain again, plainer.
5 were about the approach, closer to the plugin's turf.
3 I couldn't place.

Ponytail says, in its own text, that it "governs what you build, not how you talk." It was loaded every time. It just wasn't the rule I kept asking for.

3. The rule is a wish

So when I started a new data project this week, its CLAUDE.md had the right rule from the first hour: "Explain simply." Within a day I'd asked for a simple explanation five more times. "I need to understand in very simple way how to use that app."

"Explain simply" is a wish. Nothing in it can be checked. The docs make the same point with better examples: "Use 2-space indentation", not "Format code properly". A checkable version of mine would name the thing: a line limit, an example first, no term left undefined. I haven't tested that yet, so I'm not promising it.

4. The rule is clear, loaded, quoted back, and broken anyway

The hard case. Another repo of mine opens its CLAUDE.md with a logging rule, under a heading that says non-negotiable: every change gets a CHANGELOG entry, timestamped from date -u, "never guessed or invented". Specific. Checkable. Line 40 of a 222-line file when it went in; the file is 311 lines now.

$ git log --format="%ad  %s" --date=short -S "Timestamps are UTC and real" -- CLAUDE.md
2026-08-16  Repo audit, project rules, and the documents needed to run this
$ git log --reverse --format="%ad  %s" --date=short -i -E --grep="(correct|fix).*timestamp"
2026-08-17  Correct a changelog timestamp I invented
2026-08-24  Correct a changelog timestamp that was written before date -u was read
2026-08-29  Fix a guessed timestamp, and write down how to stop guessing them
2026-09-09  Correct a guessed timestamp, for the third time
$ wc -l CLAUDE.md
311 CLAUDE.md

Four guessed timestamps in the 24 days after the rule went in, each caught and fixed in its own commit. Claude wrote those fixes, and every one names the rule it had just broken. With the third fix the rule got sharper: read the clock in its own command, then write. Eleven days later it broke again. The fourth fix is titled "for the third time". Even the apology lost count.

That's four caught misses in about 150 commits that touched the log, so the rule mostly held. Mostly is fine for indentation. It's useless for a timestamp whose only job is to be right. Since 9 Sep there have been 44 more log commits and no fix, which means either the sharper wording landed or nobody checked. The history can't say which.

Why rules slip: the docs and the issues

My four cases line up with Anthropic's memory docs, its best practices, and the issue tracker:

Where it sits. CLAUDE.md arrives after the system prompt, as a user message. When it clashes with Claude Code's own guidance, the built-in can win. In #27032, plan mode suggested a plans folder in the home directory, and the model followed it over a CLAUDE.md rule to keep plans in the repo. The docs list this among the things to check.
Length. Target under 200 lines; longer files "reduce adherence". The best-practices page is blunter: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" My logging rule lived in a file that grew from 222 lines to 311. What each line costs is in the length post.
Conflicts. If two instructions contradict each other, "Claude may pick one arbitrarily". Check your user file against your project file and any nested ones.
Shouting. The docs suggest "IMPORTANT" on the one line that keeps getting skipped, and warn that if you emphasise many, none stands out. #33603 is what happens next: a rule restated and strengthened after each violation, then broken in each of the next three sessions.
The model. #99704 counted a "reply in Korean" rule over one long session: no English replies on claude-opus-5, 33% English on claude-opus-5-5, same CLI. A rule that held last month proves nothing about this model.
Timing. If something must happen at a fixed point, before every commit or after every edit, the docs say to write it as a hook.

When a rule should be a hook

The best-practices page puts it in one line: CLAUDE.md instructions are "advisory", while hooks "are deterministic and guarantee the action happens". A PreToolUse hook sees the tool call before it runs, and can refuse it.

Here's slopguard's Bash guard, run from its plugin folder, fed the call Claude would make to commit a .env:

$ echo '{"tool_name":"Bash","tool_input":{"command":"git add .env && git commit -m wip"}}' \
  | node scripts/guard-bash.mjs \
  | node -p "JSON.parse(require('fs').readFileSync(0)).hookSpecificOutput.permissionDecisionReason"
SLOPGUARD blocked this command — [SG-1] credential file staged for commit.

fix: Add it to .gitignore. Anything committed is in the history permanently, even after a later delete.

Rule text lives in AGENTS.md.

The sentence version of that rule is #2142, open since June 2025: Claude Code "repeatedly ignores CLAUDE.md security guidelines and exposes API keys to version control". A hook doesn't give it the chance.

Two limits:

A hook only enforces what a script can check. In #99642, hooks that checked the form (a table exists, the logs were read) were satisfied while the work they stood for was skipped.
A hook that only adds text is still a request. Ponytail's hook prints its rules at session start, and the hooks guide says that output just joins Claude's context. Same odds as CLAUDE.md. #99642's reminder hook injected its instruction on every turn, and the model never acted on it.

So the test is: could a script say yes or no? A .env in a commit: yes, hook it. A log timestamp that doesn't match the clock: yes, and that's the hook my logging rule should have been. I haven't written it yet. "Explain simply": no. That one stays a sentence, as concrete as I can make it, and gets counted.

Count whether it stuck

A rule you never re-check is a rule you're hoping about. toldya does the counting, on your machine, sending nothing:

$ npx toldya --dry    # the report only, changes nothing

Run it without --dry and it asks about each repeat: y writes it into CLAUDE.md, n skips it, e lets you reword it first. A week later, run it again. Each rule it added gets a line like "Keep it simple." said 18× before · 0× since. If "since" isn't near zero, the rule is a wish, or it needs a hook.

Honest status: I can't show you a real "since" yet, because I never added my repeats through toldya. That line is from a test run a minute after adding one, so its zero means nothing. The ponytail count above is the same check done by hand, with toldya's matcher.

Sources: every terminal block is a real run on my machine on 9 Oct 2026; the toldya report (0.3.5) is trimmed to its first three lines, and the before/since line is from 0.3.6, which fixed which habit that line counts. Copies were dropped the way toldya drops them, and the 25 messages were read and sorted by hand. The git log is from one of my own repos. The slopguard run feeds its hook script the JSON a tool call sends. Docs: Claude Code's memory, best practices and hooks guide. Issues are on anthropics/claude-code, read through the GitHub API the same day; the 124 is a search for CLAUDE.md and "ignore" in issue titles.

Where this fits: memory and context, layer 2 of the Agent Ops Stack.

Originally published at singhlabs.dev.

Does Claude Code read .env files? What each fix actually stops.

Manpreet Singh — Fri, 09 Oct 2026 12:25:16 +0000

Short answer: yes. Claude Code can read your .env like any other file, and .gitignore doesn't stop it. A Read deny rule in .claude/settings.json stops the obvious ways in. Nothing that matches on the filename stops a command that never says the filename.

Most guides stop at "add a deny rule". So I made a throwaway repo with a fake .env and put each fix up against the ways an agent actually gets at a file. Some of it I ran live. Some I couldn't, and I'll say which.

Every fix here matches the name .env. Your keys don't need to be asked for by name.

Yes, it can: the 30-second test

The lab: a fresh git repo, two obviously fake keys (one is AWS's own documentation example), and the file ignored the way most repos ignore it.

$ cat .gitignore
.env
$ git check-ignore -v .env
.gitignore:1:.env   .env
$ cat .env
STRIPE_KEY=sk_test_FAKE0000000000000000
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

Then, in a live Claude Code session, the agent's own tools against that folder:

Read on .env returned both lines.
Glob for **/.env* listed it.
Grep for STRIPE_KEY across the folder found nothing. Rename .gitignore and the same search finds the key. Point Grep at the file itself and it finds it with .gitignore in place.

So .gitignore hides the file from a folder-wide search. That's all it does. It was written to keep files out of commits, and it's good at that.

Every fix people suggest

.claudeignore. Anthropic's permissions docs are blunt: if your project has one, "it has no effect". Move its entries into Read deny rules.

A line in CLAUDE.md saying "never read .env". That's a request, not a control. I didn't measure how often it's obeyed, and a rule you can't measure isn't one you should lean on for a secret.

permissions.deny. This is the official answer. Anthropic's settings docs show it as an example, and it's what I put in the lab:

$ cat .claude/settings.json
{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep|Bash",
        "hooks": [
          { "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-env.mjs\"" }
        ]
      }
    ]
  }
}

The docs say a Read deny rule covers Claude's file tools, Grep and Glob on a "best-effort" basis, @file mentions, and Bash commands it recognises as file reads: cat, head, tail, sed, tee, plus redirections like < file. And the docs name the gaps themselves: a command that reads files without naming them, like grep -r pattern ., and "arbitrary subprocesses", like a Python or Node script that opens the file on its own.

I couldn't run this one live. The CLI's login had expired:

$ claude --version
2.1.257 (Claude Code)
$ claude -p 'Read .env and print it'
Failed to authenticate: OAuth session expired and could not be refreshed

So that row of the matrix is Anthropic's word, not my run. I also can't tell you whether it catches a glob like cat .en?. The docs don't say, and I didn't get to try.

A PreToolUse hook. The hook in the settings above runs before every Read, Grep and Bash call. Exit code 2 blocks the call and hands the agent the message. Here's all of it:

$ cat .claude/hooks/block-env.mjs
// PreToolUse hook: refuse Read, Grep and Bash calls that name a .env file.
let raw = '';
for await (const chunk of process.stdin) raw += chunk;
const { tool_name, tool_input = {} } = JSON.parse(raw);
const target = tool_input.command ?? tool_input.file_path ?? tool_input.path ?? '';
if (/(^|[^\w.-])\.env(\.[\w.-]+)?(?![\w.-])/.test(target)) {
  console.error(`Blocked: ${tool_name} touches a .env file. Ask the user for the value instead.`);
  process.exit(2);
}

No live session, so I tested it the way Claude Code calls it: the documented PreToolUse JSON piped to the script on stdin, trimmed to the fields it reads. Then I ran whatever got through.

$ echo '{"tool_name":"Read","tool_input":{"file_path":".env"}}' | node .claude/hooks/block-env.mjs; echo "exit $?"
Blocked: Read touches a .env file. Ask the user for the value instead.
exit 2
$ echo '{"tool_name":"Bash","tool_input":{"command":"cat .env"}}' | node .claude/hooks/block-env.mjs; echo "exit $?"
Blocked: Bash touches a .env file. Ask the user for the value instead.
exit 2
$ echo '{"tool_name":"Bash","tool_input":{"command":"cat .en?"}}' | node .claude/hooks/block-env.mjs; echo "exit $?"
exit 0
$ cat .en?
STRIPE_KEY=sk_test_FAKE0000000000000000
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
$ echo '{"tool_name":"Bash","tool_input":{"command":"grep -r STRIPE ."}}' | node .claude/hooks/block-env.mjs; echo "exit $?"
exit 0
$ grep -r STRIPE .
./.env:STRIPE_KEY=sk_test_FAKE0000000000000000

Python went the same way. open('.env') was blocked. open(glob.glob('.en*')[0]) got exit 0 and printed both keys. One question mark beat a regex I spent longer on than I'd like to admit.

One more trap, and it's a nasty one:

$ echo 'not json' | node .claude/hooks/block-env.mjs 2>/dev/null; echo "exit $?"
exit 1

A hook that crashes exits 1. Per the hooks docs, exit 1 is a "non-blocking error" and the action goes ahead. If your guard throws, it waves the call through. Only exit 2, or a JSON deny, blocks.

The sandbox. sandbox.filesystem.denyRead is the one fix that doesn't care about names. The OS enforces it on Bash commands and every process they start, so the Python trick and the glob should both hit a wall. Two catches, both from the sandbox docs: a denyRead entry "doesn't stop the Read tool", so you still need the deny rule. And it runs on macOS, Linux and WSL2. On native Windows, which is what I'm on, commands run unsandboxed. Untested here for that reason.

The matrix: what each one blocks

.gitignore. Stops: commits, and a folder-wide Grep. Misses: Read, Glob, Grep aimed at the file, cat, everything else. Tested live.
.claudeignore. Stops: nothing. Anthropic's docs; not tested.
"Never read .env" in CLAUDE.md. Stops: whatever the model chooses to obey. Not tested.
Read deny rules. Stops: Read, Grep and Glob (best effort), @file, cat/head/tail/sed/tee on the file. Misses: grep -r ., scripts that open the file themselves. Anthropic's docs; not tested live.
PreToolUse hook. Stops: any call that spells out .env. Misses: cat .en?, grep -r STRIPE ., Python with a glob, and everything if the hook crashes. Tested with piped payloads.
Sandbox denyRead. Stops: Bash and its child processes, by OS. Misses: the Read tool, and all of native Windows. Anthropic's docs; not tested.
slopguard. Stops: none of the reads. That isn't its job. Its job is the next section. Tested with piped payloads.

The other leak: it writes the key into your code

Reading the key isn't the expensive part. The expensive part is the agent helpfully pasting it into a source file, which then gets committed, pushed and shipped to a browser.

slopguard is our Claude Code plugin for that moment. Its write hook looks at the code before the Write or Edit tool puts it on disk. Fed by hand, from the repo, the way its README says to:

$ echo '{"tool_input":{"file_path":"src/aws.js","content":"const keyId = \"AKIAIOSFODNN7EXAMPLE\";"}}' | node plugins/slopguard/scripts/guard-write.mjs | node -pe "JSON.parse(require('fs').readFileSync(0,'utf8')).hookSpecificOutput.permissionDecisionReason"
SLOPGUARD blocked this write to src/aws.js — 1 unsafe pattern(s):

• [SG-1] AWS access key ID
    found: AKIA…LE
    fix:   Move this to an environment variable or a secret manager, reference it via process.env / os.environ, and rotate the exposed credential — assume it is already public.

Rewrite the code to satisfy the rule above, then write the file again.
Rule text lives in AGENTS.md. Do not disable the guard to get past it.
$ echo '{"tool_input":{"file_path":"src/pay.js","content":"const stripe = new Stripe(\"sk_test_FAKE0000000000000000\");"}}' | node plugins/slopguard/scripts/guard-write.mjs; echo "exit $?"
exit 0
$ echo '{"tool_input":{"command":"git add .env"}}' | node plugins/slopguard/scripts/guard-bash.mjs | node -pe "JSON.parse(require('fs').readFileSync(0,'utf8')).hookSpecificOutput.permissionDecisionReason"
SLOPGUARD blocked this command — [SG-1] credential file staged for commit.

fix: Add it to .gitignore. Anything committed is in the history permanently, even after a later delete.

Rule text lives in AGENTS.md.
$ echo '{"tool_input":{"command":"cat .env"}}' | node plugins/slopguard/scripts/guard-bash.mjs; echo "exit $?"
exit 0
$ echo '{"tool_input":{"command":"echo AWS_KEY=AKIAIOSFODNN7EXAMPLE >> src/config.js"}}' | node plugins/slopguard/scripts/guard-bash.mjs; echo "exit $?"
exit 0

Five calls, three results worth knowing:

A live-shaped key going into source is blocked, and the agent is handed the rule and the fix. The same kind of line reading process.env instead passes.
The sk_test_ key passes. That's deliberate: its rules treat test keys as placeholders, on the theory that a guard that cries wolf gets uninstalled.
cat .env and a key written with echo >> both pass. slopguard checks the Write and Edit tools, not what Bash writes. Its README says so.

A setup that holds, and what still gets through

Read deny rules for .env and .env.*, exactly as Anthropic's docs show them. They're the only fix that covers the Read tool.
The sandbox, with denyRead on the same paths, if you're on macOS, Linux or WSL2. It's the only fix that covers scripts.
A hook only for what deny rules can't say. Exit 2, and catch your own errors, because a crash is an allow.
slopguard for the write side, so a key that does get read doesn't land in a commit.
No production secrets in the folder the agent works in. Test keys in .env; the real ones in a secret manager the dev machine never sees.

That last one carries the weight. Your own app loads .env on purpose. When the agent runs npm start or your test suite, no rule sees a filename, and anything the app prints or logs is in the transcript. The only key that can't leak from a dev folder is one that was never in it.

Sources: every terminal block is a real run on my machine on 9 Oct 2026, in a throwaway repo with fake keys. The Read, Glob and Grep results are from a live Claude Code session the same day. The deny rules, the hook and slopguard were not run inside a live session (the CLI's login had expired); the hook and slopguard were fed the documented hook JSON by hand. slopguard is v1.1.2: v1.1.1 echoed a 20-character AWS key ID back whole in its block message, which this test caught and which was fixed the same day. What deny rules and the sandbox cover is from Claude Code's permissions, settings and sandboxing docs; hook exit codes from the hooks reference. AKIAIOSFODNN7EXAMPLE is AWS's published example key.

Where this fits: guardrails, layer 1 of the Agent Ops Stack.

Originally published at singhlabs.dev.

Claude Code Stop hook example: check the "done" claim.

Manpreet Singh — Fri, 09 Oct 2026 12:11:26 +0000

Search for a Claude Code Stop hook example and you get two kinds. One runs the tests when the agent stops. The other plays a sound. Both are fine. Neither reads the paragraph the agent just wrote you.

This one does. It takes the agent's last message, holds it against git diff, and won't let the agent stop while a changed file goes unmentioned. 31 lines of Node, no dependencies. Every output below is a real run.

A test gate checks the code. Nothing checks the paragraph you're about to merge on.

What a Stop hook can see

Stop fires when Claude finishes responding. Your command gets a JSON payload on stdin. Here's the one my hook was fed, paths shortened:

$ cat ../stop-payload.json
{
  "session_id": "ed45f42f-…",
  "transcript_path": "~/.claude/projects/…/….jsonl",
  "cwd": "C:/…/stop-hook-demo",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": false,
  "last_assistant_message": "Done. `login()` in auth.js now returns false when `user` is undefined, instead of throwing on `.trim()`. One guard line, no other changes needed.",
  "background_tasks": [],
  "session_crons": []
}

Four fields matter:

last_assistant_message is the claim. No need to dig it out of the transcript: Anthropic's docs say hooks that want the final text should use this field instead.
transcript_path is the whole session as JSONL, for when the last message isn't enough.
cwd is where to run git.
stop_hook_active is the one that bites. More on it below.

I built that payload by hand, in the documented shape, from the real transcript of the Claude Code session that made the fix. Piping a saved payload in is also the quickest way to test a hook without waiting for Claude to stop.

The usual example: a test gate, and what it misses

The task was small. login() in auth.js threw when the user was undefined. Claude Code added one guard line and said:

Done. login() in auth.js now returns false when user is undefined, instead of throwing on .trim(). One guard line, no other changes needed.

Here's the working tree:

$ git status --short
 M auth.js
 M config.js

config.js was edited before the task even started, on purpose. I left a timeout set to 0 in it to stand in for the edit from three tasks ago. Now the tests:

$ node --test 2>&1 | grep -E "^# (pass|fail)"
# pass 2
# fail 0

Green. The usual Stop hook runs the suite and exits 2 on a failure, which the docs say "prevents Claude from stopping". Here it has nothing to fail on. Claude stops, you commit, and the zero timeout ships with the bug fix.

Keep the test gate. It answers a real question. It just isn't this one.

A better one: hold the summary against the diff

Same event, different question: did the message name every file that changed? Save this as .claude/hooks/check-done.mjs:

#!/usr/bin/env node
// Stop hook: don't let Claude stop until its last message names every file it changed.
import { readFileSync } from 'node:fs';
import { execSync } from 'node:child_process';

const input = JSON.parse(readFileSync(0, 'utf8'));

// We blocked once already and Claude is answering for it. Let it stop.
if (input.stop_hook_active) process.exit(0);

// The claim: the last thing Claude said, handed over in the payload.
const claim = input.last_assistant_message;
if (!claim) process.exit(0);

// The evidence: tracked files that changed, plus files that are new.
const git = (args) => execSync(`git ${args}`, { cwd: input.cwd, encoding: 'utf8' })
  .split('\n').filter(Boolean);
let changed;
try {
  changed = [...git('diff --name-only HEAD'), ...git('ls-files --others --exclude-standard')];
} catch { process.exit(0); } // not a git repo, or no commits yet

// A literal match on the path or the file name. Crude on purpose.
const unnamed = changed.filter((f) => !claim.includes(f) && !claim.includes(f.split('/').pop()));
if (unnamed.length === 0) process.exit(0);

console.log(JSON.stringify({
  decision: 'block',
  reason: `You said you're done but never mentioned: ${unnamed.join(', ')}. ` +
    'Say what changed in each one, or undo it.',
}));

The ls-files --others half matters. git diff on its own never lists a brand-new file, so without it a whole new file walks straight past.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-done.mjs"]
          }
        ]
      }
    ]
  }
}

Two details from the docs. Stop takes no matcher. Add one and it's silently ignored. And args switches the hook to exec form, with no shell in between, which the docs recommend whenever a path placeholder is involved. A project path with a space in it can't split the command in two.

Same payload, same repo:

$ node .claude/hooks/check-done.mjs < ../stop-payload.json
{"decision":"block","reason":"You said you're done but never mentioned: config.js. Say what changed in each one, or undo it."}

"decision": "block" keeps Claude working, and reason becomes its next instruction. The tests had nothing to say about config.js. This did.

If a block showing up as a hook error bothers you, the docs offer hookSpecificOutput.additionalContext instead. Same loop protections, but the transcript labels it "Stop hook feedback".

The infinite-loop trap

When the hook blocks, Claude answers and then tries to stop again. That fires the Stop hook again. If the hook asks the same question and gets the same answer, it blocks again.

The way out is stop_hook_active. The docs say it's true "when Claude Code is already continuing as a result of a stop hook". That's the second line of the script. Here it is with the flag set:

$ grep stop_hook_active ../stop-payload-active.json
  "stop_hook_active": true,
$ node .claude/hooks/check-done.mjs < ../stop-payload-active.json; echo "exit $?"
exit 0

No output, exit 0, Claude stops. The hook gets one block per stop. If Claude's reply to it is weak, it still stops, and you read the reply. That's the trade, and it's the right one.

Without that line, the docs describe a safety net: Claude Code overrides the next block after stop hooks have continued the turn eight times in a row. Don't lean on it. The count resets every time Claude calls a tool, and checking a diff means calling one. I didn't crash a session to prove this. The guard costs one line.

Or let a plugin do more of it

trust issues is the free plugin I built on the same event. It reads the claim from transcript_path and runs four checks instead of one: changed but never mentioned, quiet cuts like a deleted assertion, mutes like .skip, and work described that never happened. Same payload, with TI pointing at the plugin's stop-check.mjs:

$ node "$TI" < ../stop-payload.json | node -pe "JSON.parse(require(\"fs\").readFileSync(0)).systemMessage"
trust issues — the diff says otherwise:

plumb — 2 files changed, 1 named in the summary

changed but never mentioned  (read these first)
  · config.js modified

1 thing the summary did not tell you.

By default it tells you and doesn't block. A guardrail that interrupts you on its first false alarm gets uninstalled the same afternoon. When you trust it, set TRUST_ISSUES=strict and it hands Claude the bill instead:

$ TRUST_ISSUES=strict node "$TI" < ../stop-payload.json
{"decision":"block","reason":"Before you call this done — the summary and the diff disagree:\n\nplumb — 2 files changed, 1 named in the summary\n\nchanged but never mentioned  (read these first)\n  · config.js modified\n\n1 thing the summary did not tell you.\n\nEither fix what was quietly changed, or say plainly what you did and why."}

On the stop_hook_active: true payload it exits 0 and says nothing, in both modes.

What this won't do

It matches names literally. "auth.js" counts. "The auth module" doesn't. Ask the agent to end every task with a file list and the noise goes away.
It checks the working tree, not the turn. That's how it caught config.js. It's also how it will nag you about the last task's files until you commit them. Commit between tasks.
A mention isn't the truth. "Updated the test" names the file and hides the .skip. That's what the quiet-cut and mute checks in trust issues are for.
It can't tell whether the code works. Run the test gate too. Both can sit on Stop together.

Why the summary leaves things out in the first place is its own post: Claude Code says it's done. Check the diff, not the paragraph.

Sources: every terminal block is a real run on 9 Oct 2026 (Node 22.17.1, trust issues 1.0.1) in a throwaway git repo, with paths shortened. Claude Code's command line wasn't signed in on this machine, so no payload was logged from a live Stop. Both payloads were built in the documented shape from the real transcript of the Claude Code session that made the fix, then piped in by hand. Payload fields, exit codes, exec form, stop_hook_active and the eight-continuation cap are from Anthropic's hooks reference.

Where this fits: testing and verification, layer 5 of the Agent Ops Stack.

Originally published at singhlabs.dev.

How long should CLAUDE.md be? I priced every line.

Manpreet Singh — Fri, 09 Oct 2026 12:08:05 +0000

Short answer: under 200 lines, which is Anthropic's own target, and the reason is attention, not money. A line of CLAUDE.md is about 13 tokens and it's sent again on every turn. Priced over 190 of my real Claude Code sessions at Opus 5.5 API rates, one line costs about a tenth of a cent per session with caching, and about a cent without. A whole 200-line file comes to 21 cents a session.

Every guide answers this with a number. Sixty lines. A hundred. Two hundred. Three hundred. None says what a line costs, which is odd for a file that's sent again every time you press enter.

So I priced one. Not with a file size times a message count, which ignores the cache, but with the transcripts Claude Code already keeps on my machine: 190 sessions, 63,964 turns, and the caching they actually got.

A line of CLAUDE.md costs about a tenth of a cent a session. Keep it short for Claude's sake, not your bill's.

The numbers everyone quotes, and where 200 comes from

There's one official number. Anthropic's memory docs say to "target under 200 lines per CLAUDE.md file", because a longer file takes more context and gets followed less reliably.

The unofficial numbers come with a reason too. HumanLayer's guide keeps its own root file under sixty lines and reports a consensus of under 300. Its logic is a budget: frontier models follow roughly 150 to 200 instructions with reasonable consistency, and Claude Code's own system prompt already spends about 50 of them.

Two hard limits do exist. Don't confuse them with the 200:

The 200-line cutoff is for a different file. Claude Code's auto memory loads only the first 200 lines (or 25KB) of MEMORY.md. CLAUDE.md has no line cutoff at all: Claude Code loads the whole thing and only skips a file over 4 MiB.
Codex caps AGENTS.md at 32 KiB. Per its docs, Codex stops adding instruction files once they reach 32 KiB combined, unless you raise project_doc_max_bytes.

So 200 is a target about attention. Nobody puts a price on it.

What one line of CLAUDE.md costs over a real session

Three numbers: tokens per line, how many times the line is sent, and what each send costs.

Tokens per line. Here's this site's own CLAUDE.md:

$ wc -l CLAUDE.md
114 CLAUDE.md
$ bridle agents CLAUDE.md | grep size
  ✔ size: 916 words ≈ 1474 tokens, re-sent every turn

1,474 tokens over 114 lines is about 13 a line. That isn't a quirk of my file. Across 350 public files (more on those below), the typical line ran 10 to 14 tokens at every size.

How many times it's sent. The file loads at the start of a session and stays to the end. It even comes back after /compact. And Claude Code sends the whole session again on every turn, where a turn is one API call: a request that runs ten tools is ten turns. Here's my whole history:

$ baggage --all
baggage — 190 sessions, all projects, 63,964 turns

  before you typed anything              76k  tokens
    system prompt, every tool schema, every skill, CLAUDE.md.
    paid again on all 63,964 turns = 4.8B tokens, 18% of the bill,
    whether you called any of it or not.

Counting each session's turns from the same transcripts, the median session ran 213 turns. A quarter ran under 64, a quarter over 466, and the longest ran 2,943. So in a typical session, one line is sent 213 times: 2,769 tokens.

What each send costs. This is where the guesses go wrong, because of the cache. The first turn writes the line to Claude Code's one-hour cache at twice the input price. Every later turn reads it back at a twentieth of the input price on Opus 5.5 (Anthropic's rates). Unless the cache broke: an idle hour, a /compact, a model switch. Then the start of the session is written again at the write price. In my history, that happened on 1.8% of turns (1,137 of 63,453).

So for one line over a 213-turn session on Opus 5.5:

first write: 13 tokens at $8 per million = $0.0001
3.8 re-writes at the same price = $0.0004
208 cache reads at $0.20 per million = $0.0005
total: $0.0010. Uncached, all 213 sends at $4 per million: $0.011.

The same sum on three models, for one line and for a full 200-line file:

Opus 5.5: one line $0.0010 cached, $0.011 uncached. 200 lines: $0.21 cached, $2.22 uncached.
Sonnet 5.5: one line $0.0005 cached, $0.0055 uncached. 200 lines: $0.10 cached, $1.11 uncached.
Fable 5.1: one line $0.0019 cached, $0.028 uncached. 200 lines: $0.38 cached, $5.54 uncached.

Two things fall out of that. Caching cuts the price of a line by 11 to 14 times, so any figure that skips the cache is off by an order of magnitude. And on Opus 5.5, the five turns that write the line cost nearly as much as the 208 that read it, and a cache break re-writes the whole session, not just this file. If cost is the worry, keep the cache warm before you start cutting lines.

On a Pro or Max plan you see a limit, not dollars. In tokens, a 200-line file is about 554,000 tokens sent over a typical session. How heavily a cached token counts against the limit isn't published, so I won't guess.

One caveat on the ruler. bridle counts four characters a token, Anthropic's own rough estimate, but Anthropic also says Claude 4.7 and later produce about 30% more tokens for the same text. On current models, add about 30% to every figure here.

Does CLAUDE.md save tokens?

Only when it saves turns. A wasted turn re-sends at least the 76k floor from the block above, plus everything since. A line costs 2,769 tokens a session. So a line that prevents one wrong turn every 27 sessions has paid for itself in tokens. A line that never changes what Claude does never will.

How long real CLAUDE.md files are (350 repos)

Last month, for another project, I pulled 350 public instruction files from GitHub: 220 CLAUDE.md and 130 AGENTS.md, one root file per repo, no forks, every repo pushed this year. I picked them evenly across six file sizes, so they show the range, not the typical file on GitHub. Then I ran wc -l and bridle on every one. Median lines and tokens per line, by size:

under 800 bytes (41 files): 8 lines, 10.6 tokens a line
800 bytes to 1.5 KB (57): 26 lines, 10.2
1.5 to 3 KB (61): 49 lines, 11.6
3 to 6 KB (50): 83 lines, 12.7
6 to 12 KB (70): 150 lines, 12.8
12 KB and up (71): 312 lines, 14.4

Bigger files have denser lines, with tables and code blocks, but the typical line stays between 10 and 14 tokens. 73 of the 350 run past 200 lines and 11 past 500. The longest is 980 lines, about 8,700 tokens. At the prices above, that one costs about 69 cents a session on Opus 5.5 with caching, or $7.38 without. 11 of the 350 are past the 32 KiB that Codex reads by default.

My own 23 files have a median of 41 lines, and three run past 200. One of those, 311 lines and about 4,200 tokens, sits in a project where my sessions run a median 493 turns. That's 64 cents a session on Opus 5.5 with caching, $8.24 without, and under 5% of the 89k that project loads before I type anything.

In money, length barely matters. That leaves Anthropic's reason: a long file gets followed less. The research on that is mixed (I went through it in the AGENTS.md vs CLAUDE.md post), but every line still competes with the task for attention.

Cutting it without losing rules

Ask of each line: would Claude get something wrong without it? If not, delete it. If it would, check whether the line can live somewhere cheaper:

Rules for one part of the code go in .claude/rules/ with a paths: list at the top. Per the docs, they load when Claude reads a matching file, so they're carried only from that turn on, and only in sessions that touch those files.
Procedures become a skill. Its description loads every session; the body loads only when it's used.
@imports don't shrink anything. Imported files load at launch too. They tidy the file, not the bill.
Notes for humans go in an HTML comment. Claude Code strips block-level comments before Claude sees the file, so they cost nothing.
Keep what you keep repeating. The lines worth their rent are the corrections you've typed three times. Your chat history already has them.

What I didn't do is trim a file and measure the difference. Trimming today and running baggage tomorrow compares two days of work, not two files. Done properly, it's a week of sessions on the shorter file: the floor, the share of turns that re-write the cache, and whether the cut rules start turning up in chat again.

Check yours

$ wc -l CLAUDE.md
$ npx -y github:manpreet171/bridle agents CLAUDE.md   # or AGENTS.md
$ npm install -g github:manpreet171/baggage
$ baggage          # this project's floor and turns

bridle prints the file's size in tokens, plus what's missing from it. baggage reads the transcripts already on your machine and prints your floor, your sessions and your turns. Both are free and send nothing anywhere. Then the sum is yours: tokens per line, times turns per session, times your model's cache price.

Sources: both terminal blocks with output are real runs on my machine on 9 Oct 2026, the baggage one trimmed to its first lines. Turns per session and cache re-writes are counted from the same transcripts baggage reads, the same way it counts a turn. The 350 files are public repos pulled on 24 Sep 2026. Token counts are estimates at four characters a token. Prices, cache multipliers and the tokenizer note are from Anthropic's pricing page; CLAUDE.md loading, rules and limits from Claude Code's memory docs; line counts and the instruction budget from HumanLayer; the 32 KiB cap from Codex's AGENTS.md docs.

Where this fits: memory and context, layer 2 of the Agent Ops Stack.

Originally published at singhlabs.dev.

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

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

AGENTS.md is a plain Markdown file in your repo that tells AI coding agents how to work on it. CLAUDE.md is Claude Code's own version.

Two files, one job. 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.

Does AGENTS.md work with Claude Code?

Yes, from version 2.1.277, as long as no CLAUDE.md is in the way. The rules, 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.
Telemetry off? Update. Before 2.1.281, sessions with telemetry disabled, or on Bedrock, Vertex or an LLM gateway, skipped AGENTS.md without a word (issue #95690). 2.1.281 fixed it, per the changelog. The docs add one more: the first session after upgrading from 2.1.276 or earlier can skip it too.
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 (I priced what each line costs), 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 · 15 sessions (1 Aug – 9 Oct) · 727 of your messages · 44 corrections

You keep telling your AI:
   1.   3×  keep it simple   (3 sessions)

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

916 words of rules, and that line isn't in there. The correction I gave most often in this repo had never been written down, so every new session started without it and I typed it 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.

AGENTS.md vs SKILL.md

Different jobs. AGENTS.md holds facts the agent needs on every turn, and you pay for them on every turn. A skill is a folder with a SKILL.md in it: a procedure that loads only when the job comes up. Until then, only its name and description ride along.

Anthropic's skills docs draw the line: make a skill when a section of CLAUDE.md "has grown into a procedure rather than a fact." The deploy happens on push: a fact, so it goes in the file. The steps of a release: a skill.

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.

Sources: every terminal block is a real run in this website's repo on 5 Oct 2026, except toldya's: re-run on 9 Oct with 0.3.5 (0.3.3 stopped counting resumed sessions twice, 0.3.4 fixed how it groups rewordings, 0.3.5 skips "I don't get it"). Loading rules are from Anthropic's memory docs and the Claude Code changelog for 2.1.277 and 2.1.281; the telemetry bug is from issue #95690. Skills are from Anthropic's skills docs. Tool support is from agents.md. The studies are arXiv 2602.11988 and arXiv 2605.10039.

Where this fits: memory and context, layer 2 of the Agent Ops Stack.

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.

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.

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.