gatekeeper-hooks

Cross-platform NPX bootstrapper that installs the Gatekeeper pre-commit enforcement system into any Git repository.

The package is git-driven — it ships nothing language-specific. The hooks fire on git commit and dispatch to language-aware AI agents.

Supported languages (first-class)

Python · C# · .NET · React · Angular · Java · C · C++

(Go, Rust, Node/TS, Kotlin work out of the box too — best-effort.)

Install

npx gatekeeper-hooks

That's it. Hooks now run automatically on every git commit.

Not committed to your repo

The CLI adds itself to .gitignore so the installed runtime stays local. New teammates simply run npx gatekeeper-hooks after cloning. Treat it like node_modules or .venv.

The managed block looks like this and lives between markers (so re-runs are idempotent and never duplicate lines):

# >>> gatekeeper-hooks >>>
# Installed by `npx gatekeeper-hooks` — re-run on each clone instead of committing.
.githooks/
.gatekeeper/
.github/hooks/
.github/agents/
.github/instructions/
.github/skills/
gatekeeper.config.json
.gatekeeper-approved
# <<< gatekeeper-hooks <<<

What gets installed

your-repo/
├── .githooks/
│   ├── pre-commit            ← whitespace, YAML, branch protection
│   └── commit-msg            ← delegates to .gatekeeper/bin/gatekeeper
├── .github/
│   ├── hooks/
│   │   ├── gatekeeper-hook.py            ← Python backend (Linux/macOS)
│   │   └── gatekeeper-copilot-cli.ps1    ← PowerShell backend (Windows)
│   ├── agents/               ← Copilot custom agents (build, quality, etc.)
│   ├── instructions/
│   └── skills/
├── .gatekeeper/
│   ├── bin/
│   │   ├── gatekeeper        ← unified runtime shim (POSIX)
│   │   └── gatekeeper.cmd    ← unified runtime shim (Windows)
│   └── venv/                 ← isolated Python env (auto-created if Python is present)
├── .vscode/
│   ├── settings.json         ← merged: smart-commit disabled, post-commit none
│   └── mcp.json              ← registers Azure DevOps MCP for Work Item Agent
└── gatekeeper.config.json    ← auto-detected stack profiles + check toggles

git config --local core.hooksPath .githooks is set automatically so the hooks activate without further user action.

Work item validation (new in 0.4)

If your commit message contains an Azure DevOps work item reference (#12345 or AB#12345), the Work Item Agent fetches the item's acceptance criteria via the Azure DevOps MCP server and validates that your codebase implements them. No reference in the message → silent skip; ADO unreachable → silent skip. It never blocks a commit on its own.

One-time setup:

1. Open .vscode/mcp.json.
2. Replace <your-ado-org> with your Azure DevOps org slug.
3. Run az login once. Done.

Idempotent

Re-running npx gatekeeper-hooks is safe:

• Existing files in .githooks/, .github/hooks/, .gatekeeper/ are preserved
• Existing gatekeeper.config.json is merged, not overwritten
• Existing .vscode/settings.json keys are preserved (only missing keys are added)
• git core.hooksPath is set only if not already pointing at .githooks

Skipping a single commit

The Gatekeeper AI layer runs at the pre-commit stage, before git has written your new commit message. Use one of these reliable bypasses:

SKIP_GATEKEEPER=1 git commit -m "wip"        # env var (POSIX)
$env:SKIP_GATEKEEPER=1; git commit -m "wip"  # env var (PowerShell)
git commit --no-verify -m "wip"              # built-in git bypass

The skip_gatekeeper keyword in the commit message is not reliable at pre-commit time because git writes .git/COMMIT_EDITMSG only after the pre-commit hook succeeds. Use the env var or --no-verify instead.

Uninstalling

npx -y gatekeeper-hooks@latest --uninstall   # recommended (no npx prompt)
npx gatekeeper-hooks --uninstall             # also fine; npx may ask "Ok to proceed?" first

The -y flag auto-accepts npx's own "Ok to proceed?" prompt that fires when the package isn't cached locally. It does not skip the uninstaller's confirmation — you'll still be asked to confirm the actual removal. Pass --yes after the package name to skip that too: npx -y gatekeeper-hooks@latest --uninstall --yes.

Removes everything this package installed:

• .gatekeeper/ (Python venv + runtime shims)
• .githooks/pre-commit + .githooks/commit-msg
• .github/hooks/gatekeeper-*, gk-memory.py, log files
• gatekeeper.config.json, .gatekeeper-approved
• The managed block in .gitignore
• core.hooksPath git config (only if it points at .githooks)
• Recommended VS Code settings (only if unchanged from defaults)

User content is preserved: any other hooks you wrote in .githooks/ or .github/hooks/, your own .gitignore lines, your VS Code overrides, and the user-customizable directories .github/agents/, .github/instructions/, and .github/skills/ (delete those manually if you no longer want them).

Optional integrations

• GitHub Copilot CLI — gh auth login enables AI-powered code-quality analysis at commit-msg stage. Hooks degrade gracefully if gh is missing.
• Python — when present, a local venv is created at .gatekeeper/venv/ and PyYAML is installed for YAML linting. If absent, those checks are skipped.

Project layout (this package)

gatekeeper-hooks/
├── bin/cli.js
├── lib/
│   ├── installer.js   ← orchestration
│   ├── env.js         ← detect Python / stack / `gh`
│   ├── git.js         ← git config helpers
│   ├── fs.js          ← idempotent recursive copy + chmod
│   └── merge.js       ← deep-merge JSON without overwriting user values
├── templates/         ← copied verbatim into the target repo
└── package.json

License

MIT