hol-guard-plugin — Claude Code and Codex plugin
Plugin for Claude Code and Codex that inspects tool invocations before execution and blocks suspicious operations. Sits on a local approval layer; requires hol-guard CLI pre-installed.
Apache-2.0 ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install hol-guard-plugin@awesome-codex-pluginsWhat hol-guard-plugin does
HOL Guard runs on Claude Code, Codex, Cursor, Copilot CLI, DeepSeek Harness, Gemini, and other platforms. The plugin taps into a local approval system: before an agent runs a tool, HOL Guard reviews it for risks and either requests confirmation or blocks the call outright.
When installed in DeepSeek Harness, the plugin uses native policy layers: async review via tools/pre-execute, integration with the one-time approval service, and a monotonic final gate before command dispatch. Missing Guard response, timeout, rejected approval, or sandbox-required outcome — all close access. A regular pre-execute listener cannot override a HOL Guard denial.
The plugin ships with a portable plugin-scanner skill for checking repositories, plugins, and MCP servers before release, plus an MCP server with built-in search and fetch tools for local receipt storage. Requires Python ≥ 3.10 and hol-guard version 2.0.1024 or later.
What it helps with
- block tool invocations that pose security risks
- scan a plugin before publishing to a marketplace
- inspect MCP servers and skills for vulnerabilities
- retrieve a local receipt for each review
- wire security checks into CI/CD pipelines
Example prompts for the agent
- Use HOL Guard to protect this workspace before running agent tools
- Scan this plugin for release with HOL Guard
- Run
bash scripts/hol-guard-plugin scan .from the project root
How to install hol-guard-plugin
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install hol-guard-plugin@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about hol-guard-plugin
How do I install hol-guard-plugin in Claude Code?
Run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install hol-guard-plugin@awesome-codex-plugins. Make sure hol-guard is already installed: pipx install hol-guard.
What does hol-guard-plugin do?
The plugin reviews tool calls before execution, prompts for local approval on risky operations, and can block a command entirely if it is flagged as suspicious.
What is the minimum hol-guard version required?
hol-guard version 2.0.1024 or higher is required, plus Python ≥ 3.10. Check the version with hol-guard status.
Source text
hol-guard-plugin · Apache-2.0
# HOL Guard Plugin
[](https://hol.org/guard)
[](https://skills.sh/hashgraph-online/hol-guard-plugin)
Codex and DeepSeek Harness plugin for HOL Guard, the local AI security layer from [`hol-guard`](https://github.com/hashgraph-online/hol-guard).
HOL Guard protects local AI harnesses before tools run. It can inspect Codex, Claude Code, Copilot CLI, Cursor, DeepSeek Harness, Gemini, Hermes, OpenClaw, OpenCode, and Antigravity surfaces, then route risky changes through local approvals and receipts.
## Install in DeepSeek Harness
Install HOL Guard first:
```bash
pipx install hol-guard
hol-guard status
```
Add the plugin to each DSH profile you use:
```bash
dsh plugin --profile headless add github:hashgraph-online/hol-guard-plugin
dsh plugin --profile web add github:hashgraph-online/hol-guard-plugin
```
Verify that the composed profile contains `hol-guard-plugin`:
```bash
dsh --profile headless --dump-config
```
You can also let HOL Guard install its managed local copy into detected DSH profiles:
```bash
hol-guard install dsh
```
### DSH enforcement contract
The plugin uses both DSH policy layers instead of relying on a reorderable listener alone:
1. `tools/pre-execute` performs the bounded asynchronous HOL Guard review.
2. Guard `ask`, `review`, and `require-reapproval` outcomes use DSH's native one-time approval service when it is mounted.
3. The resolved decision is latched onto the exact DSH execution.
4. `ctx.tools.guard()` enforces the latch as a monotonic final denial boundary before dispatch.
A missing Guard command, timeout, malformed response, rejected or unavailable approval, `sandbox-required` outcome, incomplete review, or another plugin short-circuiting the pre-execute waterfall fails closed and prevents the tool from running. An ordinary pre-execute listener cannot force-allow a HOL Guard denial.
See [DeepSeek Harness security boundary](docs/dsh-security-boundary.md) for the ordering, failure matrix, trust properties, and explicit limitations.
## Install the security skill
Install the portable `plugin-scanner` skill with the open Skills CLI:
```bash
npx skills add hashgraph-online/hol-guard-plugin --skill plugin-scanner
```
The Skills CLI supports many coding agents. The skill asks before installing the separate `plugin-scanner` package and never executes code from a repository just to scan it.
## What this plugin adds
- A native DSH bundle with asynchronous Guard review, native one-time approval, and a monotonic pre-dispatch denial guard.
- A public Codex skill at [`skills/hol-guard/SKILL.md`](skills/hol-guard/SKILL.md).
- A portable security skill at [`skills/plugin-scanner/SKILL.md`](skills/plugin-scanner/SKILL.md).
- Guard setup guidance for Codex, Claude Code, Copilot CLI, Cursor, DeepSeek Harness, Gemini, Hermes, OpenClaw, OpenCode, and Antigravity.
- Scanner guidance for Codex plugins, Claude Code project surfaces, skills, MCP servers, and marketplace packages.
- Helper script for common `hol-guard` and `plugin-scanner` workflows.
- Validation for the Codex manifest, DSH bundle, skill assets, script paths, and `.mcp.json`.
## MCP server
This plugin includes a `.mcp.json` that registers the HOL Guard local MCP server (`guard-mcp.v1`). The server runs directly via the `hol-guard` binary, with no package-manager startup or shell wrapper.
### Prerequisites
- `hol-guard` CLI installed and on PATH (minimum version: 2.0.1024)
- Python >= 3.10
### Tools
| Tool | Input | Returns |
| :--- | :--- | :--- |
| `search` | `{query: string}` | Max 20 sanitized results from local receipts and inventory |
| `fetch` | `{id: string}` | Single receipt or inventory item, max 32 KiB sanitized text |
| `get_guard_status` | `{}` | CLI availability, receipt count, inventory count |
All tools return a `guard-mcp.v1` contract envelope with `contractVersion`, `source: local`, `generatedAt`, and `freshness: real-time`.
### Local vs Cloud
- **Local** (`hol-guard mcp serve --stdio`): reads local Guard data offline. No network access required.
- **Cloud** (`/api/guard/mcp` on the portal): reads synced workspace data. Requires OAuth Bearer token with `guard:workspace.read` and `guard:receipt.read` scopes.
### Setup
```bash
pipx install hol-guard
hol-guard status
```
The `.mcp.json` is automatically discovered by MCP-compatible clients. No additional configuration is needed.
## Install HOL Guard locally
Recommended:
```bash
pipx install hol-guard
```
Fallback:
```bash
python3 -m pip install --user hol-guard
```
Verify:
```bash
hol-guard status
hol-guard detect --json
```
## Use from Codex
Install this plugin in Codex, then ask:
```text
Use HOL Guard to protect this workspace before running agent tools.
```
or:
```text
Use HOL Guard to scan this plugin before release.
```
## Local helper
```bash
bash scripts/hol-guard-plugin status
bash scripts/hol-guard-plugin harnesses
bash scripts/hol-guard-plugin protect claude-code
bash scripts/hol-guard-plugin protect codex
bash scripts/hol-guard-plugin protect dsh
bash scripts/hol-guard-plugin scan-system claude .
bash scripts/hol-guard-plugin scan-system codex .
bash scripts/hol-guard-plugin scan .
bash scripts/hol-guard-plugin evidence
```
The helper does not read `.env` files. It only calls `hol-guard` and `plugin-scanner` commands already exposed by their respective upstream distributions.
## Supported harness systems
| System | Helper command | Guard command |
| :--- | :--- | :--- |
| Codex | `bash scripts/hol-guard-plugin protect codex` | `hol-guard install codex` |
| Claude Code | `bash scripts/hol-guard-plugin protect claude-code` | `hol-guard install claude-code` |
| Copilot CLI | `bash scripts/hol-guard-plugin protect copilot` | `hol-guard install copilot` |
| Cursor | `bash scripts/hol-guard-plugin protect cursor` | `hol-guard install cursor` |
| DeepSeek Harness | `bash scripts/hol-guard-plugin protect dsh` | `hol-guard install dsh` |
| Gemini CLI | `bash scripts/hol-guard-plugin protect gemini` | `hol-guard install gemini` |
| Hermes | `bash scripts/hol-guard-plugin protect hermes` | `hol-guard hermes bootstrap` |
| OpenClaw | `bash scripts/hol-guard-plugin protect openclaw` | `hol-guard install openclaw` |
| OpenCode | `bash scripts/hol-guard-plugin protect opencode` | `hol-guard install opencode` |
| Antigravity | `bash scripts/hol-guard-plugin protect antigravity` | `hol-guard install antigravity` |
## Validation
```bash
npm test
```
The repository also runs an actual DSH headless session against a local OpenAI-compatible mock inference endpoint. The control session executes a bash tool call, while the protected session proves HOL Guard's native DSH gate blocks the same call:
```bash
npm run test:dsh-e2e
```
No provider key is required for the end-to-end test.
## Source projects
- Plugin repository: https://github.com/hashgraph-online/hol-guard-plugin
- Guard and scanner source: https://github.com/hashgraph-online/hol-guard
- DeepSeek Harness source: https://github.com/deepseek-ai/deepseek-harness
- HOL Guard product: https://hol.org/guard
- Plugin security dataset: https://huggingface.co/datasets/HashgraphOnline/hol-plugin-security
Snapshot of catalog scores (~205 scored plugins), modeled Guard runtime fixtures, and public advisories. Scan ≠ safety guarantee. Catalog plugin count is not the Registry Broker agent catalog. HOL publishes it; not independent validation. Do not attribute Hashgraph Online's org-wide GitHub stars to this plugin repository.
© Hashgraph Online · Apache-2.0 · hashgraph-online/awesome-codex-plugins