Skip to main content

vulkro guard

In-loop security guard for AI coding agents. vulkro guard scans files as the agent writes them and feeds findings back so the agent regenerates until the file is clean.

Where vulkro mcp serve exposes the scanner as an MCP TOOL the agent may choose to call (discovery), vulkro guard wires the scanner into the agent's HOOK system so a scan runs on every file write or edit whether the agent asks for it or not (enforcement). The two compose: run mcp serve for on-demand scans and guard install to make scanning mandatory in the write loop.

Each check is a single-file scan with no network call and no token cost, so it fits inside the agent's edit loop.

Sub-commands​

vulkro guard check <FILE>   # scan one file, emit a verdict the agent consumes
vulkro guard install        # wire the hook into an agent's config
vulkro guard uninstall      # remove the hook the guard installed
vulkro guard status         # show which agents are wired

guard check​

Scan a single file fast and emit a verdict the agent loop can consume. Reuses the standard scanner (same result as vulkro scan), filtered to the one file. Findings at HIGH or CRITICAL severity BLOCK (the agent should regenerate the file); MEDIUM / LOW / INFO are reported but do not block, so the guard never traps the agent on a stylistic nit.

FlagDescription
--hook-format <FORMAT>Output / exit protocol to emit: generic (default), claude-code, or cursor.

The output and exit protocol depend on --hook-format:

  • generic (default): a structured JSON verdict on stdout, the regenerate instruction mirrored to stderr on a block. Exit 0 = clean, exit 2 = block. This intentionally differs from Vulkro's usual 0/1/2 contract: a hook needs a non-zero "stop" code on findings, and Claude Code reserves exit 1 for a non-blocking error, so the guard uses 2 to mean "block and regenerate".
  • claude-code: always exit 0; emits {"decision":"block","reason":...} on a block (fed back to the model) and an empty object when clean. The target file is read from the hook's stdin JSON (tool_input.file_path) when no path argument is given.
  • cursor: always exit 0; emits {"permission":"deny","agent_message":...} on a block or {"permission":"allow"} when clean. The target file is read from the hook's stdin JSON (file_path) when no path argument is given.

Any format also exits 2 on an operational error (file missing, scan failure) with an actionable message on stderr.

guard install​

Idempotently wire vulkro guard check into an agent's hook config so it runs on every file write or edit. Merges into the existing config without clobbering unrelated keys; re-running does not duplicate. Prints the file it changed and how to undo.

FlagDescription
--agent <AGENT>Which agent to wire: claude-code (default), cursor, windsurf, or all.
--scope <SCOPE>user (all projects, the default) or project (this repo only, checked into version control).

Supported agents:

AgentConfigIntegration
claude-code~/.claude/settings.json or .claude/settings.jsonSolid: verified PostToolUse hook schema.
cursor~/.cursor/hooks.json or .cursor/hooks.jsonSolid: verified afterFileEdit hook schema.
windsurf~/.codeium/windsurf/hooks.json or .windsurf/hooks.jsonBest-effort: a generic-format wrapper until the schema stabilises.
all-Wire every supported agent at once.

Exit codes: 0 installed (or already present), 2 error (no home dir, unreadable / malformed config, write failure).

guard uninstall​

Remove the guard hook that install added, idempotently. Removes only the Vulkro-managed entry; your own hooks and unrelated keys are preserved. Re-running after removal is a no-op.

guard status​

Show which agents are wired to run vulkro guard check, the config file each uses, and whether the integration is solid or best-effort. Read-only.

Exit codes​

  • check: 0 clean, 2 block (or operational error). See the protocol above; this differs from the usual contract on purpose.
  • install / uninstall / status: 0 success, 2 error.

Examples​

# Make scanning mandatory in Claude Code, this project only.
vulkro guard install --agent claude-code --scope project

# See what is wired.
vulkro guard status

# Manual single-file check (generic protocol).
vulkro guard check src/handlers/users.ts
Last updated on