{
  "markdown": "# Skarn guard: agent plugins\n\nHook configuration, agent skills, and a local MCP server declaration for [Skarn](https://getskarn.com/?utm_source=agent-guard-readme&utm_medium=referral&utm_campaign=home&utm_content=intro), packaged for four hosts, with a fifth host served from its own repository. This repository is generated at every Skarn release. It contains no binary, no detection rules, and no engine code.\n\nFive units live here, four of them guard units. `claude/` and `codex/` are plugins in the marketplace this repository's root manifest serves, for Claude Code and Codex CLI. `antigravity/` is a plugin directory for the Antigravity CLI (`agy`). The repository root is itself a Gemini CLI extension, because Google's installer and gallery crawler read the manifest from the root. A file at the root is either a repository-level file (this README, LICENSE, SECURITY.md, the marketplace manifest) or a Gemini file (`gemini-extension.json`, `GEMINI.md`, `hooks/`, `skills/`); every other host gets a subdirectory. The fifth unit, `recall/`, is a skill-only plugin in the same marketplace: one skill, no hooks, no MCP server. The Cursor unit is not in this repository at all; it lives at https://github.com/skarn-security/cursor-plugin.\n\nThe guard is a pre-execution hook. Before your agent runs a shell command, applies a patch, writes a file, fetches a URL, calls an MCP tool, or sends a prompt to the model provider, the pending action is scanned by the Skarn detection engine on your machine and gets a verdict: deny (block), ask (escalate to you), or allow (silent). It scans locally, makes no network call, and never prints a raw secret - a verdict names the rule and a redacted preview.\n\n## Install\n\nInstall the skarn binary first (the plugin does not carry it; the hooks call `skarn guard` on your PATH):\n\n```sh\nbrew install skarn-security/tap/skarn\n```\n\nClaude Code:\n\n```sh\nclaude plugin marketplace add skarn-security/agent-guard\nclaude plugin install skarn-guard@skarn\n```\n\nCodex CLI:\n\n```sh\ncodex plugin marketplace add skarn-security/agent-guard\ncodex plugin add skarn-guard-codex@skarn\n```\n\nThe two guard plugins carry different names because one marketplace cannot hold two plugins under the same name, and each ships its host's hook shape (event names, tool matchers, and the `--agent` the guard routes on). Install the one for the host you are wiring. Both carry the `skarn-audit` skill, which runs `skarn assess` and `skarn vet` over this machine and reports redacted findings. Redaction masks the credential values Skarn detects; the surrounding transcript context in a finding is still session-derived, so the skill treats a whole result as session data rather than as safe text.\n\nCodex asks you to trust the hooks the first time you start it after installing: choose \"Trust all and continue\" at the \"Hooks need review\" prompt. Until you do, the hooks do not run and the guard is not protecting you. Trust is a content hash per hook, so any later change to a hook (a version bump, or the audit-to-enforce flip) asks again. Claude Code needs no trust step; the hooks are live in your next session.\n\n`skarn-recall` is a third plugin in the same marketplace, and the marketplace add above already reaches it. It carries one skill, no hooks, and nothing host-specific, so the same plugin serves both hosts:\n\n```sh\nclaude plugin install skarn-recall@skarn\n```\n\n```sh\ncodex plugin add skarn-recall@skarn\n```\n\nThat skill reconstructs what you worked on from your session transcripts, which is why it ships apart from the guard rather than inside it. Transcript content it reads leaves your machine for the model provider serving the agent; redaction masks the credentials Skarn detects, not everything you would call sensitive. Install it when you want that, and scope what it reads by project and by time window.\n\nGemini CLI installs this repository as an extension, which carries the same guard hooks in audit mode, the `skarn-audit` skill, a `GEMINI.md` context file, and the MCP server below:\n\n```sh\ngemini extensions install https://github.com/skarn-security/agent-guard\ngemini extensions list\ngemini extensions uninstall skarn\n```\n\nInstall asks for consent, because the extension declares both hooks and an MCP server, and it asks you to trust the folder. Answer both.\n\nAntigravity CLI installs the `antigravity/` directory of a clone:\n\n```sh\ngit clone https://github.com/skarn-security/agent-guard\nagy plugin install agent-guard/antigravity\nagy plugin list\nagy plugin uninstall skarn-guard\n```\n\n`agy plugin list` reports the plugin with its hook, skill, and MCP server counts. Copying `antigravity/` to `~/.gemini/config/plugins/skarn-guard/` by hand does the same thing.\n\nCursor has its own repository, https://github.com/skarn-security/cursor-plugin, generated by the same release. Cursor's marketplace and its review are per repository, which is why that unit does not live here.\n\n`skarn setup` is the alternative install path for Claude Code, Codex CLI, Cursor, Copilot CLI, Gemini CLI and Grok Build: it merges the same hooks into each of those hosts' native config without the plugin system. It does not know the Antigravity CLI, so that host installs the plugin directory above or merges its hook file by hand.\n\n## Local MCP server\n\nEach of the four guard units (`claude/`, `codex/`, `antigravity/`, and the Gemini extension at the root) declares the same stdio MCP server, which the host starts by running `skarn mcp` from your PATH. Cursor and VS Code take it in one click:\n\n[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=skarn&config=eyJjb21tYW5kIjoic2thcm4iLCJhcmdzIjpbIm1jcCJdfQ%3D%3D)\n\n[![Add to VS Code](https://img.shields.io/badge/VS_Code-Add_skarn_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=skarn&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22skarn%22%2C%22args%22%3A%5B%22mcp%22%5D%7D)\n\nBoth buttons register the server as `skarn` and run `skarn mcp` from your PATH, so install the binary first. If you would rather not install it, the pinned launcher form works with only Node present: [Cursor](https://cursor.com/install-mcp?name=skarn&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBza2Fybi1zZWN1cml0eS9za2FybkAwLjI4LjAiLCJtY3AiXX0%3D) or [VS Code](https://vscode.dev/redirect/mcp/install?name=skarn&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40skarn-security%2Fskarn%400.28.0%22%2C%22mcp%22%5D%7D) - it downloads `@skarn-security/skarn@0.28.0` on first run and reuses the npx cache afterwards; a newer Skarn needs a newer link.\n\nManual configuration for any client:\n\n```json\n{\n  \"mcpServers\": {\n    \"skarn\": {\n      \"command\": \"skarn\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nIt runs on your machine, makes no network call, and exposes four read-only tools: `scan_sessions` (findings from past sessions, every previewed value redacted), `vet_configs` (a masked report on your assistant configuration surface), `list_sessions` and `session_stats` (metadata and aggregates, never message content). There is no write tool and no tool that returns message content.\n\nTwo content tools, `search_sessions` and `get_session`, appear only if you start the server as `skarn mcp --enable-recall`. Both mask what they return, and the content still leaves your machine for the model provider serving the session, so the declarations above do not set the flag. `search_sessions` refuses a call that names neither `hours` nor `project`; `get_session` takes one exact `session_id`, which is already its scope.\n\nIf you would rather not install the binary yourself, a version-pinned npx form works:\n\n```json\n{\n  \"mcpServers\": {\n    \"skarn\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@skarn-security/skarn@0.28.0\", \"mcp\"]\n    }\n  }\n}\n```\n\nnpx downloads the package the first time the server starts and caches it afterward, so the first start is slower and needs network access. Pin the version. The unpinned form resolves to whatever the registry serves at start time, and `skarn vet` reports it as `vet-mcp-unpinned`. Do not use it.\n\n`llms-install.md` at this repository's root is the same install in agent-readable steps, for a client that wires the server up for you.\n\nEach host reports a missing binary its own way. `claude mcp list` says `Failed to connect` with `Executable not found in $PATH: \"skarn\"`. `gemini mcp list` shows the `skarn` server as `Disconnected`. `codex mcp list` runs no health check, so the row stays listed and enabled and the server fails when a session starts it. Cursor shows the plugin's row as `Error - Show Output`, and the output panel ends with `spawn skarn ENOENT`. In every case, run `skarn --version` in a terminal: `command not found` means the binary is not installed or is not on the PATH that host inherits, which is the usual answer for an application launched from a desktop rather than a shell.\n\n## Audit first, then enforce\n\nBoth guard plugins ship in **audit** mode (`skarn-recall` has no hooks, so it has no mode): the guard reports the verdict it would have returned and never changes what your agent does. Run it that way first and measure your real would-block rate. Set `SKARN_GUARD_LOG=<path>` in the environment your agent inherits and the guard appends one redacted JSONL record per flagged call (`ts`, `verdict`, `tool`, `rule`, `severity`, redacted reason, `session`, `cwd`, `latency_ms`); clean calls are not logged.\n\nWhen the log looks clean, flip the `--guard-mode audit` in the hook command to `--guard-mode enforce`, or run `skarn setup --update --mode enforce`. Enforcement requires a Skarn license; without one the guard stays in audit and reports rather than blocks, so a lapsed license never breaks your editor.\n\nKeeping a hook current as Skarn releases widen a host's event set is the plugin update below, not a Skarn command: these plugins carry their own hook files, and `skarn setup --update` refreshes only the Skarn-owned entries that `skarn setup` itself wrote, at whichever scope it wrote them (per-user by default, or the repo config under `--scope project`). For a config wired that other way, `--update` rewrites those entries to whatever the installed binary writes, replacing each one whole except for a hook-call timeout you tuned yourself (`timeout`, or `timeoutSec` on Copilot), which is carried across when it pairs unambiguously with its replacement and the value is sane, so a per-machine budget survives the refresh; any other field you added to such an entry is dropped. Run at a terminal, `skarn guard report` and `skarn assess` name a setup-wired per-user hook that has fallen behind, once per release, with the exact update command for that host.\n\n## Updating\n\nClaude Code:\n\n```sh\nclaude plugin marketplace update skarn\nclaude plugin update skarn-guard@skarn\n```\n\nCodex CLI (it has no update verb; re-adding installs the new version):\n\n```sh\ncodex plugin marketplace upgrade\ncodex plugin add skarn-guard-codex@skarn\n```\n\nPlugin updates and binary updates are independent: the hook commands invoke `skarn guard` on PATH, so `brew upgrade skarn` alone gives you the newer detection engine. A plugin update matters when anything the plugin itself carries changes: the hook shape (a new event, a new flag, a new matcher), a skill's text, or the manifest metadata.\n\n## Safety\n\nThe guard only ever tightens a decision, never loosens one. What happens when the guard itself fails depends on the host, because each host decides what a hook crash, timeout, or malformed output means.\n\nClaude Code, Codex CLI, and Gemini CLI fail open: a malformed event, an out-of-scope tool, or any guard error yields allow, and the guard never bricks your agent. The only fail-closed path on those hosts is `--strict` with a licensed enforce, which each host README documents.\n\nThe Antigravity CLI fails closed on every hook outcome except an explicit allow: a crash, a timeout, invalid JSON, and an empty `{}` all block the matched call, in audit mode as well as enforce, and a wired hook with no `skarn` binary on PATH blocks every matched call. The guard answers every event it receives with an explicit decision, and the shipped matcher names only the tools it scopes so that a step outside the matcher can never be blocked by a guard failure. Install skarn before wiring that hook, and remove the entry before uninstalling skarn. Documentation: https://getskarn.com/?utm_source=agent-guard-readme&utm_medium=referral&utm_campaign=home&utm_content=documentation\n\n## License, privacy, and support\n\nThis repository is MIT licensed; see LICENSE. It carries configuration only, so that covers the plugin manifests, the hooks, the skills, and the MCP server declarations in it.\n\nThe `skarn` binary those files invoke is a separate download and is not open source. It is licensed under the Skarn End User License Agreement at https://getskarn.com/terms/, and running it accepts that agreement. What it reads, what it keeps, and what it never sends anywhere: https://getskarn.com/privacy/.\n\nSupport: hello@getskarn.com. Vulnerability reports go to security@getskarn.com; see SECURITY.md in this repository.\n",
  "bytes": 13199,
  "sha": "fa280d77bbe31fe923eb35946cb76e906a6477597de3be0227dc11f75f5ab059",
  "repo_slug": "skarn-security/agent-guard",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_skarn_security_agent_guard_b480c530/readme"
}