Getting started
Install and check your first signed decision. Enforce is free for one machine, with no account or license key. Adding a Solo or Team key is optional. Use Node.js 22 on macOS or Linux. Windows execution is not verified.
Step 1. Install
Section titled “Step 1. Install”Choose the host where your agent runs. Run the install commands in your terminal, then change into the installed plugin root reported by that host before running npm ci. Keep npm lifecycle scripts enabled for that step.
codex plugin marketplace add MerchantGuard/agentguard-codex-plugincodex plugin add agentguard@agentguardIn the installed plugin root:
npm ciStart a new session and open /hooks. Inspect the session-start and session-end commands, both pre-tool gates and the post-tool receipt command, then trust the reviewed definitions. Installing the plugin alone does not trust its hooks. Changed definitions need review again.
claude plugin marketplace add MerchantGuard/agentguard-codex-pluginclaude plugin install agentguard@agentguardIn the installed plugin root:
npm ciReview the plugin source and accept the normal workspace trust prompt only for a directory you trust. Claude Code’s /hooks menu is read-only: use it to inspect the loaded hooks. It does not use Codex’s per-hook trust action. Start a new session after installation; use /reload-plugins after changing plugin definitions.
ChatGPT Work uses the plugin’s local Codex runtime setup on supported surfaces. These commands provision the Codex installation; they do not establish that every Work workspace can run the hooks:
codex plugin marketplace add MerchantGuard/agentguard-codex-plugincodex plugin add agentguard@agentguardIn that installed plugin root:
npm ciWhere your desktop workspace provides the marketplace, select it in the Plugins Directory, install AgentGuard and start a new chat. Node, scripts and dependencies must be present where Work executes them. Review the hook definitions in the Codex runtime as above. Your administrator may need to provision and validate this setup. AgentGuard does not supply a remote MCP connector URL for this installation.
Work availability and hook execution need validation in your actual workspace. Installing a plugin in a web surface does not deploy its local scripts. See OpenAI’s plugin architecture and marketplace setup.
Step 2. Add a key for Solo or Team
Section titled “Step 2. Add a key for Solo or Team”Skip this step for Free. For Solo or Team, replace KEY with the key from your email. Ask your agent to use the installed skill:
Use agentguard-policy to activate license KEY.This is an agent request, not a shell command. The skill passes the key through standard input to runtime/activate.cjs; the helper stores it in the current host’s policy.json and asks the detached worker to refresh the license. It preserves the other policy settings. Do not place the key in shell arguments, audit entries or shared transcripts. An AGENTGUARD_LICENSE_KEY environment setting takes precedence over the policy key.
A new policy requests enforce mode, but a policy already set to shadow remains shadow after activation. Free enforces the local policy with no key. A paid key adds features and seats; it does not override a shadow policy or a refresh failure.
Step 3. See it work
Section titled “Step 3. See it work”Ask your agent:
Use agentguard-status to show my current mode and reason.The skill uses the local read-only get_status tool. These are skill and tool names, not shell executables. With Free or a valid paid key, an enforce policy and healthy worker state, the summary should include:
mode: enforcereason: nullShadow is a fallback or an explicit local policy choice. It records decisions without blocking. Enforce stops calls that the effective policy denies. If the mode is shadow, read the reason before assuming enforcement is active:
| Status reason | What it means |
|---|---|
license_required |
A configured key is invalid or expired. No key uses Free Enforce. |
license_unavailable |
A license refresh failed; the current session is shadow. |
seat_limit |
The license’s active seat limit was exceeded. |
seat_unavailable |
Seat registration or heartbeat could not be confirmed. |
seat_revoked |
An administrator revoked this seat; it remains shadow until explicitly restored. |
org_policy_unavailable |
The org policy refresh could not be confirmed. |
status_unavailable |
Current worker status is unavailable; license details are cached. |
To check a first decision, ask the agent to read a small local file you choose, then use list_decisions to show the newest signed decision and outcome. Ask agentguard-verify to verify the local chain. If records or the MCP tools are unavailable, report that limitation; an empty view is not proof that no tool ran. Hooks that are disabled, untrusted or outside the host’s supported dispatch path cannot record those calls.
Switch between Shadow and Enforce
Section titled “Switch between Shadow and Enforce”To request enforcement after reviewing your policy, ask:
Use agentguard-policy to set mode to enforce, preserving my license key and every other policy setting. Then use agentguard-status to report the effective mode and reason.To request observation without blocking, ask:
Use agentguard-policy to set mode to shadow, preserving my license key and every other policy setting. Then use agentguard-status to report the effective mode and reason.The field values are "mode": "enforce" and "mode": "shadow". Shared team and org policy still apply; an org enforce policy cannot be lowered locally. Licensing and refresh failures select shadow with a reason. The plugin does not change Burn’s separate policy or run Burn’s enforce command.
Or let your agent do it
Section titled “Or let your agent do it”Paste this Free setup request into the agent you are setting up. No key is needed. Add a key separately if you choose Solo or Team. Review and trust the hooks yourself using the host instructions above.
Install the AgentGuard plugin for this host using the matching commands below.Codex:codex plugin marketplace add MerchantGuard/agentguard-codex-plugincodex plugin add agentguard@agentguardClaude Code:claude plugin marketplace add MerchantGuard/agentguard-codex-pluginclaude plugin install agentguard@agentguardRun npm ci in the installed plugin root.Use agentguard-status to show my current mode and reason.Report the mode line.- Free, $0: one machine, no account or key, full Enforce, local signed receipts and Burn. No dashboard, receipts export or org policy.
- Solo, $19 per month or $190 per year: a key for up to three machines, the dashboard, receipts export and email support.
- Team, $199 per month or $1,990 per year: ten seats, one org policy every seat runs, seats you add and revoke, one invoice. Team is the only trial, with a card.
Where your records live
Section titled “Where your records live”The host supplies the data directory. Ask the agent to resolve that directory instead of guessing a path:
| Host | Signed local ledger |
|---|---|
| Codex or supported Work runtime | ${PLUGIN_DATA}/ledger/decisions.ndjson |
| Claude Code | ${CLAUDE_PLUGIN_DATA}/ledger/decisions.ndjson |
The ledger contains tool names, identifiers, input hashes, byte counts and policy results. It does not contain tool input contents or output text. Protect these records and the signing key. The public verification key can be shared; the private signing key must stay private. Internal errors allow the call and may leave a pending, unsigned recovery record until the worker recovers it.
What a STOP looks like
Section titled “What a STOP looks like”Prepared example: synthetic session history with a real Claude Code hook decision and signed receipt. The existing Burn card below demonstrates a blocked spawn, not a customer incident or the outcome you must reproduce to complete setup.
┌────────────────────────────────────────────────────────────────┐│ AGENTGUARD STOP agent spawn blocked │├────────────────────────────────────────────────────────────────┤│ 16 spawns in the last 15 active minutes. ││ 154.0M tokens · 15 spawns · depth 1 │├────────────────────────────────────────────────────────────────┤│ DO NOW ││ 1. Queue agents instead of launching them in parallel; the ││ limit is shared across all of them. ││ 2. Most of this burn is cached context re-sent per agent. ││ Fewer, longer-lived agents beat many short ones. │├────────────────────────────────────────────────────────────────┤│ override once: agentguard-burn resume --once --reason "..." │└────────────────────────────────────────────────────────────────┘Read the reason and adjust the task before retrying. The card’s override is an explicit operator choice, not an installation step. A policy STOP and a licensing failure are different: licensing failures select shadow and do not deny a call.
Verify a receipt
Section titled “Verify a receipt”The simplest check stays local:
Use agentguard-verify to verify my local receipt chain and report the result.Verification is available on every tier. A valid paid license also permits export_receipts; ask the skill for an export to a local destination you choose. The export must include all pages through nextSequence: null before it is described as the complete recorded chain.
For browser verification, paste the export bundle’s entries array into Receipt JSON, then copy publicKeyHex into Public key (hex) and click Verify receipt. You can also paste a single signed entry with its public key. The page does not accept the whole plugin bundle as an entry and has no file-upload control. Use the entries array instead of multiline NDJSON in this flow.
Pasted text is checked in the browser, but the page loads cryptographic modules from a CDN. Keep receipt data out of URL query parameters: those are included in the initial site request. For an offline check, use the local verification skill. A valid result proves the recorded bytes match the supplied key; it does not prove a tool’s real-world outcome or who controlled that key.
Need help? Reply to your welcome email or contact support@agentguard.run. Include the reported mode and reason, never your license key or private signing key.