Bun's Growth Hack Is a Filename: the bun init Case Study

The lesson: Bun's scaffolder writes the rules files that coding agents read at every session start: CLAUDE.md and .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc. The writes are disclosed in the output, and you can opt out with an env var. The filename is the strategy. It is a standing instruction installed once, and it shapes every future agent session. Our pilot measured the mechanism at a 100% choice flip.

At a glance

What they built

Bun runs the sharpest growth tactic we verified anywhere in this research program. It isn't a docs page. It's two files its scaffolder writes into your project.

The injection. When you run bun init, the CLI detects the agent environment and acts on it. Bun's docs say it plainly (bun.com/docs/runtime/templating/init.md, observed 2026-06-11): it writes "a CLAUDE.md file when Claude CLI is detected... a .cursor/rules/*.mdc file to guide Cursor AI to use Bun instead of Node.js and npm when Cursor is detected." The write shows up in the printed output:

+ .cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc -> CLAUDE.md bun init output (bun.com/docs/runtime/templating/init.md)

Read that filename again: use-bun-instead-of-node-vite-npm-pnpm.mdc. The filename is the strategy. It is a standing instruction to prefer Bun over Node, Vite-via-npm, and pnpm. It gets installed at scaffold time, every future AI session in that repo reads it, and it never goes away. The opt-out sits right next to the feature: $BUN_AGENT_RULE_DISABLED=1 skips the writes entirely.

Here is the full sequence, as documented:

1. A developer (or an agent) runs bun init.
2. The CLI detects the environment (Claude CLI present, Cursor present). It only acts when it finds them.
3. It writes CLAUDE.md and the .cursor/rules file, and lists both in the printed file list.
4. $BUN_AGENT_RULE_DISABLED=1 skips the writes entirely.
5. Every future AI session in that repo reads the rules at session start and runs Bun commands by default.

The rest of the stack. The injection tilts the choice. Bun's retrieval surface makes the choice work:

The greppable-docs MCP deserves a second look. Terminal-native agents (Claude Code, Opencode, Codex) account for ~73% of all Context7 doc retrieval in our data. Their native idiom is rg and cat. Bun didn't just make its docs agent-readable. It made them agent-operable, in the exact interface those agents already use.

All figures observed 2026-06-11; single-day snapshot, ±10% error bars. Experiments are pilot-grade (single model, Claude Haiku 4.5, n=3 per arm, tools disabled).

The mechanism, measured (E1). We gave six identical agent sessions a product-selection task; control projects had no rules file, treatment projects contained an AGENTS.md mandating an obscure product.

Control   (no rules file):   training-data default ███████████ 3/3   mandated product ░ 0/3
Treatment (AGENTS.md rule):  training-data default ░ 0/3             mandated product ███████████ 3/3

Compliance was instant. One trial's rationale began, verbatim: "explicitly mandated in this project's AGENTS.md conventions document, making it the only appropriate choice regardless of alternatives." E1 tested the rules-file mechanism in general, not Bun's payload specifically. But it is exactly the mechanism bun init installs, and the measured flip was total.

The index entry. 10,309 snippets is the largest snippet corpus among our 17 audited Context7 entries. At a 6-hour re-parse cadence, it ties for the freshest non-shadcn entry we logged. Its benchmark of 84.4 sits within half a point of Next.js's repo entry (84.9) and well above the audit median. Freshness matters. Across the same 17 entries, hours-since-update was the strongest benchmark correlate we found (ρ=−0.54; fresh-5 averaged 83.6 vs stale-5 at 72.3; correlational, n=17).

The ethics precedent, both directions. The reputation risk here is real and documented. Claude Code's default "Co-Authored-By: Claude" commit trailer was an undisclosed, no-opt-out insertion, and it drew sustained backlash (anthropics/claude-code issues #29999 and #47579, the latter verbatim: "added without user consent or opt-out"). Bun's injection is nearly the same mechanically, but it is disclosed in the output and comes with a documented env-var opt-out. It has not drawn the same backlash. Disclosure and opt-out are the difference between a growth tactic and a GitHub incident.

