Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on macOS
A pre-execution guard for AI coding agents. It blocks destructive Git and file system commands, plus common attempts to access sensitive files, before a tool call runs. Supports Amp Code, Antigravity CLI, Claude Code, Codex, Cursor, DeepSeek Harness, Devin CLI, GitHub Copilot CLI, Grok Build, Hermes Agent, Kimi Code, OpenClaw, OpenCode, and Pi.
Saved setup from 9 h ago
Will it work on macOS?
Also: Docs ↗
CONTRIBUTING.mdBug reports, feature requests, and technical analysis are welcome through GitHub Issues.
Pull request creation is restricted to invited collaborators. If you want something fixed or improved, please describe the problem in an issue before spending time on an implementation.
AI-generated submissions have increased the work required to review outside contributions. A plausible patch still needs someone to verify the problem, understand the changes, check their effects on the rest of the project, and work through revisions.
I use coding agents to implement fixes myself. A detailed issue report often helps me resolve a problem faster than reviewing and reworking an unsolicited pull request. Reproduction steps and technical analysis are especially useful.
Most issues are written by coding agents. Whether you are an agent or a person, follow these rules:
gh issue list --search "<keywords>" --state all).
If the problem has already been reported, add new evidence to that issue
instead of opening another.npx cc-safety-net doctor --json
covers most of this and shows whether custom rules are in play.For an incorrect command decision, a destructive command that was allowed or a safe one that was blocked, also include:
npx cc-safety-net explain --cwd <dir> "<command>".npx cc-safety-net logs
(npx cc-safety-net logs --id <id> --json).For a destructive command that was allowed or a protected secret file that was read, also show that a coding agent ran the command while doing real work:
A command you wrote yourself, or one an agent wrote because it was asked to find commands CC Safety Net misses, is not a bug report. That covers bypass research, evasion benchmarks, and GTFOBins-style surveys, at every safety level and for every target, including root and home. Such issues are closed as not planned.
A missed destructive command or an allowed read of a protected secret file is a public bug, not a vulnerability, at every safety level. See SECURITY.md for the few issues that must be reported privately.
Before you submit, remove credentials and tokens. Logs redact secrets but not
file paths: replace private directory names with <project> and ~, keeping
the path structure intact so the command still reproduces.
Explain the problem you need to solve, the behavior you want, and a concrete example of where it would help. The rules above apply: search first, one request per issue, and no patches.
CC Safety Net has a focused scope: preventing coding agents from making
accidental mistakes that cause data loss, such as rm -rf ~/ or
git reset --hard. It is not a general security hardening tool or an attack
prevention system.
Requests for detection rules, configuration changes, documentation corrections, and small bug fixes should all start with an issue. An accepted proposal does not automatically authorize a pull request.
Be respectful and constructive. Keep reports focused on the problem and provide enough information for someone else to investigate it.
This section is for invited collaborators and for anyone running a local build.
package.json defines the project Bun version in packageManager. CI, bun run build,
and Git hooks use that version automatically, independently of your global Bun version.
If it differs, the launcher downloads and caches the selected Bun through bun x;
this requires network access on first use or after cache eviction. To run another
command with the project runtime, use bun scripts/project-bun.ts run check.
To upgrade Bun, change packageManager, rebuild, and commit the regenerated artifacts.
# Clone the repository
git clone https://github.com/kenryu42/cc-safety-net.git
cd cc-safety-net
# Install dependencies
bun install
# Build for distribution
bun run build
# Check for all lint errors, type errors, dead code and run tests
bun run check
Build the project:
bun run build
Disable the safety-net plugin in Claude Code (if installed) and exit Claude Code completely.
Run Claude Code with the local plugin:
claude --plugin-dir .
Test blocked commands to verify your changes:
# This should be blocked
git checkout -- README.md
# This should be allowed
git checkout -b test-branch
[!NOTE] See the official documentation for more details on testing plugins locally.
Build the project:
bun run build
Update your OpenCode config (~/.config/opencode/opencode.json or opencode.jsonc):
{
"plugin": [
"file:///absolute/path/to/cc-safety-net/dist/index.js"
]
}
For example, if your project is at /Users/yourname/projects/cc-safety-net:
{
"plugin": [
"file:///Users/yourname/projects/cc-safety-net/dist/index.js"
]
}
[!NOTE] Remove
"cc-safety-net"from the plugin array if it exists, to avoid conflicts with the npm version. Or comment out the line if you're usingopencode.jsonc.
Restart OpenCode to load the changes.
Verify the plugin is loaded: Run /status and confirm that the plugin name appears as dist.
Test blocked commands to verify your changes:
# This should be blocked
git checkout -- README.md
# This should be allowed
git checkout -b test-branch
[!NOTE] See the official documentation for more details on OpenCode plugins.
# Run all checks (lint, type check, dead code, tests)
bun run check
# Individual commands
bun run lint # Lint (Oxlint, type-aware)
bun run lint:comments # Code-comment check (see "Comments" in AGENTS.md)
bun run format # Format (Oxfmt)
bun run format:check # Formatting check (Oxfmt)
bun run typecheck # Type check
bun run knip # Dead code detection
bun run check-duplicates # Duplicate-code detection (jscpd)
bun run test # Run tests (30 s per-test timeout, as in CI)
# Run specific test
bun run test tests/gate/analyzer/git-rules.test.ts
# Run tests matching pattern
bun run test --test-name-pattern "checkout"
# Build for distribution
bun run build
| Convention | Rule |
|------------|------|
| Build/test runtime | Bun, pinned in package.json |
| Published runtime | Node.js 22+ |
| Package Manager | bun only (bun install, bun run) |
| Formatter | Oxfmt |
| Linter | Oxlint (type-aware) |
| Type Hints | Rely on inference; annotate exports only where it adds clarity |
| Type Syntax | type \| null preferred over type \| undefined |
| File Naming | kebab-case (e.g., worktree-relaxation.ts, not worktreeRelaxation.ts) |
| Function Naming | camelCase for functions, PascalCase for types/interfaces |
| Constants | SCREAMING_SNAKE_CASE for reason constants |
| Imports | Relative imports within package |
This section applies only to invited collaborators. Everyone else should report problems or propose changes through GitHub Issues.
Before implementing a change, agree on its scope with the maintainer in the related issue.
main.AGENTS.md and the project conventions.bun run check after completing
the changes.AGENTS.md and the project conventionsbun run check passes (lint, types, dead code, tests)AGENTS.md)package.jsonImportant: Version bumping and releases are handled by maintainers only.
package.json or plugin.json directlybun run test:e2e:live. It spends real tokens, so it stays out of bun run check and
per-commit CI, and it is the only evidence for the per-host-version claim that a PreToolUse
deny still holds in Claude Code's bypass and auto permission modes..github/workflows/prepare-release.yml with a bump type (patch, minor, or major).
It computes the next stable version from package.json on main. An explicit version input
overrides the bump. Its dry-run mode performs the same checks without changing Git.main at origin/main, updates both version manifests, rebuilds and
verifies every package surface, then atomically pushes one release commit and one new immutable
tag..github/workflows/publish.yml workflow independently rebuilds and verifies the
exact npm tarball before trusted publishing with provenance. It attaches the tarball and its
SHA-256 checksum to the GitHub release.kenryu42/cc-safety-net, workflow filename
publish.yml, environment npm, and permission to run npm publish. Protect release tags and
configure the GitHub npm environment with the required maintainer reviewers. The workflow
refuses branch-dispatched runs even when the input names a valid tag.main, or unpublish a bad npm version.gitHead, tarball, checksum, draft/prerelease state, and exact asset allowlist before
completing only the missing release assets. Any npm version collision before tag creation is a
hard stop.bunx cc-safety-net doctor to verify your setup is working correctlybunx cc-safety-net explain "git command" to see step-by-step how a command is analyzedCLAUDE.md or AGENTS.md for detailed architecture and conventionssrc/gate/analyzer/tests/helpers.ts for test utilitiesThank you for taking the time to report problems and share ideas. It helps keep AI-assisted coding safer for everyone.
Then run bash setup.sh. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: xcode-select --install
git clone https://github.com/kenryu42/cc-safety-net.git cd cc-safety-net
Node.js >=22, Bun
# needs nvm: brew install nvm (or https://github.com/nvm-sh/nvm) nvm install --lts curl -fsSL https://bun.sh/install | bash
bun install
bun run test
You need Node.js 22 or higher. Install into the coding CLIs on this machine, then check that protection is working:
npx -y cc-safety-net@latest install
npx -y cc-safety-net@latest doctor
Update with npx -y cc-safety-net@latest update and uninstall with npx -y cc-safety-net uninstall. Keep the @latest qualifier: a bare cc-safety-net spec can run an older copy from the npx cache. Per-CLI requirements are in Installation.
No reports for macOS yet.
GitManual AI Agent reads the 9 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.