how to contribute tooling

Tooling

This page catalogs the toolchain and the scripts behind the common commands. It complements Patterns and conventions (code style rules) and the command reference (../reference/index.md).

Lint and format

• Biome (@biomejs/biome 2.3.5) formats and lints. Config is biome.json. npm run check starts with biome check --write --error-on-warnings ..
• The TypeScript native-preview compiler tsgo runs type checks via tsgo --noEmit inside npm run check. Root devDependencies pin @typescript/native-preview 7.0.0-dev; individual packages may pin different TypeScript versions for their own builds.

Git hooks

Husky installs git hooks (the prepare script runs husky). These run on commit and push, so the pre-commit and pre-push checks gate every commit. Do not bypass hooks with git commit --no-verify.

React Doctor

React Doctor audits the web code against the waivers in doctor.config.jsonc. Run it with npx -y react-doctor; for change-scoped scans use npx -y react-doctor --scope changed --project web/app,web/design as the audit plans in plans/README.md prescribe.

Web tooling

• web/ is a pnpm workspace defined by web/pnpm-workspace.yaml. Its packages are app, design, protocol, and server.
• The web dev server is Vite on port 3000, started with pnpm --dir web --filter @prime-agent/web dev.
• web/pnpm-workspace.yaml keeps nested @earendil-works/* dependencies on the in-tree npm packages with link: overrides (for example "@earendil-works/pi-coding-agent": "link:../packages/coding-agent"), not file:. Do not add packages/{ai,agent,tui,coding-agent} to the packages: list there.
• tsx runs TypeScript directly for tests and scripts, for example npx tsx ../../node_modules/vitest/dist/cli.js --run test/specific.test.ts.

Dependency age

.npmrc sets min-release-age=7: package managers will not resolve versions published less than 7 days ago. Enforced only with npm >= 11.10; older npm silently ignores it. web/pnpm-workspace.yaml mirrors this with minimumReleaseAge: 10080 (7 days in minutes). Override for an urgent security patch with npm install --min-release-age=0 <pkg>.

Scripts reference

The repo-root scripts/ directory holds the release, packaging, check, and profiling tooling:

Script	Purpose
scripts/release.mjs	Runs the release (npm run release:patch / release:minor / release:major)
scripts/pack-prime-agent-release.mjs	npm run release:pack; packs a prime-agent release
scripts/build-web-release.mjs	npm run build:web:release; bundles the built web server and client into packages/coding-agent/dist/web/
scripts/check-source-installer.mjs	npm run check:installer (static) and npm run test:source-installer (smoke)
scripts/check-browser-smoke.mjs	npm run check:browser-smoke
scripts/check-web-release.mjs	npm run check:web:release
scripts/sync-versions.js	Synchronizes the version number across all packages
scripts/profile-coding-agent-node.mjs	Profiling for npm run profile:tui and npm run profile:rpc
scripts/setup-kernel-venv.sh	Creates the Python kernel venv
scripts/build-binaries.sh	Builds binary artifacts

Build order

• npm run build builds packages in dependency order: packages/tui, then packages/ai, then packages/agent, then packages/coding-agent. Do not run this at the repo root as a validation step; use npm run check instead.
• npm run build:web:release runs pnpm --dir web --filter @prime-agent/web build, then scripts/build-web-release.mjs to bundle the production web runtime into packages/coding-agent/dist/web/.
• CI runs npm run build then npm run check in the build-check job; see Testing.

Related pages

• Patterns and conventions, code style and repo rules
• Testing, running tests and what CI runs
• Development workflow, the check-commit-release cycle
• Reference, configuration and dependencies