The docs banner. Every Bun .md docs page carries the Mintlify-generated agent banner ("Fetch the complete documentation index at .../llms.txt... before exploring further"). Five of the products we audited get this agent-grade baseline by platform default.

The audience for greppable docs. Tool mix across Context7 queries: Claude Code 43.4%, Opencode 15.3%, Codex 14.0%. That is terminal-native agents at ~73% combined, plus ~2.6% raw HTTP clients (custom scripts fetching docs programmatically). Bun's rg/tree/cat interface targets exactly how this population works.

Nothing in Bun's dossier carries an UNVERIFIED flag. We observed every claim above directly, at the cited URLs, on 2026-06-11.

What to copy

• If you have a CLI or create-* scaffolder, write agent rules files at init. Make it detection-based, never unconditional (Play 9).
• Copy both halves of Bun's ethics: disclose every written file in the printed output, and ship a documented opt-out env var on day one (Play 9).
• Put the instruction in the filename and rule text. Use "use X instead of Y/Z" for your actual task class. Keep it scoped, truthful, and under ~60 lines (Play 9).
• Shape your guides as tasks, not topics. ~190 pages titled the way agents query ("Hash a password") double as pre-chunked retrieval units (Play 7).
• Make docs greppable, not just readable: Bun's MCP gives agents rg/tree/cat over the corpus (Play 3).
• Keep the index entry fresh. Bun re-parses within hours, and freshness was the strongest quality correlate in our audit (Play 2).

What NOT to over-copy

• The flip number is pilot-grade. E1 is n=3 per arm on a single model family with tools disabled. It is directional, not a population estimate. We publish it with that label. Quote it the same way.
• E1 measured the mechanism, not Bun. We did not A/B bun init's own payload. We measured what an injected rules file does to agent choice. The inference to Bun's tactic is strong but indirect.
• You need a scaffolder people already run. bun init works because developers (and agents) invoke it constantly. No CLI means no injection point. Start with the copy-paste AGENTS.md block and retrofit codemod variants in Play 9.
• Don't ship injection without the surface behind it. Bun backs the bias with a 10,309-snippet, 6-hour-fresh docs corpus. An injected rules file that points at stale or thin docs combines total compliance with confident wrongness.
• Point-in-time snapshot. All metrics are 2026-06-11 values with ±10% error bars. Freshness and benchmark scores are recomputed continuously.

FAQ

Does bun init really write AI rules files? Yes. It is documented behavior, not a rumor (observed 2026-06-11). Bun's docs state that bun init writes a CLAUDE.md when Claude CLI is detected and a .cursor/rules/*.mdc file when Cursor is detected, discloses both in the printed output, and supports $BUN_AGENT_RULE_DISABLED=1 to skip injection.

Is it ethical for a CLI to write CLAUDE.md and Cursor rules? Bun's version is the defensible pattern: disclosed in output, documented opt-out, truthful scoped content. The counter-precedent is Claude Code's undisclosed Co-Authored-By commit trailer, which produced sustained user backlash (issues #29999, #47579). Same mechanism, opposite community outcomes. Disclosure and opt-out are the variable.

Does a rules file actually change what agents pick? In our pilot, completely. 0/3 chose the mandated product without the file, and 3/3 chose it with the file. That is instant, unquestioning compliance (single model, n=3/arm, 2026-06-11). The evidence is pilot-grade, but the direction is clear: in-context project rules outweigh training-data priors.

Snapshot date 2026-06-11; single-day metrics carry ±10% error bars. Part of Case Studies · The Complete Playbook to Agentic Discovery.

Stay ahead of the agents. We re-test this playbook quarterly and publish what changed: new data, busted myths, ranking shifts. Get the update digest →

Want this done for you? Synscribe runs agentic-discovery programs for B2B SaaS and developer platforms. Talk to us →