Agent Skills: Bun Dev

Bun Dev

Rule-first Bun guidance plus the native codex-dev bun command surface.

Use bun-dev for operating-model decisions, rule lookup, reference sync, and platform routing. Use bun-audit when the task is specifically a scan, safe-fix, or validation workflow.

Navigation

1. If changing package manager/runtime, open P1 rules first: pm-*, runtime-*, vercel-*.
2. If working in a monorepo, open: scripts-bun-run-parallel-sequential, scripts-bun-filter-and-workspaces.
3. If deploying to Vercel, open: vercel-bun-runtime-enable, vercel-bun-runtime-limitations.
4. For repo-wide enforcement, use: codex-dev bun audit, codex-dev bun fixes plan, codex-dev bun fixes apply, and codex-dev bun validate run.
5. For current vendor-backed references, use: codex-dev bun references status and codex-dev bun references plan.

Quick Start

Audit:

codex-dev --json bun audit --root .

Plan safe fixes:

codex-dev --json bun fixes plan --root .

Apply safe fixes:

codex-dev --json bun fixes apply --root .

Validate after remediation:

codex-dev --json bun validate run --root . --fail-on warn

Priority Table

| Priority | Category | Impact | Prefix | | --- | --- | --- | --- | | 1 | Package manager + lockfiles | Critical | pm- | | 1 | Runtime selection + one runtime where possible | Critical | runtime- | | 1 | Vercel Bun runtime | Critical | vercel- | | 2 | Scripts + monorepo orchestration | High | scripts- | | 2 | TypeScript + tooling | High | tsconfig- | | 3 | Testing | Medium | test- | | 3 | Bundling + build | Medium | build- | | 4 | Performance | Medium | perf- | | 5 | Migration + troubleshooting | Low/medium | migrate-, troubleshooting- |

Quick Reference

Package manager + lockfiles:

• pm-bun-add-remove-update
• pm-no-mixed-lockfiles
• pm-commit-bun-lockb
• pm-bun-install-ci-frozen-lockfile
• pm-package-manager-field
• pm-bunx-vs-npx

Runtime selection:

• runtime-bun-vs-node-choose
• runtime-bun-run-bun-flag
• runtime-ts-direct-execution
• runtime-watch-and-hot-reload
• runtime-env-files

Vercel Bun runtime:

• vercel-bun-install-detection
• vercel-bun-runtime-enable
• vercel-bun-runtime-limitations
• vercel-nextjs-bun-runtime-scripts
• vercel-bun-function-fetch-handler

Scripts + monorepos:

• scripts-bun-run-parallel-sequential
• scripts-bun-filter-and-workspaces
• scripts-no-npm-in-bun-repos

TypeScript:

• tsconfig-bun-recommended
• tsconfig-bun-types
• tsconfig-module-resolution-bundler

Testing + build:

• test-bun-test-runner
• test-bun-retry
• test-mocking-and-spying
• build-bun-build-bundler
• build-compile-executables
• build-bun-compile-browser

Performance:

• perf-prefer-bun-native-apis
• perf-avoid-node-fs-promises-hot-paths

Migration + troubleshooting:

• migrate-node-to-bun-checklist
• troubleshooting-esm-cjs-and-exports
• troubleshooting-types-bun

Native Commands

• codex-dev bun audit --root .: report Bun findings.
• codex-dev bun rules list: print rule ids.
• codex-dev bun rules show <rule-id>: print one rule.
• codex-dev bun fixes plan --root .: print safe fix candidates with hashes and diffs.
• codex-dev bun fixes apply --root .: apply safe rewrites and write rollback artifacts under external dev-skills state.
• codex-dev bun validate plan --root .: print validation commands.
• codex-dev bun validate run --root . --fail-on warn: audit then run validation commands.
• codex-dev bun benchmark --root .: time audit and fix planning.
• codex-dev bun references status: inspect reference hashes and integrity.
• codex-dev bun references plan: fetch vendor docs and preview changed reference files.
• codex-dev bun references sync: refresh tracked references and rebuild indexes.
• codex-dev bun doctor: inspect paths, version pin, and integrity.
• codex-dev tool import: import an external JSON report into a task capsule.

Platform State

• Config file: bun-platform.config.json
• External config: ${XDG_CONFIG_HOME:-~/.config}/dev-skills/bun-platform
• External state: ${XDG_STATE_HOME:-~/.local/state}/dev-skills/bun-platform
• External cache: ${XDG_CACHE_HOME:-~/.cache}/dev-skills/bun-platform
• Audit cache is read-only by default; opt in with --write-cache.
• Safe fixes write rollback artifacts under external state, never under the repo root.

Config keys:

• disabledRules
• severityOverrides
• adapters
• includePaths
• excludeDirs
• baseline
• maxFiles
• maxBytes
• validationCommands
• writeCache

Example template: assets/templates/bun-platform.config.example.json.

References

Start with references/index.md.

| Topic | Reference | Start with rules | | --- | --- | --- | | Bun latest release notes | references/ref-bun-release-notes-latest.md | scripts-bun-run-parallel-sequential, build-bun-compile-browser, test-bun-retry, test-bun-test-runner | | Bun capabilities | references/ref-bun-capabilities-latest.md | runtime-*, build-*, test-* | | Bun package-manager fallbacks | references/ref-bun-package-manager-fallbacks.md | pm-*, scripts-* | | Vercel Bun runtime | references/ref-vercel-bun-runtime.md | vercel-bun-runtime-enable, vercel-bun-runtime-limitations |

Refresh reference snapshots:

codex-dev --json bun references plan
codex-dev --json bun references sync

Skill integrity check:

codex-dev --json bun doctor
codex-dev --json bun references status