@coryrylan/tools

Shared tooling configs - ESLint, Prettier, Stylelint, Vale, Vite, and Vitest - plus custom ESLint rules for keeping codebases maintainable when coding agents are the primary contributors.

Philosophy

When an agent is the one writing most of a diff, prose instructions living in an AGENTS.md file are advisory at best. They have to be loaded into context, correctly interpreted, and remembered turns later, and none of that is guaranteed on any given run. Prose decays: it drifts out of context, gets skimmed instead of read, or is outweighed by whatever the agent is focused on in the moment. A lint rule has none of these failure modes: it runs on every diff, every time, and fails the build instead of hoping to be noticed. Every rule and every shared config in this package exists to replace a paragraph an agent would otherwise have to read (and might ignore, forget, or misapply) with a deterministic check or preset that gates the diff instead.

Surfaces

Entry	What it ships
@coryrylan/tools/eslint	Flat configs plus the custom tools/* rule plugin.
@coryrylan/tools/prettier	The shared Prettier config.
@coryrylan/tools/stylelint	Shared Stylelint config (standard + logical properties + design-token checks).
@coryrylan/tools/vite	createNodeLibraryBuildConfig / createBrowserLibraryBuildConfig factories.
@coryrylan/tools/vite/plugins/write-if-changed	Vite plugin that skips writing chunks whose content didn't change.
@coryrylan/tools/vite/plugins/dts	Vite plugin that runs the consumer's TypeScript compiler for declaration output.
@coryrylan/tools/vitest	nodeTestConfig preset for node-environment unit tests.
@coryrylan/tools/vitest/browser	browserTestConfig preset for browser-mode (Playwright Chromium) tests.
dist/vale/	Vale starter kit: ini template plus shared accept/reject vocabulary.
@coryrylan/tools/pi/greeting	Pi extension - speaks a greeting via macOS say on session start.
@coryrylan/tools/pi/audio-summary	Pi extension - speaks a short summary of each agent turn.
@coryrylan/tools/pi/hooks	Pi extension - Claude-Code-style lifecycle hooks from .agents/hooks.json.

ESLint

pnpm add -D eslint @coryrylan/tools typescript typescript-eslint

The remaining peers (@eslint/js, @eslint/json, eslint-plugin-jsdoc) install automatically as regular peer dependencies under pnpm 10 or npm. Yarn users should add them to devDependencies explicitly.

// eslint.config.js
import { typescriptConfig, jsonConfig } from '@coryrylan/tools/eslint';

export default [...typescriptConfig, ...jsonConfig];

A default export is also available if you'd rather reach into the plugin and config map directly: import agentLintRules from '@coryrylan/tools/eslint' exposes { plugin, configs }, where configs is keyed by typescript, tests, browser, html, and json.

Configs

Config	What it enables	Requirements
typescriptConfig	On all JS/TS files: size/complexity budgets (complexity 8, max-depth 3, max-params 3, max-lines 500, max-statements 15, max-lines-per-function 50, max-nested-callbacks 3) plus eqeqeq, prefer-const, no-shadow, no-warning-comments, no-param-reassign, and friends, and 5 syntax-only tools/* rules. On TS files: type-aware strictTypeChecked, plus @typescript-eslint/no-floating-promises, only-throw-error, consistent-type-imports, switch-exhaustiveness-check, explicit-member-accessibility (no-public), a #private-over-private selector, no-explicit-any, no-unnecessary-boolean-literal-compare, jsdoc checks (informative-docs, no-types, valid-types, check-tag-names), and the type-aware tools/no-deep-class-inheritance rule. The default starting point for a new agent-maintained project - relax specific rules per-project rather than swapping this config out.	typescript-eslint, eslint-plugin-jsdoc, typescript >=5.5.0 <6.1.0, parserOptions.projectService
testsConfig	Relaxes size/complexity budgets (max-lines, max-lines-per-function, max-statements, max-nested-callbacks, unused-expression checks) for *.test.* / *.spec.* files.	combine with another config
browserConfig	globalThis-over-window/document/location restrictions, plus 3 cleanup rules (require-listener-cleanup, require-observer-cleanup, require-timer-cleanup).	none extra
htmlConfig	@html-eslint recommended structural rules for *.html files (duplicate ids/attrs, obsolete tags, lang/alt requirements, baseline feature checks), with pure-formatting rules off in favor of Prettier and frontmatter-aware parsing for static-site templates.	@html-eslint/eslint-plugin, @html-eslint/parser
jsonConfig	@eslint/json structural rules for *.json (JSONC variant for tsconfig*.json), plus no-unpinned-dependency-ranges scoped to package.json.	@eslint/json

Rules

Rule	What it catches	Enabled by
tools/no-dead-code	Disallow commented-out source code left behind in comments.	typescript
tools/no-deep-class-inheritance	Disallow class inheritance chains deeper than a configured maximum.	typescript
tools/no-single-consumer-abstraction	Disallow exported abstractions (base classes) with fewer than two implementation consumers.	typescript
tools/no-unjustified-disable	Require every eslint-disable* directive to carry a reason (and, by default, an explicit rule list).	typescript
tools/no-reexport-barrels	Flag files that re-export from more than a configured number of modules.	typescript
tools/consistent-error-messages	Require thrown/constructed Errors to carry a non-empty, informative message.	typescript
tools/require-listener-cleanup	Require a matching removeEventListener for every addEventListener added in a setup lifecycle method; forbid addEventListener in the constructor.	browser
tools/require-observer-cleanup	Flag ResizeObserver/MutationObserver/IntersectionObserver/PerformanceObserver instances created without storing a reference.	browser
tools/require-timer-cleanup	Flag setInterval handles that are never stored or never cleared.	browser
tools/no-unpinned-dependency-ranges	Require package.json dependency version specifiers appropriate to the package's publish status and dependency kind.	json

Prettier

pnpm add -D @coryrylan/tools prettier

Reference the config straight from package.json:

{ "prettier": "@coryrylan/tools/prettier" }

Or import and spread it in a prettier.config.js to override options. Embedded template literals stay hand-formatted (embeddedLanguageFormatting: 'off'). See src/prettier/docs.

Stylelint

pnpm add -D @coryrylan/tools stylelint stylelint-config-standard

// stylelint.config.js
export { default } from '@coryrylan/tools/stylelint';

Layers stylelint-config-standard with logical-property enforcement (no physical margin-*/padding-*) and design-token checks (no hardcoded pixel values in spacing properties). See src/stylelint/docs.

