HOL Guard integration

HOL GuardOfficial extension listing

Syngraphe gives coding agents shared repository context. HOL Guard reviews agent actions before they run. Its command.syngraphe extension recognizes context changes made through both syngraphe and syg, so you can inspect a plan before an agent applies it.

The extension ships with HOL Guard and was included in HOL Guard 3.17.2. It is an External opt-in extension: installing Guard does not activate it. A local administrator must enable it on the device.

Install and connect Guard to your agent

Install Syngraphe using the installation guide. For direct CLI use, a global installation provides both executable names:

npm install -g syngraphe

HOL Guard's installation instructions offer a Python installation through pipx, requiring Python 3.10 or newer:

pipx install hol-guard
hol-guard init

Follow the first-run wizard to configure protection for the coding agent you use. The wizard asks before making setup changes. Check the installation and inspect the shipped extension:

hol-guard --version
hol-guard status
hol-guard command extensions command.syngraphe --json

For an existing installation, use hol-guard update if the extension is unavailable.

Guard must be connected to the agent's execution path. For example, HOL Guard documents this explicit Codex setup:

hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex

After configuring Codex, diagnose its integration:

hol-guard doctor codex

Use the agent support matrix for your agent's integration and coverage. Protection applies at the execution points that integration supports; installing Guard alone does not intercept every command in an ordinary terminal.

Enable the Syngraphe extension

In Guard's local dashboard, open Modules → Protection Center and locate Syngraphe repository context protection (command.syngraphe). Use its Change settings flow to enable the external extension on this device and complete the local approval step. Keep the covered operations at their recommended review treatment.

Inspect the module and its effective permission settings from the CLI:

hol-guard command controls show command.syngraphe
hol-guard command controls patterns --tool command.syngraphe

The extension catalog describes shipped coverage; the controls describe the device's effective settings. See Guard's Local Extensions and protection settings for the settings and approval flow.

What gets reviewed

With the extension enabled and its recommended settings, these operations contribute a review requirement:

Operation	Examples	Repository effect
Initialize context	syngraphe init, syngraphe init --policy	Creates context and agent bootstrap files, updates an older managed body, and optionally creates AGENT-POLICY.md.
Create an agent policy	syngraphe policy add, syngraphe policy add --force	Creates the root policy file; --force replaces an existing one.
Create a context document	syngraphe truth new domain-model, syg decision new use-postgres, syngraphe state new migration, syngraphe history new release-notes	Writes a document in the selected context.
Archive current state	syngraphe state archive phase-one	Creates a history document and resets the selected context's state/current.md.

Read-only commands such as status, check, stats, document list commands, help and version queries do not trigger these mutation rules. A valid --dry-run is the safe counterpart of each covered mutation, including init --policy and policy add --force.

--scope <path> selects an existing Git-root-relative directory and keeps the same classification for commands that support it. policy add always targets the Git root and rejects --scope. See the CLI reference for valid flags and arguments.

These are the extension's classifications. Guard retains the final decision: another matching rule, device setting or managed restriction can still require review or block the command. A dry run in one segment does not clear other actions in a compound shell command. The coverage is defined in HOL Guard's canonical Syngraphe extension source.

Inspect, then apply

From a Git working tree where Syngraphe has already been initialized (syngraphe init), ask the protected agent to preview the change first:

syngraphe decision new use-postgres --title "Use PostgreSQL" --dry-run --json

Syngraphe runs the same planner as the real operation and changes neither repository contents nor Git state. --json renders a content-free plan; on mutating commands it requires --dry-run. It does not make a real write automatic on its own.

Read the plan, then ask the agent to apply the same change:

syngraphe decision new use-postgres --title "Use PostgreSQL"

Guard evaluates the real mutation and routes it through review according to the active policy. Resolve the request through the agent's supported approval interface or Guard's local approval center. Once applied, check the repository context:

syngraphe check

To inspect Guard's decision separately, use its explanation command:

hol-guard command explain 'syngraphe decision new use-postgres --dry-run --json'
hol-guard command explain 'syngraphe decision new use-postgres'

These commands evaluate the supplied command text without executing it or creating an approval. If a mutation receives no Syngraphe review, check the installed catalog, the local opt-in setting, and the agent integration. For other decisions, inspect the matching rules and effective settings. See HOL Guard's command inspection guidance.