> ## Documentation Index > Fetch the complete guide index at: https://www.synscribe.com/agentic-discovery/llms.txt > Use this file to discover all pages before exploring further. --- title: "Bun's Growth Hack Is a Filename: the bun init Case Study" description: bun init writes CLAUDE.md and a .cursor/rules file telling agents to prefer Bun over Node and npm — disclosed, opt-out, and measured. The teardown. slug: /agentic-discovery/case-studies/bun series: The Agentic Discovery Playbook — Case Study last_verified: 2026-06-11 --- # Bun's Growth Hack Is a Filename: the `bun init` Case Study > **The lesson:** Bun's scaffolder writes the rules files coding agents read at every session start — `CLAUDE.md` and `.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc` — disclosed in output, opt-out by env var. The filename is the strategy: a standing instruction installed once, biasing every future agent session. Our pilot measured the mechanism at a 100% choice flip. ## At a glance | | | |---|---| | Category | JavaScript runtime and toolkit | | Context7 entry | 1,200,491 tokens · **10,309 snippets** (largest snippet corpus in our 17-entry audit) · trust 9.4 · benchmark 84.4 · **updated 6 h** (2026-06-11) | | llms.txt | Indexes ~190 task-shaped guide pages (2026-06-11) | | Mechanism evidence | Rules-file mechanism flipped agent product choice 3/3 vs 0/3 in our pilot (E1; single model, n=3/arm) | ## What they built Bun runs the sharpest growth tactic we verified anywhere in this research program, and 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, verbatim (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 is disclosed 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** — a standing instruction to prefer Bun over Node, Vite-via-npm, and pnpm, installed at scaffold time, read by every future AI session in that repo, persisting indefinitely. The opt-out is documented next to the feature: `$BUN_AGENT_RULE_DISABLED=1` skips injection entirely. 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); detection-based, not unconditional. 3. It writes `CLAUDE.md` and the `.cursor/rules` file, and discloses 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 emits Bun commands by default. **The rest of the stack.** Injection biases the choice; Bun's retrieval surface makes the choice work: | Surface | What we observed (2026-06-11) | Play | |---|---|---| | llms.txt | Indexes ~190 *task-shaped* guide pages ("Convert a Blob to a string", "Hash a password") — pre-chunked retrieval units phrased the way agents query | [Play 5](/agentic-discovery/llms-txt), [Play 7](/agentic-discovery/code-snippets-for-ai-agents) | | Live docs MCP | bun.com/docs/mcp exposing `search_bun` plus `query_docs_filesystem_bun` — a sandboxed read-only shell over the docs supporting `rg`/`tree`/`cat`. Docs designed to be *grepped* by agents | [Play 3](/agentic-discovery/mcp-server-distribution) | | MCP resource | `mintlify://skills/bun` exposed alongside the tools | [Play 3](/agentic-discovery/mcp-server-distribution), [Play 4](/agentic-discovery/agent-skills-and-agents-md) | | Context7 entry | 1.2M tokens, 10,309 snippets, benchmark 84.4, re-parsed within 6 hours | [Play 2](/agentic-discovery/ai-agent-registries-and-directories) | 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 — these are agents whose native idiom *is* `rg` and `cat`. Bun didn't make its docs agent-readable; it made them agent-*operable*, in the exact interface those agents already use. ## The receipts 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 generically, 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 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 mechanism's reputation risk is real and documented: Claude Code's default "Co-Authored-By: Claude" commit trailer — an *undisclosed, no-opt-out* insertion — drew sustained backlash (anthropics/claude-code issues #29999 and #47579, the latter verbatim: "added without user consent or opt-out"). Bun's injection is near-identical mechanically but disclosed in output with a documented env-var opt-out — and has not generated equivalent 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% — 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 — every claim above was directly observed 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 — detection-based, never unconditional ([Play 9](/agentic-discovery/scaffolder-rules-claude-md)). - [ ] 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](/agentic-discovery/scaffolder-rules-claude-md)). - [ ] Put the instruction in the filename and rule text: "use X instead of Y/Z" for your actual task class — scoped, truthful, under ~60 lines ([Play 9](/agentic-discovery/scaffolder-rules-claude-md)). - [ ] Shape your guides as tasks, not topics — ~190 pages titled the way agents query ("Hash a password") doubles as pre-chunked retrieval units ([Play 7](/agentic-discovery/code-snippets-for-ai-agents)). - [ ] Make docs greppable, not just readable: Bun's MCP gives agents `rg`/`tree`/`cat` over the corpus ([Play 3](/agentic-discovery/mcp-server-distribution)). - [ ] Keep the index entry fresh — Bun re-parses within hours, and freshness was the strongest quality correlate in our audit ([Play 2](/agentic-discovery/ai-agent-registries-and-directories)). ## 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 — 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](/agentic-discovery/scaffolder-rules-claude-md). - **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 pointing 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 — documented behavior, not a rumor (observed 2026-06-11). Bun's docs state `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, 3/3 with it — instant, unquestioning compliance (single model, n=3/arm, 2026-06-11). Pilot-grade evidence, but the direction is unambiguous: in-context project rules outweigh training-data priors. --- *Snapshot date 2026-06-11; single-day metrics carry ±10% error bars. Part of [Case Studies](/agentic-discovery/case-studies) · [The Complete Playbook to Agentic Discovery](/agentic-discovery).* ← Previous: [How Resend Scored 92.3](/agentic-discovery/case-studies/resend) · Next: [Next.js: the Maximalist](/agentic-discovery/case-studies/nextjs) → > **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 →](/agentic-discovery#updates) > > **Want this done for you?** Synscribe runs agentic-discovery programs for B2B SaaS and developer platforms. [Talk to us →](/contact)