hol-guard

HOL Guard

HOL Guard protects local AI harnesses before tools run. Use it for runtime safety, approval review, package verification, and auditable evidence around agent actions.

Safety Rules

Never read .env files.
Never bypass Guard approvals.
Do not claim a workspace is protected until a Guard command proves it.
Prefer reversible Guard commands over manual harness configuration edits.
Treat scanner failures as real until inspected.
Preserve user changes and inspect git status --short before editing a repository.

Install Check

Probe the CLIs directly so the check works across shells:

hol-guard --version
plugin-scanner --version

If hol-guard is missing and the user asked for runtime setup, prefer an isolated install:

pipx install hol-guard

If plugin-scanner is missing and scanning was requested, install its separate distribution:

pipx install plugin-scanner

Do not assume the hol-guard distribution provides the plugin-scanner command. If pipx is unavailable, explain that isolated CLI installation is recommended rather than silently modifying the user's Python environment.

After installing HOL Guard:

hol-guard status
hol-guard detect --json

Protect a Local Harness

First detect the exact supported harness, then use Guard-owned setup:

hol-guard detect --json
hol-guard bootstrap
hol-guard install <harness>
hol-guard run <harness> --dry-run
hol-guard run <harness>
hol-guard doctor <harness> --json
hol-guard status

Supported harness names include:

codex
claude-code
copilot
cursor
gemini
hermes
openclaw
opencode
antigravity

Use the exact detected harness rather than assuming another healthy harness protects the current session. Hermes has its own bootstrap flow:

hol-guard hermes bootstrap

Review Approvals and Evidence

When Guard blocks or queues work:

hol-guard approvals
hol-guard approvals open <request-id>
hol-guard receipts
hol-guard diff <harness>

For terminal-only resolution:

hol-guard approvals approve <request-id>
hol-guard approvals deny <request-id>

Only approve after reading the risk reason and understanding the requested scope.

For audit evidence:

hol-guard inventory
hol-guard abom --format json
hol-guard events
hol-guard explain <artifact-id>

Cloud sync is optional and user-directed:

hol-guard connect status
hol-guard sync

Scan a Plugin or Skill Package

Use the separate scanner for Codex plugins, Claude Code project surfaces, skills, MCP server configs, and marketplace packages:

plugin-scanner lint <path>
plugin-scanner verify <path>

For JSON evidence:

plugin-scanner verify <path> --json

Do not execute an untrusted target repository merely to scan it. Scan its package or repository files directly.

Report Results

State:

the command that ran;
what HOL Guard or plugin-scanner found;
what remains blocked or risky;
what evidence exists;
the exact next command if the user must act.

Never claim protection, approval, or release readiness without command output proving it.