Before you make a large change, open an issue. This page gives the development setup and project conventions. For the full guide, see CONTRIBUTING.md in the source repository.
Propose before you build
CC Safety Net has a focused scope: preventing coding agents from making accidental mistakes that cause data loss. It is not a general security-hardening or attack-prevention tool. Open an issue to discuss new detection rules, command categories, architectural changes, or configuration options before implementing them. Typo fixes and small bug fixes with an obvious solution can go straight to a pull request.
Set up the development environment
- Bun 1.3.14 — the required build and test runtime, and the only supported package manager (install guide). It is pinned as
packageManager in package.json.
- Node.js 18 or newer — the supported runtime for the built artifacts. Bun is not needed to run the published CLI or plugins.
- Claude Code or OpenCode — only if you want to load and exercise the plugin locally. Neither is needed to build the project or run the test suite.
bun run check is the single gate. It runs, in order: Biome lint and format, TypeScript typecheck, knip dead-code detection, jscpd duplicate detection, the test suite with coverage, and a coverage-threshold check. Run it once when you finish your changes rather than running the sub-commands separately. Make sure it passes with no errors before opening a pull request.
Individual commands are available while iterating:
Test a local plugin
Build, then load the local plugin so you can test real blocks:
- Claude Code: disable any installed safety-net plugin, exit Claude Code, then run
claude --plugin-dir . from the repo root.
- OpenCode: point the
plugin[] array in ~/.config/opencode/opencode.json at the built file://.../cc-safety-net/dist/index.js, remove the npm cc-safety-net entry to avoid conflicts, and restart OpenCode. Run /status and confirm the plugin name appears as dist.
Confirm a known block with the harmless exclusion-only pathspec: git checkout -- ':(exclude,top)**' must be blocked. If protection is inactive, this pathspec selects no files.
Follow the code conventions
Style guide
- Keep code in one function unless it is genuinely composable or reusable.
- Avoid
try/catch, the any type, and else branches — prefer early returns.
- Prefer functional array methods (
flatMap, filter, map) over for loops, and use type guards on filter so inference survives downstream.
- Prefer
const over let; use ternaries or early returns instead of reassignment.
- Inline values used only once instead of naming them, and avoid unnecessary destructuring.
Scope discipline
Over-engineering is this project’s dominant failure mode. Implement the smallest change that satisfies the request, and name the concrete failure that any addition beyond it prevents. Every check must be falsifiable in practice. Do not build schemas, validators, registries, or harnesses ahead of their first real entry, and prefer a documented process over code that enforces the process.
Knip
Never add entries to ignoreIssues in knip.ts. When knip flags an unused export, fix the root cause: delete or unexport genuinely dead code, tag test-only exports with a /** @internal */ JSDoc comment (knip runs in --production mode, so test files are excluded), and drop unused names from barrel files.
Prepare your pull request
- Code follows the conventions above.
bun run check passes with no errors.- Tests added for new rules, with a minimum of 90% coverage.
- Tested locally with at least one supported agent — for example Codex, Claude Code, Gemini CLI, GitHub Copilot CLI, Kimi Code, or Pi. All twelve are listed on the Installation page.
- Documentation updated where needed (
README.md, AGENTS.md).
- No version changes in
package.json.
Version bumping and releases are handled by maintainers only. Never modify the version in package.json or plugin.json directly.
Get development help
bunx cc-safety-net doctor verifies your setup.bunx cc-safety-net explain "<command>" shows step-by-step how a command is analyzed.- Check
CLAUDE.md or AGENTS.md in the source repo for architecture and conventions, and read REVIEW.md before reviewing code.
- Review existing implementations in
src/analyzer/ for code patterns, and tests/helpers.ts for test utilities.
- Open an issue for bugs or feature requests.
Last modified on August 12, 2026
