HOL Guard: A Runtime Gate for Agent Tool Calls, Not a Malware Scanner
Open-source antivirus for AI agents: block risky tools, secret access, prompt injection, malicious packages, MCP servers, plugins, and skills at runtime.
At a glance
- What is it?
- HOL Guard is a local-first Python tool that intercepts shell commands, file access, package installs and MCP tool calls from AI coding agents and applies allow, block or approval policy. Its coverage is bounded by whatever hook events each agent actually exposes, and the README says so.
- Who is it for?
- Adopt HOL Guard if you already run one of the listed agents in a terminal and want a reviewable record of what that agent tried to execute, with approvals routed to a prompt you control. Do not adopt it if you need kernel-level enforcement or coverage of an agent that is not on the support matrix.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap HOL Guard is aimed at: an agent that can run anything your shell can
A coding agent with shell access inherits your user account. It can read ~/.aws/credentials, rewrite a build directory, install a package from a registry, or call an MCP tool that does any of those things on its behalf. The README frames the product as a layer that "reviews agent actions before they run: shell commands, file access, package installs, and MCP tool calls." That is a different position from a static scanner. It sits in the path of the action rather than inspecting an artifact after the fact.
The intended user is someone running an agent locally who wants a decision point and a record. The README names a long list of supported agents, including Codex, Claude Code, GitHub Copilot CLI, Cursor, Cline, Gemini CLI, OpenClaw and OpenCode. If your agent is not on that list, the product has no hook to attach to. The README is explicit that coverage depends on the events each agent exposes, and points to a support matrix that documents enforcement, approval delivery and failure behavior per integration. That sentence is the honest boundary of the whole design, and it is worth reading before anything else.
How the interception actually works: native hooks, managed proxies, launch integrations
The README describes three attachment mechanisms: native agent hooks, managed MCP proxies, and launch integrations. Guard does not sandbox the process. It registers itself where the agent already emits events, then classifies what flows through.
For MCP, the mechanism is a proxy. Guard inspects server configuration and reviews tool calls through supported hooks and managed proxies. That means the tool call passes through Guard before reaching the server, which is where a block can actually take effect. For Codex specifically, the README states that Guard installs native pre-tool hooks and refuses a managed launch if those hooks are missing or disabled. That refusal is a real design decision: rather than running unprotected and reporting success, a managed launch fails closed when its enforcement point is absent.
The artifact side is separate from the call side. Guard inventories local plugins, skills and agent configuration, and reviews new or changed tools before launch. The README's dry-run example makes the sequence concrete: hol-guard run codex --dry-run records the current artifact state before launch. So there are two data flows, one over live tool calls and one over the local artifact inventory, and the diff between recorded and current state is what the launch review operates on.
Getting it running: pipx, init, and per-agent install
Installation assumes Python 3.10 or newer and pipx. The README gives two commands:
pipx install hol-guard hol-guard init
The first-run wizard discovers supported agents and walks through protection setup. The README says it asks before each setup change, including opening the dashboard, installing agent integrations, and connecting optional cloud services. Verification is hol-guard --version and hol-guard status. Updates go through hol-guard update.
Per-agent setup is explicit. For Codex the README shows hol-guard install codex, then hol-guard run codex --dry-run, then hol-guard run codex. The dry run is the step that records artifact state before the agent starts, which is what makes the later diff meaningful.
Day-to-day operation is a small command surface: hol-guard status, hol-guard doctor codex, hol-guard diff codex, hol-guard approvals, hol-guard receipts, hol-guard inventory, hol-guard abom --format json, hol-guard supply-chain scan, and hol-guard connect for optional cloud sync. Approvals resolve with hol-guard approvals approve <request-id> or hol-guard approvals deny <request-id>.
The most useful debugging commands are the ones that do not execute anything. hol-guard command test 'rm -rf ./build' and hol-guard command explain 'git clean -ndx' inspect a command's classification and matching rules without running it or creating an approval. hol-guard command extensions command.git --json exposes the extension set behind the command.git rule family. If you are evaluating whether the policy engine agrees with your intuition about what is dangerous, these three commands answer that question without side effects.
The support matrix is the real product boundary
The README repeats one caveat in two places: coverage depends on the events each agent exposes, and the support matrix documents enforcement, approval delivery, and failure behavior per integration. Read that as the central limitation. Guard can only review what the host agent tells it about. An agent that does not surface file reads as an event, or that surfaces tool calls only after execution, gives Guard nothing to block on.
That produces a spectrum rather than a binary. On one end, an agent with pre-tool hooks can be stopped before the command runs. On the other, an integration might only be able to observe and record. The README does not claim uniform enforcement across the listed agents, and the existence of a per-integration failure-behavior column implies the maintainers expect integrations to differ in how they degrade.
This is also the reason the Codex behavior matters as a signal. Guard refusing a managed launch when hooks are missing is a fail-closed posture at the launch layer. Whether the same posture holds for every other listed agent is not something the README states, so treat per-agent refusal semantics as something to verify with hol-guard doctor rather than assume.
Approvals, receipts and the AI bill of materials
The approval center and the receipts log are the parts that make Guard auditable rather than merely restrictive. A blocked action routes to a native prompt or to the approval center, and the decision is written to a local receipt. hol-guard receipts reads that history. hol-guard abom --format json exports an AI bill of materials, which is the artifact inventory rendered in machine-readable form.
There is a practical consequence here. Because receipts are local and the README says Guard runs without an account, the default deployment keeps decision history on the machine. Guard Cloud is optional and adds shared history, team policy and fleet management, connected via hol-guard connect. That split is a genuine trade-off rather than a feature list. Local-only means no central visibility across a team and no shared policy, but also no data leaving the host and no account to provision. Cloud means the opposite.
The receipt log also has a retention question the README does not answer. How long receipts persist, whether they rotate, and what they contain are not specified in the material available. If audit retention matters to you, that is a gap to resolve from the documentation before relying on it.
Where it is the wrong tool
Guard is not a sandbox and does not claim to be one. If your threat model is a malicious agent process that ignores hooks, or an agent runtime you did not configure, a hook-based reviewer is the wrong layer. The README's own framing is review before execution, which presumes the agent cooperates with the hook contract.
It is also the wrong tool for an agent that is not on the supported list. There is no generic interception mode described in the material. The named agents are the coverage.
A third case is scale. This is a pipx-installed Python CLI with a local dashboard and a local receipt store. The README positions Guard Cloud as the answer for fleet management, which implies the local install is not designed for many machines under one policy. A team that needs centralized policy from day one is looking at the cloud path, not the default one.
Finally, prompt injection screening is described as applying to "supported events." That qualifier matters. Prompt screening is not a universal filter over all model input and output; it is bounded by which events the integration emits, the same constraint that governs everything else here.
The alternative: a container or VM boundary instead of a hook
The obvious alternative is to run the agent inside a container or virtual machine with a restricted filesystem and no ambient credentials, and skip the policy layer entirely. The difference in approach is structural rather than incremental. A container boundary does not care what the agent attempts, because the attempt cannot reach the host. Guard does care, which is why it can produce a receipt explaining that a command was blocked and which rule matched.
That distinction cuts both ways. Containers give you a hard boundary but poor visibility into intent: you learn that something was denied by the kernel, not that the agent tried to read a credential file and which rule family caught it. Guard gives you classification and an approval workflow, but only for events the agent chooses to emit. The two are not substitutes. A container constrains the blast radius; Guard documents and gates the action.
There is also a middle option the README implicitly supports: use Guard's inspection commands as a standalone policy check without a live agent. hol-guard command test and hol-guard command explain classify a command string without executing it, and hol-guard supply-chain scan scans workspace dependencies. Those work regardless of whether you have wired up an agent integration, which makes them usable as a pre-commit-style check on their own.
Maintenance cost and licence
The release cadence visible in the material is fast. Three releases landed between 2026-09-09 and 2026-09-10, at versions v3.0.144, v3.0.145 and v3.0.146. A patch-level cadence that tight usually means integration fixes rather than feature drops, and it implies you should expect to run hol-guard update regularly. Whether updates are silent or require re-running per-agent installs is not stated in the README, so plan to check hol-guard status and hol-guard doctor <agent> after each update.
The dependency surface is small: Python 3.10 or newer and pipx. There is a companion PyPI package named plugin-scanner, which the README's badge row references alongside hol-guard, so the plugin and skill scanning path may pull in a separate distribution. The README does not detail that relationship.
Licensing is Apache-2.0. That permits commercial use, modification and redistribution under the terms of the licence, and it includes an explicit patent grant. It is a permissive licence, not a copyleft one, so it does not oblige you to publish modifications. This is a description of the licence identifier in the repository, not legal advice; if you are redistributing Guard inside a product, read the LICENSE file and the NOTICE requirements yourself.
One thing the material does not tell you: how the supply-chain intelligence behind package-install evaluation is sourced or updated. The README says installs are evaluated against supply-chain intelligence, but not where that data comes from or how stale it can get. That is the first question to answer before treating package-install review as a control.
Editorial conclusion
Adopt HOL Guard if you already run one of the listed agents in a terminal and want a reviewable record of what that agent tried to execute, with approvals routed to a prompt you control. Do not adopt it if you need kernel-level enforcement or coverage of an agent that is not on the support matrix. Before trusting it, run hol-guard doctor for your specific agent, then hol-guard command test on a destructive command you know should be blocked, and read docs/guard/harness-support.md to confirm which events your agent exposes and what happens when a hook is missing.
Community notes