# Contributor handoff — denoland/deno

> Canonical page: https://codevetter.com/unpack/deno/agent-handoff

# Contributor handoff — denoland/deno

Scanned commit 461f32ec6174d88b7e43654a054d46d67ae2fdab (2026-09-21). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

Read `CLAUDE.md`, `tools/x.ts`, `cli/lib.rs`, and `cli/factory.rs` first — those four give you the command surface, the dispatch table, and the service graph. Use `./x` rather than raw cargo: `./x check` for fast feedback, `./x build` for a binary, `./x test-spec <filter>` for integration tests (a filter is mandatory and the runner will panic without one under Claude Code), and `./x verify` (fmt + lint-js) before committing. The repo's conventions are enforced mechanically: dprint formatting, a copyright-header check, generated-workflow freshness, and a clippy `disallowed_methods` list that is why you see `#[allow(clippy::disallowed_methods, reason = "…")]` sprinkled through startup code. Keep diffs minimal and avoid drive-by changes — the CLAUDE.md git workflow says so explicitly, and PRs are squash-merged so never force-push.
- Read first, in order: `CLAUDE.md` (build/test/PR conventions), `tools/x.ts` (the command registry with long help strings), `cli/lib.rs` (`main()` at :863 and `run_subcommand` at :124), `cli/factory.rs` (`CliFactoryServices` at :302), and `runtime/worker.rs` (`common_extensions` at :1199). — [CLAUDE.md](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/CLAUDE.md) [tools/x.ts#L102-395](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/x.ts#L102-L395) [cli/lib.rs#L124-556](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/lib.rs#L124-L556) [cli/factory.rs#L302-345](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/factory.rs#L302-L345) [runtime/worker.rs#L1199-1262](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/runtime/worker.rs#L1199-L1262)
- Never run the full spec suite: `tests/specs/mod.rs::main` panics when `CLAUDE_CODE_ENTRYPOINT` is set without a filter — always use `./x test-spec <filter>` or `./x test-spec --list`. — [tests/specs/mod.rs#L266-279](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tests/specs/mod.rs#L266-L279) [tools/x.ts#L235-270](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/x.ts#L235-L270)
- Pre-commit is `./x fmt` then `./x lint-js` (bundled as `./x verify`) for JS/TS-only changes; if Rust changed, also run `./x lint` (includes clippy) and `./x check`. — [tools/x.ts#L370-395](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/x.ts#L370-L395) [CLAUDE.md](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/CLAUDE.md)
- Unit tests must go through cargo, not the built binary: `./x test-unit <filter>` runs `cargo test -p unit_tests --test unit -- <filter>`; `CLAUDE.md` explicitly warns against `./target/debug/deno test` for `tests/unit/`. — [tools/x.ts#L160-190](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/x.ts#L160-L190) [tests/unit/Cargo.toml](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tests/unit/Cargo.toml) [CLAUDE.md](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/CLAUDE.md)
- Formatting is dprint-driven with a repo config; do not hand-format. `tools/format.js` runs `npm:dprint@0.47.2 fmt --config .dprint.json`, and `--check` mode is available for verification. — [tools/format.js#L1-22](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/format.js#L1-L22) [.dprint.json](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/.dprint.json)
- Every source file needs the copyright header `// Copyright 2018-2026 the Deno authors. MIT license.` — `checkCopyright()` runs as part of `tools/lint.js` whenever both JS and Rust linting are enabled. — [tools/lint.js#L18-44](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/lint.js#L18-L44) [tools/copyright_checker.js](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/copyright_checker.js) [cli/lib.rs#L1](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/lib.rs#L1)
- Clippy enforces a disallowed-methods/types list per crate via `clippy.toml` files (present in `cli/`, `runtime/`, `ext/*`, `libs/*`); bypassing one requires an `#[allow(clippy::disallowed_methods, reason = "...")]` with a written reason, as seen around `std::env::current_dir` and `std::env::var_os` in startup. — [cli/clippy.toml](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/clippy.toml) [cli/lib.rs#L919-923](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/lib.rs#L919-L923) [cli/lib.rs#L846-852](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/lib.rs#L846-L852) [tools/lint.js#L31](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/lint.js#L31)
- Safe edit boundary for new native APIs: add ops inside the relevant `ext/<name>` crate, keep the `common_extensions` position stable, and remember the snapshot files (`runtime/snapshot.rs`, `runtime/snapshot_info.rs`, `runtime/web_worker.rs`) must stay in sync. — [runtime/worker.rs#L1206-1212](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/runtime/worker.rs#L1206-L1212) [runtime/snapshot.rs#L59-100](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/runtime/snapshot.rs#L59-L100)
- Anything in `.github/workflows/*.generated.yml` is build output — edit the `.ts` sibling and regenerate, or `ensureWorkflowYmlsUpToDate()` in `tools/lint.js` will fail CI. — [.github/workflows/ci.ts#L1-40](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/.github/workflows/ci.ts#L1-L40) [tools/lint.js#L38](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/lint.js#L38)
- Trap: adding a thread earlier in `main()` breaks the safety argument for the startup `env::set_var` calls; the node-shim setup, tunnel init, and `DENO_CONNECTED` assignment all carry comments stating they must run before any thread spawns. — [cli/lib.rs#L1023-1062](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/lib.rs#L1023-L1062) [cli/node_compat_shim.rs#L173-180](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/node_compat_shim.rs#L173-L180)
- Trap: large futures overflow the stack on Windows debug builds. `spawn_subcommand` uses `boxed_local()`, several subcommands add explicit `.boxed_local()`, and `Deferred::get_or_try_init_async` documents boxing for the same reason — preserve these when refactoring. — [cli/lib.rs#L108-122](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/lib.rs#L108-L122) [cli/factory.rs#L280-290](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/factory.rs#L280-L290) [cli/tools/run/mod.rs#L179-181](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/tools/run/mod.rs#L179-L181)
- Git workflow per `CLAUDE.md`: branch off `main`, never force-push to a PR (commits are squashed on merge so incremental commits help reviewers), and keep changes scoped — no drive-by fixes in an unrelated PR. — [CLAUDE.md](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/CLAUDE.md)
- PR titles must match `type(scope): description` with types `feat|fix|perf|refactor|chore|docs|test|revert|BREAKING`; `tools/verify_pr_title.js` and the `review-pr` skill both gate on it. — [.claude/skills/review-pr/SKILL.md#L33-44](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/.claude/skills/review-pr/SKILL.md#L33-L44) [tools/verify_pr_title.js](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/verify_pr_title.js)
- Debugging aids that already exist: `DENO_STARTUP_PHASES=1` for boot-phase timings, `DENO_LOG=debug` for module-level logging, and `DENO_AUDIT_PERMISSIONS=<file|otel>` to record every permission access. — [cli/lib.rs#L841-860](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/lib.rs#L841-L860) [cli/lib.rs#L1100-1130](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/cli/lib.rs#L1100-L1130) [CLAUDE.md](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/CLAUDE.md)
- When touching Node compatibility, use the repo's own workflow: `./x test-compat <filter>` runs `cargo test --test node_compat`, and `.claude/skills/node-compat/SKILL.md` documents the fix/skip/ignore decision procedure. — [tools/x.ts#L215-235](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tools/x.ts#L215-L235) [.claude/skills/node-compat/SKILL.md](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/.claude/skills/node-compat/SKILL.md) [tests/node_compat/config.jsonc](https://github.com/denoland/deno/blob/461f32ec6174d88b7e43654a054d46d67ae2fdab/tests/node_compat/config.jsonc)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)