Vale

Install the Vale binary (mise use vale, or brew), then point a .vale.ini at the styles this package ships:

StylesPath = node_modules/@coryrylan/tools/dist/vale/styles
Vocab = Tools
Packages = Google, write-good

Run vale sync once to download the style packages. The full template with per-filetype sections lives at src/vale/vale.ini. See src/vale/docs.

Vite

pnpm add -D @coryrylan/tools vite

// vite.config.ts
import { defineConfig, mergeConfig } from 'vite';
import { createNodeLibraryBuildConfig } from '@coryrylan/tools/vite';

export default defineConfig(mergeConfig(createNodeLibraryBuildConfig({ entry: { index: 'src/index.ts' } }), {}));

ESM-only, every bare specifier externalized, preserveModules for deep imports, no minification. The write-if-changed and dts plugins ship as deep imports under @coryrylan/tools/vite/plugins/. See src/vite/docs.

Vitest

pnpm add -D @coryrylan/tools vitest

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { nodeTestConfig } from '@coryrylan/tools/vitest';

export default defineConfig(nodeTestConfig);

@coryrylan/tools/vitest/browser exports browserTestConfig for real-Chromium browser-mode tests (requires the optional @vitest/browser-playwright, @vitest/coverage-istanbul, and playwright peers) with istanbul coverage gated at 90% across lines, branches, functions, and statements. See src/vitest/docs.

Pi extensions

pi install npm:@coryrylan/tools

Three pi coding-agent extensions, shipped as a pi package (pi manifest key in package.json, pi-package keyword): greeting, audio-summary, and hooks. Pi provides @earendil-works/pi-ai/@earendil-works/pi-coding-agent/typebox at runtime, so there is nothing extra to install. See src/pi/docs.

Peer dependencies

Every peer beyond eslint is scoped to the surface that needs it; the non-ESLint peers are marked optional, so install them with the surface you use.

• typescript must satisfy >=5.5.0 <6.1.0 for type-aware linting (typescriptConfig) - this is the range typescript-eslint supports; newer typescript majors are not yet compatible with type-aware rules here. Note that a bare pnpm add -D typescript resolves to 7.x (the native compiler, which no longer ships the JS compiler API typescript-eslint needs), so install an explicit typescript@6 until typescript-eslint supports 7.
• typescript-eslint >=8.40.0 and eslint-plugin-jsdoc >=60.0.0 are only needed if you use typescriptConfig.
• @eslint/json >=0.13.0 is only needed if you use jsonConfig.
• @html-eslint/eslint-plugin >=0.61.0 and @html-eslint/parser >=0.61.0 are only needed if you use htmlConfig.
• prettier >=3 for the Prettier config; stylelint >=17 and stylelint-config-standard >=40 for the Stylelint config.
• vite >=8 for the Vite factories and plugins; vitest >=4 for the test presets, plus @vitest/browser-playwright >=4, @vitest/coverage-istanbul >=4, and playwright >=1.50 for browserTestConfig.
• @earendil-works/pi-ai, @earendil-works/pi-coding-agent, and typebox for the pi extensions - the pi CLI provides all three at runtime, so they're optional peers with no version floor.

License

MIT - see LICENSE. Copyright (c) 2026 Cory Rylan.