git:20260811.41d2f74 to git:20260811.9c2c95a

---

description: Set up and verify AgentGuards in Claude Code. Use when the user runs /agentguards:setup, asks to configure AgentGuards, set their API key, or check that the guardrails are wired up correctly.

---

# AgentGuards setup

Set up AgentGuards for the user. The plugin already bundles the MCP server and the

enforcing hooks — the only thing missing is their API key.

## Never do these

They are all wrong, and every one of them has been given to a real user:

- **Never print an `export` or `setx` or `[Environment]::SetEnvironmentVariable`

command for them to run.** You have file tools. Use them.

- **Never tell them to edit a shell profile** (`~/.bashrc`, `~/.zshrc`, a

PowerShell profile). The Claude Desktop app **never reads a shell profile**, so

this does nothing for desktop users and wastes their time.

- **Never mention a "Configure" screen.** There isn't one. The desktop app has no

settings screen for this key.

- **Never end your turn by asking whether they'd like you to set it up.** Setting

it up is what this skill is for. Ask only for the key itself.

If you catch yourself writing any of the above, stop and write the file instead.

## Steps

1. **Find the current key.** Check the `AGENTGUARDS_API_KEY` environment variable

and the `env` block of the settings file for this OS:

- Windows: `%USERPROFILE%\.claude\settings.json`

- macOS/Linux: `~/.claude/settings.json`

**Treat a placeholder as missing.** Values like `ag_YOUR_TOKEN`,

`ag_YOUR_KEY_HERE`, `ag_your_token_here`, or anything containing `YOUR`, are

copy-paste artefacts from the setup page. Say so plainly ("that's the example

value from the setup page, not a real key") rather than reporting it as

configured.

A real key is `ag_` followed by 32 hex characters. If one is already there,

skip to step 4.

2. **Get the key.** Three ways, in order:

a. **They already put it in the message** — e.g. `/agentguards:setup ag_1234…`.

Use it, don't ask again.

b. **Offer the clipboard.** Most people arrive having just copied the key from

the dashboard. Offer: *"If you've already copied your key, I can read it

straight from your clipboard — say the word."* Only read it if they agree:

- Windows: `Get-Clipboard`

- macOS: `pbpaste`

- Linux: `wl-paste`, or `xclip -selection clipboard -o`

Validate before using it, and if the clipboard holds something else, say

only that it didn't look like a key — **never** echo clipboard contents

back, as it may hold something private.

c. **Otherwise ask them to paste it**, from https://agentguards.co/dashboard/keys

Either way, validate it is `ag_` + 32 hex before writing. If it isn't, say why

and ask again. People often paste an Anthropic `sk-ant-…` key here — if you see

one, tell them that's their Anthropic key, not their AgentGuards token.

3. **Write it into the settings file yourself**, at the path for their OS from

step 1:

```json

{ "env": { "AGENTGUARDS_API_KEY": "ag_..." } }

```

Rules that matter:

- **Read the file first and merge — never overwrite.** Their `model`,

`enabledPlugins`, `hooks` and `permissions` must all survive. Add the key

inside `env`, creating `env` only if it is absent.

- If the file doesn't exist, create it, and its directory.

- If it exists but isn't valid JSON, **stop and tell them**. Never rewrite a

file you couldn't parse — you would destroy settings you can't see.

- This file is the right place because both the terminal and the desktop app

read it. That is why a shell profile is not an option here.

- Write the key and nothing else. Don't raise `AGENTGUARDS_URL` or self-hosting

— this plugin is for the hosted service and points at it by default. A

self-hosted appliance uses the separate `agentguards-claude-selfhosted`

plugin, so mentioning it here is noise mid-setup.

Never print the key back, and never write it anywhere else.

4. **Tell them to restart** — settings are read only at startup:

- **Claude Desktop app:** fully quit it. On Windows the X only minimises to the

tray; on macOS the red dot only hides the window. Then reopen.

- **Terminal:** start a new Claude Code session.

5. **Verify after the restart.** Run the `health_check` MCP tool

(`ToolSearch(query="agentguards health_check")`; as a plugin its full name is

`mcp__plugin_agentguards-claude_agentguards__health_check`).

`health_check` only proves the service is reachable — **it does not validate

the key**, so a placeholder still returns "ok". To prove the key works, call

Then say plainly what is now on: prompt screening on every message, Bash

command authorization, web-content scanning, and the `check_input` /

`authorize_action` tools.

## Worth knowing

- **Without a key the guardrails are off, not blocking.** The hooks let the turn

through and say so. "Nothing looks broken" is not evidence that setup worked —

verify as in step 5.

- **The plain Chat tab isn't covered.** Hooks run in Agent Mode and Local Code

sessions, which are Claude Code underneath. If you are in a plain chat with no

file access, say so directly: *"I can't set this up from here — open an Agent

Mode or Local Code session and run me there."* Do not fall back to reciting

manual instructions.

- Once a key is set, enforcement fails **closed**: if AgentGuards is unreachable,

actions are blocked. `AGENTGUARDS_FAIL_OPEN=true` prefers availability. Mention

it only if they ask or report unexpected blocks.