skarn(1)
AI coding session security scanner with built-in session search
skarn 0.28.0
New to Skarn? The scanning guide walks through the first skarn assess run per assistant; the research pages publish the measured precision behind the rules.
Real-time guard: every hook event it gates, per host, is documented in the guard hook-event reference.
To wire the guard into your agents, start at the Wire the guard section of the install page.
Synopsis
skarn check [options] skarn assess [options] skarn vet [options] skarn mcp skarn baseline <audit|accept> <file> [<fingerprint>] [options] skarn search <query> [options] skarn recent [options] skarn restore <session> skarn messages <session> [options] skarn stats [options] skarn tools [options] skarn mcps [options] skarn cmds [options] skarn export [options] skarn guard [report|accept <fingerprint>] [options] skarn setup [options] skarn doctor [options] skarn completion <shell> skarn serve [options] skarn taxonomies skarn license [<file>|-|renew] [options] skarn eula [accept] skarn --version skarn --help
Description
Skarn is an AI coding session security scanner with built-in session search. It detects leaked credentials and the attack patterns that cause or exploit them in the local session transcripts of AI coding assistants (Claude Code, Gemini CLI, Codex CLI, Cursor, VS Code Copilot Chat, Kimi Code CLI, Grok Build, Grok Bot, Antigravity, and OpenCode), and it lets you search, browse, and analyze those sessions.
Skarn is a single static binary. It scans locally and makes no network connection by default; the only features that transmit data off the machine are opt-in and named explicitly in the SECURITY section below.
Skarn has two faces over one parsing engine. The recall commands (search, recent, stats, and friends) are the daily-use surface. They match and filter on the raw session text, then mask every detected secret in what they print, which runs the detector over the sessions a command emits; a value the detector matches in any session of that output is masked in every session of it, while a value it matches nowhere in that set prints as recorded; --no-redact prints raw content and skips that scan. The check command is the security scanner: it runs the detection rules, correlates attack chains, and computes a session risk score for CI/CD gating. Every finding is mapped to MITRE ATLAS, the OWASP Top 10 for LLM Applications 2025, and CWE; run skarn taxonomies to print the crosswalk and the pinned framework versions.
Commands
check [options]- Scan AI sessions for leaked credentials and attack patterns.
assess [options]- Scan every AI session on this machine and print a friendly risk summary, with an optional shareable redacted report and a scoped incident dossier. Free, no config, no license. Run at a terminal it also names, once per release, a hook in your own per-user agent config that has fallen behind this build, so an event a newer template gates does not go unscanned unnoticed; it looks at that config only, never at a repo's committed hooks and never at a fleet-managed one.
vet [options]- Statically vet the local AI assistant configuration (hooks, MCP servers, permission grants, plugins and skills) for risky patterns across Claude Code, Codex CLI, Cursor, Copilot, Gemini CLI, Grok Build, Grok Bot, and Microsoft Scout. Read-only and offline; free, no license.
mcp- Run a local stdio MCP server exposing read-only, redacted scan, config-vetting and session-metadata tools to an AI coding assistant.
baseline <audit|accept> <file> [<fingerprint>] [options]- Interactively triage findings into a committed baseline (audit), or record a false-positive fingerprint (accept).
search <query> [options]- Search past AI sessions (literal text, or --regex).
recent [options]- List recent sessions.
restore <session>- Restore a session.
messages <session> [options]- Show the messages of a session.
stats [options]- Session analytics: tokens, models, tools, and timing (text, json, csv, or html).
tools [options]- Show the tools used across sessions.
mcps [options]- Show the MCP calls made across sessions.
cmds [options]- Show the shell commands run across sessions.
export [options]- Export sessions as text, json, ndjson, or html (redacted by default).
guard [report|accept <fingerprint>] [options]- Real-time pre-execution hook for editor/agent integration; reads an event on stdin and emits a verdict. guard report summarizes the audit log, forecasts what enforcing would cost, prints the enforce flip when the window is clean, and at a terminal names, once per release, a hook in your own per-user agent config that has fallen behind this build; guard accept records a flagged finding as a false positive so the guard stops blocking it.
setup [options]- Wire the skarn guard hook into detected AI coding agents (merge-based, reversible), then verify it with the guard self-test.
doctor [options]- Check whether skarn is actually protecting this machine: binary, license, wired agent hooks, guard log, session stores, and the guard self-test.
completion <shell>- Print a shell completion script for bash, zsh, or fish.
serve [options]- Start the local web UI (search, recent, stats, and a redacted scan view) bound to 127.0.0.1, with every detected secret masked.
taxonomies- Print the standards crosswalk (MITRE ATLAS, OWASP LLM Top 10, CWE) and the EU Cyber Resilience Act obligation axis (process evidence relevant to an obligation, not proof of product conformity).
license [<file>|-|renew] [options]- Show the active license, install one from a file (or stdin), or renew it from the license service.
eula [accept]- Print the Skarn End User License Agreement, or record acceptance of the current version (accept).
Options
Check options
Control the security scan: which rules run, the scan window, output format, and CI gating. check requires a license and refuses with exit 7 before any scan without a usable one; the free license is issued at https://getskarn.com/free after a quick email confirmation and is verified offline. Only --audit-verify is exempt: verifying an audit log's hash chain needs no license.
Assess options
The zero-config machine-scan wedge: scan every AI coding session on the machine and print a friendly risk summary, no flags and no license. -o writes a shareable redacted report (HTML or Markdown); --json emits the redacted scan for scripting. The scan is scoped by the same filters as check.
Vet options
Statically vet this machine's AI assistant configuration - hook commands, MCP server definitions, permission grants, and installed plugins and skills across Claude Code, Codex CLI, Cursor, Copilot, Gemini CLI, Grok Build, Grok Bot, and Microsoft Scout - and report the risky patterns it finds: hooks that exfiltrate local content or fetch-and-execute remote code, hooks that post the session event envelope to a remote http endpoint, hooks that rewrite an assistant's own config, MCP endpoints on remote hosts, MCP launchers with no pinned version or digest, permission grants that approve a whole class of actions, grants that let the assistant ask to widen its own authority, and extensions installed from a remote source or carrying no integrity marker, plus two file-level patterns read from permission metadata and declared posture flags alone: a plaintext credential store whose file mode grants group or other read, and an assistant configured with an always-on local-exec and egress channel. Vet reports declared configuration, not the effective merge across layers: a grant a higher layer denies, or a permission mode an administrator lock disables, is still surfaced, because the declaration exists and is one edit away from active. Project configuration is read at the cwd-level file only, so a host that also loads configuration from parent directories is covered there and no further. Vet is read-only and offline: it opens each config file for reading, never writes one, and makes no network call. A config file that does not exist is skipped; a config file that exists but cannot be read is a coverage gap that fails closed under a --fail-on flag. Each of the per-assistant configuration files listed below is opened once and its permission metadata is read off that same handle, and a path that is not a regular file is named as a coverage gap rather than read. The config-file count the report prints, and the configFilesRead field in the json and sarif output, count every such file vet opened and examined, including the two whose contents it deliberately never reads, so a file a finding names is always inside the count rather than absent from it. The hook directories and extension manifests vet also walks keep their own older read path. The one file whose permission metadata decides a finding, Grok Bot's credential store, is additionally opened without following a symlink, so a symlinked store is reported as a coverage gap named SymlinkNotFollowed rather than measured through its target; every other config file is still read through a symlink, so a dotfiles-managed configuration keeps its coverage. Vet surfaces risky configuration and does not change it.
Mcp options
Run a local Model Context Protocol (MCP) server so an AI coding assistant can call Skarn directly. The transport is stdio: newline-delimited JSON-RPC 2.0 on stdin and stdout, one server process per client, and the process exits 0 when the client closes stdin. The negotiated protocol version is 2025-11-25; a client that asks for 2025-06-18 gets that version back, and any other request, including the batch-era 2025-03-26 and the stateless 2026-07-28, is answered with 2025-11-25. Batched requests are not accepted: a top-level JSON array is answered with one -32600 error. Four read-only tools are exposed by default, and --enable-recall adds search_sessions and get_session, which return transcript text and are described under that option. scan_sessions returns the same redacted scan report that skarn assess --json prints, minus the per-incident context snippet and minus every transcript-authored label, which means the project labels on both the incidents and the attack chains and the tool name on an incident, and takes severity, hours and project. vet_configs returns the masked findings report that skarn vet --format json prints and takes no arguments; those findings quote this machine's own configuration, including hook command lines and MCP server definitions, with any credential-shaped value masked. list_sessions returns recent sessions as identifiers and counts only - session id, assistant, the two timestamps, message and tool counts, and token totals - and takes hours, limit, project and cli. session_stats returns the same aggregate counts across those sessions and takes hours, project and cli. Every tool is annotated read-only, non-destructive and closed-world. No tool writes, changes or removes a file, no tool opens a network connection, and no default tool returns session message text or a label authored inside a transcript such as a project name, a git branch, a model id or a tool name. Every value a detector matched is reported only in its masked form, which keeps at most the first character and last two characters and discards the middle; a value under 16 characters, and any personal data, is replaced whole. That is a truncated preview rather than a one-way transform of the whole value. Three classes of string are still passed through as they are: a file path, a session id, and a timestamp. Each is a locator the tools exist to hand back, and each is read from the transcript or the store rather than generated by Skarn, so a credential deliberately planted in a session id or a directory name reaches the client verbatim. A Claude Code store also encodes the project directory into its transcript file name, so the returned session_file carries that directory in encoded form. Every other Skarn surface passes those three through the same way. Tool results are returned to the MCP client that spawned the server, which is the assistant, so they travel wherever that assistant sends its context. The verb needs no license. Project-level configuration for vet_configs is read from the server process's working directory, which is whatever directory the client spawned it in.
Baseline options
Interactive baseline triage. audit walks each new finding and records a true/false-positive decision with a reason into the committed baseline; accept records a single false-positive fingerprint non-interactively. audit runs the same scan check runs and requires a license the same way: any tier, the free one included, and it refuses with exit 7 before any scan when none is usable; accept scans nothing and needs no license. The audit scan is scoped by the same filters as check. A false positive is suppressed on every later scan, while a finding labeled a true positive is recorded and keeps firing until the credential is rotated - the same labels the real-time guard honors. A true positive wins over a false positive on the same fingerprint wherever the two meet, in one file or across the member files of an org baseline directory, so one member cannot silence a leak another member confirmed. A finding that carries a secret is fingerprinted by that secret, so its acceptance follows the secret across sessions and machines; a finding with no secret (a behavioral finding such as prompt poisoning) is fingerprinted by the session it fired in, so accepting it silences that rule in that session only and the same rule in any other session keeps firing. To accept a finding the guard flagged, use skarn guard accept <fingerprint>: it takes the fingerprint straight from the guard's audit record and defaults to the personal baseline the guard reads.
Guard options
Control the real-time pre-execution hook used for editor/agent integration (Claude Code, Cursor, Codex CLI, Copilot CLI, Gemini CLI, Grok Build, and the Antigravity CLI). The report subverb reads the guard's own audit log instead of an event: it summarizes the flagged calls per agent (verdicts, top rules, latency, the most recent denies), states what enforcing that window would have cost (blocks per day, prompts per day), and, when the window spans at least five days with zero denies, prints the exact command that flips the wired hooks to enforce. Run at a terminal it reads one thing more, your own per-user hook configs, so it can name a hook that has fallen behind this build once per release; piped or as json it reads nothing but the log. The guard logs only flagged calls, so every count and every rate report prints is over flagged actions, never over all traffic. The accept subverb closes that loop: an audit record whose top finding carries a secret gets a fingerprint (the same secret-scoped key check writes to SARIF partialFingerprints), report prints it under each such deny, and skarn guard accept <fingerprint> records it as a false positive so the identical call stops being flagged; a secret-less deny (a structural egress detector, a typosquat, a chain) carries no fingerprint and no accept line. The structural egress detectors are built into the engine, not rule-pack rules, and tier themselves: an egress whose whole payload is visible in the command itself - a bare request, a literal body, query parameters, with no file sent, no credential store named, no earlier secret read in the same call, and no payload bytes the command text does not show (a command substitution, an environment expansion, a shell redirect, a form read, or a pipe feeding the target all keep the deny) - is held at the ask tier - a real approval prompt on the primary shell surfaces (Claude Code PreToolUse, Copilot preToolUse on both the CLI and VS Code, Cursor shell and MCP hooks), a block on the channels with no ask (Codex, Claude Code PermissionRequest, Copilot permissionRequest, Cursor file-read events, Gemini, Grok Build) - while a payload carrying a recognized credential file or upload form, a co-detected secret, or recon earlier in the same call stays a deny. Both subverbs are ungated: report reads the log (plus, at a terminal, your own hook configs for the line above), and accept writes only a file. On a flagged call the guard consults the personal accepted-findings baseline it shares with check (~/.config/skarn/baseline.json, the file form only - never the org-union directory, so the guard can never hit a paid gate): a finding accepted as a false positive is dropped from the verdict, while a finding a human confirmed as a REAL leak (skarn baseline audit, label true-positive) is never suppressed and keeps being blocked until the credential is rotated. Only the highest-severity finding of a call carries the fingerprint, so a call hiding several distinct secrets peels one accept at a time; a correlated attack chain still denies even when every secret in the call has been accepted; and a baseline that is missing, unreadable, or malformed suppresses nothing at all - a broken baseline means more blocking, never less.
Setup options
Guided onboarding: detect installed AI coding agents (Claude Code, Cursor, Codex CLI, Copilot CLI, Gemini CLI, Grok Build), merge the skarn guard hook into each one's native config in audit mode, and prove the wiring with the guard self-test. --scope project writes committed, shareable configs whose commands are portable by construction (a PATH-guarded invocation and a literal $HOME log path, never this machine's absolute paths) - with one honest exception: Gemini CLI and Grok Build each read a single cross-platform command field, so a file committed from a POSIX machine carries the POSIX form and a native-Windows teammate's hook fails open with a warning instead of running, and grok's project hooks additionally wait on a /hooks-trust grant; --plugin commits the claude plugin requirement instead of hook entries, and the two project routes are mutually exclusive - each removes the other's skarn-owned entries so the guard can never fire twice. Existing foreign hooks are never touched; every modified file is backed up first (*.skarn-bak.<timestamp>, carrying the target's own permissions) and rewritten atomically; a target file that does not parse as JSON is refused, never overwritten. At --scope project a target that is a symlink, that sits behind a symlinked directory, or whose path skarn cannot examine at all, is refused too, before anything is read or created: a committed symlink can name any file on the machine, and following it would copy that file's bytes into a backup beside it and rewrite it in place. User scope still follows the link, because a dotfiles manager legitimately puts one there - and the atomic rewrite then leaves a regular file where the link was, so a stow-managed config has to be relinked afterwards. On a terminal it runs an interactive wizard with default-yes prompts; --yes accepts everything, --print writes nothing.
Doctor options
Health, wiring, and dead-hook detection. Doctor runs one named check per line - the binary and its path, the license, the hook config of every agent this machine either has installed or carries a managed config for, whether each wired hook command still resolves to an executable, whether the guard mode the hook asks for (audit or enforce) is what actually runs under this binary's license, whether the wiring matches what this version of skarn writes, the guard log's freshness, the session stores it can enumerate, the guard self-test, the cache directory, and how current the detection rules are - and every warning or failure names the exact command that clears it, or the resource that explains it when no single command applies (a free binary whose bundled rules have aged has no command to run, so that one check carries the editions link instead of a fix). Each agent's hook config is read as ordered precedence layers - the MDM/fleet-managed system paths first, then the repo's committed project config in the working directory (./.claude/settings.json, ./.cursor/hooks.json, ./.codex/hooks.json, ./.github/hooks/skarn.json, ./.gemini/settings.json), then the per-user config - so a machine wired only through the managed layer reports as protected and names the managed file, and a repo carrying a committed project config is inspected wherever doctor runs; on Claude and Codex a managed lockdown key (allowManagedHooksOnly / allow_managed_hooks_only) makes every lower layer inert, and doctor reports an inert user or project hook instead of counting it as protection (Cursor and Copilot layer additively, so every present layer runs). On Claude the managed layer is the system managed-settings.json folded together with its managed-settings.d/ drop-in directory the way Claude merges them, so a machine wired only through a drop-in reports as protected and the report names the drop-in file itself; a hook found at the retired C:\ProgramData\ClaudeCode\managed-settings.json is never counted, only noted with the supported path. On Windows the managed layer also covers the HKLM and HKCU SOFTWARE\Policies\ClaudeCode registry keys that Group Policy and Intune deploy, so a fleet managed only through the registry is examined rather than skipped. Claude Code reads exactly one managed source and ignores the rest rather than merging them - an MDM/OS-level policy (the HKLM registry key, or the macOS managed-preferences plist) outranks the system managed-settings.json and its drop-ins, which in turn outrank the user-writable HKCU key - so doctor reports the losing source as inert and never counts its hooks as protection. When the winning source is one skarn cannot decode, such as the managed-preferences plist, doctor reports the coverage gap instead of a protection it cannot confirm. Two Claude managed delivery surfaces still stay outside what doctor can read, both of them above everything local: the server-managed settings delivered at sign-in from the claude.ai admin console or a self-hosted gateway, and a policyHelper executable that computes managed settings at startup. On WSL the whole Windows policy chain is out of reach of a Linux binary and outranks /etc/claude-code, so a claude check that would otherwise pass is downgraded to a warn naming that chain rather than claiming a protection skarn cannot confirm. Gemini is the one host whose managed layer is NOT read first: its own precedence is system-defaults, then user, then project, then the system settings file on top (that file has the final say), and doctor reports its layers in exactly that order; hook arrays still concatenate across all four, so every present layer runs, and what turns hooks off is not a lockdown key but hooksConfig - enabled is a single value the highest layer that sets it wins, disabled is a list of hook names unioned across every layer, and a hook either switch silences is reported inert rather than counted as protection. A committed project hook gets its own guard-command verdicts: an absolute machine-local path or an unrendered __SKARN_PATH__ placeholder FAILs (that file protects nobody but its author), a PATH-resolved command that does not resolve on this machine FAILs with the install command as the fix (the hook exits 0 here, so the repo is not protecting this machine), and Cursor at project scope WARNs naming the GUI-PATH gap - the deliberate, documented cost of a portable committed config. The license check WARNs when there is no license at all (check will not run, exit 7; assess, the guard, and the recall commands still work) and FAILs only when a license is present but broken. The eula check PASSes when an EULA acceptance is recorded (showing the accepted version, timestamp, and method) and WARNs when none is, with fix skarn eula accept - doctor itself never asks, so a diagnostic is never blocked by the acceptance gate. The guard-scope check WARNs when a hook wired with --guard-mode enforce runs on an unlicensed binary (the guard silently runs audit: it records the would-be verdict and blocks nothing). The guard-conformance check appears only when a managed layer declares a skarn hook and answers whether this machine runs what the org declared: it WARNs when the managed layer declares enforce on an unlicensed binary (the fleet is observing, not blocking), when the declared command does not resolve to an executable (the managed config alone deploys nothing - the binary must ride the same MDM payload), when a declared event is not gated, or when a hook disagrees with the declared mode; every branch is a WARN with an exact fix, never a FAIL, because a policy divergence is a fleet fact, not a broken install. The grokbot check appears only on a machine where Grok Bot is installed - xAI's always-on desktop agents app, a different product from the Grok Build CLI - and it is a warning that carries no fix, because no skarn command changes what it reports: skarn states this posture and leaves what to do about it to you. When the daemon-connection state is present the warning names the always-on local-exec daemon that lets a cloud agent execute here, and its egress tunnel when that is on; when only the app root is found it reports plain presence and claims no channel. Detecting it is stat-only over ~/.grokbot/ and the macOS app root; the one file skarn opens there is ~/.grokbot/settings.json, for its two posture flags, and it is read only once skarn has proved that path is that file and nothing else - not a link, not a hard link to a credential file, not a pipe - so no daemon or OAuth credential value can reach the report. Check ids (binary, license, eula, agent_config_<agent>, guard_command_<agent>, guard_scope_<agent>, config_drift_<agent>, guard_log_<agent>, self_test_<agent>, guard_conformance_<agent>, grokbot, session_stores, cache_dir, rule_age) are a stable, greppable contract for fleet scripts. A failure exits 1; a warning never does; --json is a data mode that always exits 0 once a report is rendered, with the two refusals that precede any check: an unknown option exits 1, and a home directory that cannot be resolved exits 6. Doctor is hermetic: it makes no network call, shells out to nothing, and enumerates the session stores without reading a session's content. Set SKARN_MANAGED_ROOT to validate a staged managed payload before pushing it; the active root is echoed in the report header and in --json, so a staged report can never pass as a live one.
Serve options
Control the localhost web UI. Access requires the per-run token embedded in the URL the command prints at startup; opening that URL sets a session cookie, and scripts may pass it as a token= query parameter instead. Every route that returns session content masks each detected secret first, and there is no opt-out: the response crosses into a browser, so the no-redact flag the recall commands honor is not a parameter here. Search masks before it runs the query, so a raw credential typed as the query returns no rows while an adjacent word returns the row with the value masked. The recent rows, the four session views, the filter facets and the by-date totals mask every label a transcript authored, which means the project name, the repository root, the working directory, the git branch, the model id and the assistant name. A facet whose displayed value the mask rewrote is marked filterable false, because sending that value back as a filter would match nothing; the UI renders it as a label with its count. Two detection scans run at a time and a further request answers 503 with redaction_busy and a Retry-After header rather than waiting, so a caller retries instead of treating the refusal as permanent; a scan that cannot start at all answers 500 with redaction_unavailable and no rows. A session whose file changes on disk while it is being read is left out of that answer rather than served unmasked, because the scan indexed the older bytes; the search stream, the recent page, the meta response and the by-date trend each report how many they left out in a skipped field (search appends it as one final line after its rows, only when a session was left out), and reloading picks the session up again. The recall views (search, recent, stats) need no license; the security view (/api/scan) is the same engine as check and requires one the same way - without it the endpoint answers 403 and the Security tab shows how to register free. Opening a finding in the Security view shows a detail drawer (severity, taxonomy crosswalk, attack-chain context, and the redacted code context) from which you can accept the finding into your baseline as a false positive - the same write path as skarn baseline accept, recording only the finding's fingerprint, never its secret. The license is resolved once at startup, so installing one while the server is running needs a restart.
Global options
Available on a bare invocation.
Recent options
List and filter recent sessions. The project, branch, model and assistant columns are masked wherever a detected secret appears in them; --no-redact prints them as recorded.
Messages options
Show one session's messages. The session is a positional id or --session; the other flags only narrow which session a prefix resolves to. Every message and every label is printed with detected secrets masked; --no-redact prints the session as recorded.
Search options
Search past sessions. The query is positional and flag order is free. The match runs on the raw text and the printed snippet is masked: when the match falls inside a masked value, the row carries the mask's offset instead, with match_in_secret set in json output and no highlight in text, and a no-result or error message names the query only under --no-redact.
Restore options
Restore a session by id. The resume command is printed from the raw session, because a masked working directory would not be a usable command: when the recorded working directory carries a detected secret, restore refuses with exit 1 and prints nothing to stdout, and --no-redact prints it as recorded. The match hint on stderr masks the project, branch and assistant name.
Stats options
Session analytics. A positional session id switches to a per-session view. Under --show timing the active-time number answers to three different key names depending on the output shape, and a reader that asks for the wrong one gets null rather than an error: a by-date or by-project row calls it active_secs, the ungrouped totals and a per-session view call it active_time_secs, and a by-date row carries a second number the other shapes do not, active_wall_secs. The two by-date numbers count differently. active_secs adds each session's own active time to the first day that session touched inside the window, so two sessions you ran side by side both count in full and a day can total more than the clock allows. active_wall_secs merges the same active intervals per calendar day, so overlapping sessions count once, which is the number to bill from. A per-session view lists its pauses under idle_gaps, keyed gap_secs and after_message. Every shape, the html report included, prints its model names, tool names and project labels with detected secrets masked; --no-redact prints them as recorded.
Export options
Export session data. Every exported field is masked by default; --no-redact exports the sessions as recorded.
Cmds options
Shell commands run across sessions. Commands, their output and the labels are printed with detected secrets masked, while --cmd and --failed match the raw text; --no-redact prints them as recorded.
Mcps options
MCP calls made across sessions. Server names, tool names and call arguments are printed with detected secrets masked, while --mcp and --failed match the raw text; --no-redact prints them as recorded.
Tools options
Tools used across sessions. Tool names, inputs and results are printed with detected secrets masked, while --tool and --failed match the raw text; --no-redact prints them as recorded.
License options
Show the active license, install one, or renew it. With no argument it reports what license this machine is using, where it came from, and when it expires. With a file argument (or - to read stdin) it validates the license and installs it to the config directory, backing up any license already there. With renew it asks the license service for a fresh license for the current subscription, verifies the reply against the signing keys built into this binary BEFORE writing a single byte, and installs it; a reply that does not verify is discarded and nothing is written. Verification is not signature-only: the reply must move the expiry forward, and must carry the same license id when both the installed and the returned license are version 2 claims, so a valid artifact belonging to another subscription is refused too. Renewal happens only when you type it - check, the recall verbs, serve, and guard never renew on their own - and it is the only network call skarn makes besides the opt-in maintained-feed fetch. The endpoint defaults to https://api.getskarn.com and is overridable with $SKARN_LICENSE_RENEW_URL; it must be https (plain http is accepted only against loopback) and carry no userinfo, so a poisoned environment cannot send the license anywhere in cleartext nor hand credentials to the endpoint. Renew exits 0 when the new license is installed; 1 when the renewal could not complete and nothing was installed (the service could not be reached, there is nothing to renew, a local target was refused, the reply was unreadable, or a verified artifact could not be written); 2 when the service declines (its reason is printed as the service worded it, after any echo of the license token is redacted, terminal control bytes are masked, and the text is capped at 300 bytes); and 3 when the reply fails verification. It never prints the license token itself, and it works without a license - and with an expired one - so it never exits 5.
Exit status
0- Clean, or informational output only.
Details, including mcp
For mcp: the client closed stdin, which is the normal shutdown.
1- A finding at or above the
--fail-on-severitythreshold was reported.Details, including setup and guard --self-test, doctor, restore, and mcp
For setup and guard
--self-test: a target was refused or a verification failed. For doctor: at least one check FAILED (a warning never exits nonzero), or an unknown option was passed, which is refused before any check runs. For restore: the recorded working directory or session id could not be rendered safely, or the working directory carries a detected secret and--no-redactwas not passed, so nothing was printed to stdout and the refusal is named on stderr. Also: the first-run EULA prompt was declined, so the invoked operation was not performed. For mcp: an unknown argument was passed, which is refused before the protocol loop starts. 2- The session risk score exceeded the
--fail-on-riskthreshold.Details, including setup
For setup: no terminal to prompt on and no
--yes; the exact non-interactive command is printed. 3- A canary token was triggered (a proven breach).
Details
This overrides every other gate.
4- A policy precondition was not met: a required rule is missing, the policy requires a baseline and none was supplied or the one supplied did not load, or the
--policyfile itself could not be read or parsed.Details
A policy that never loaded is never quietly replaced by the embedded default, which gates nothing.
5- A requested paid feature is not covered by the active license (a Team or Enterprise flag without a matching license).
Details
Refused before any scan. With no usable license at all, check exits 7 before this gate is consulted.
6- The scan could not complete:
Details, including check --audit-verify, vet, and doctor
session discovery or the scan itself failed, including a home directory that could not be resolved so no session store was ever located, or the detection rules could not be loaded so no scan was ever defined. Under
--fail-on-scan-erroran otherwise-complete run exits 6 as well whenever coverage was partial: a tool source dropped out of discovery, a session store that exists could not be read, a session's parse failed, the assistant compacted a session before the scan so its transcript no longer holds the whole conversation, or the run read no sessions at all. That verdict is computed BEFORE the report is rendered, so the SARIF invocation exit code, the evidence pack and the audit record all carry 6 rather than describing the run as clean and then exiting nonzero. A--baseline-createrun is refused on the same condition before it writes anything, so an incomplete scan is never recorded as the accepted set and the previous baseline survives. For check--audit-verify: the audit log exists but could not be read, so the hash chain was never examined (an absent log is a valid empty chain and exits 0). For vet: the home directory could not be resolved (so the configuration was never located at all), or a config file that exists was not read - it could not be read, or it was skipped because it is not that assistant's live configuration - so the configuration was only partly seen. For doctor: the home directory could not be resolved, so every per-agent check would have read an empty machine - a diagnostic that could not be produced is never reported as a healthy one. Fail-closed - the result is not trustworthy, so it is never reported as clean. 7- No usable license is present - none was found via
SKARN_LICENSE,SKARN_LICENSE_FILE, or the installed file - so check, or baseline audit, refused before scanning.Details
The free license is issued at https://getskarn.com/free after a quick email confirmation and is verified offline. Also used when a license IS present but cannot be used at all (revoked, tampered, or signed by an untrusted key). assess, baseline accept, guard accept, the recall commands, guard, setup, doctor, vet, mcp, license, taxonomies and check
--audit-verifynever exit 7.
Environment
SKARN_SCAN_THREADS- Cap the worker-pool size for every parallel sweep (scan and recall).
Details
1 forces a fully serial run. Default is one worker per core, capped at 32. Output is identical for any value; only latency changes.
SKARN_CLAUDE_DIRS- Colon-separated list of additional Claude Code config directories to scan beyond the default ~/.claude.
Details
Each entry is the dir that contains projects/. Roots are de-duplicated.
SKARN_TZ_OFFSET- Default timezone offset in hours applied when grouping recall and stats output by time.
SKARN_NO_TIMING- Suppress the dim "Scanned N sessions" timing line that recall commands print after a text run on a terminal.
Details
Already auto-suppressed for json/sarif/csv output and for non-TTY stdout.
SKARN_LICENSE_RENEW_URL- License-service endpoint
skarn license renewposts to.Details
Defaults to https://api.getskarn.com/v1/license/renew; set it to route renewals through an enterprise proxy. It must be https - plain http is accepted only against loopback - and must carry no userinfo, so a poisoned environment can neither redirect the license token to a cleartext endpoint nor hand credentials to the one it names. No other command reads it.
SKARN_GUARD_LOG- Path to append a redacted JSONL verdict log for guard (opt-in; off when unset).
Details
One record per flagged call, carrying the fingerprint that
skarn guard accepttakes; clean calls, and calls whose every finding was already accepted, are not logged. GEMINI_CLI_SYSTEM_SETTINGS_PATH- Gemini CLI's own override for the path of its managed system settings file; when set it REPLACES the default path, and Gemini also takes its system-defaults file from that path's directory.
Details
Doctor resolves both gemini managed layers through it, so the report names the files Gemini actually reads instead of default files it is not.
GEMINI_CLI_SYSTEM_DEFAULTS_PATH- Gemini CLI's own override for the path of its system-defaults file, the lowest of its four settings layers
Details
when set it REPLACES the path Gemini would otherwise derive from the system settings file's directory, and doctor reads the override.
SKARN_IDENTITY- Local-first identity tag (an SSO subject, email, or CI principal) stamped as provenance on baseline entries created with
--baseline-create.Details
Optional; Skarn never authenticates it.
SKARN_ORG- Local-first org or team tag stamped alongside
SKARN_IDENTITYon baseline provenance.Details
Optional.
SKARN_FEED_URL- Default feed channel URL used by check
--update-ruleswhen--feed-urlis not given (Team).Details
It must be https - plain http is accepted only against loopback - and must carry no userinfo, so a poisoned environment cannot redirect the subscriber credential to a cleartext endpoint.
SKARN_FEED_TOKEN- Credential presented to the subscriber feed channel when fetching a maintained feed (Team).
SKARN_EULA_ACCEPTED- Set to 1 to suppress the first-run EULA prompt and notice for this run without recording anything (ephemeral environments: containers, CI).
Details
Running Skarn constitutes acceptance either way;
skarn eula acceptrecords it durably instead. SKARN_LICENSE- License token, resolved before
SKARN_LICENSE_FILEand the config path. SKARN_LICENSE_FILE- Path to a file containing a license token.
CLAUDE_CONFIG_DIR- A Claude Code config directory visible in Skarn's environment; folded into the claude source like an
SKARN_CLAUDE_DIRSentry. COPILOT_HOME- GitHub Copilot CLI config directory visible in Skarn's environment.
Details
The CLI itself treats it as REPLACING ~/.copilot, and vet follows that: it reads mcp-config.json, config.json and settings.json from the directory this names and not from the default. Scanning deliberately diverges - the copilot source scans this root AND the default ~/.copilot, because a scanner's subject is every local store and sessions stranded in an abandoned default root still hold the secrets they held the day they were written. A store present under both roots is two real files, and both are read: either may hold a secret the other lost. Microsoft Scout sets this variable to ~/.scout/copilot in the environment of the Copilot CLI child process it spawns, not in the user's shell, so Skarn's own process never sees it; that root is therefore declared in the scanner rather than read from here, exactly as
$CODEX_HOMEand$KIMI_CODE_HOMEare declared rather than guessed. GROK_HOME- Grok Build config directory visible in Skarn's environment; replaces the default ~/.grok as grok's home.
Details
Setup writes its hook file under the directory this names, doctor resolves grok's config, requirements, hooks, and folder-trust files from it, and the guard's own behavior does not depend on it.
GROK_FOLDER_TRUST- Grok Build's folder-trust switch.
Details
Set to 0 it ungates every project-scope hook, MCP server, and LSP server, the same as [folder_trust] enabled = false in grok's config; doctor honors it, so a machine that turned the gate off is not reported as having a silenced project hook layer.
KIMI_CODE_HOME- A Kimi Code CLI data directory visible in Skarn's environment; replaces the default ~/.kimi-code as the kimi root, folded into the kimi source, de-duplicated, resolved via expandPath.
Details
Each root contributes its sessions/ and user-history/ children.
GROK_HOME- A Grok Build data directory visible in Skarn's environment; grok itself REPLACES ~/.grok with
$GROK_HOMErather than layering.Details
Skarn folds both roots, de-duplicated, resolved via expandPath, and accepts each only when it has a sessions/ child.
CODEX_HOME- A Codex CLI data directory visible in Skarn's environment; folded into the codex source alongside the default ~/.codex, de-duplicated, resolved via expandPath.
Details
Each root contributes its sessions/ and archived_sessions/ children.
SKARN_MANAGED_ROOT- Prefix prepended to every managed (MDM/fleet) config path skarn reads, so a fleet admin can validate a staged payload directory before pushing it to a single machine (
SKARN_MANAGED_ROOT=/tmp/stageskarn doctor).Details
Empty or unset means the live system paths. Doctor applies it to every managed hook config it inspects, and vet applies it to the system Grok Build layers it reads at /etc/grok. Whenever it is active, doctor echoes the root in the report header and emits it as managed_root in
--json, so a staged report can never pass as a report about the live machine. It is a filesystem prefix and cannot re-root a registry key;SKARN_MANAGED_REGISTRY_ROOTdoes that. SKARN_MANAGED_REGISTRY_ROOT- Registry key doctor reads the Windows managed policy keys under, so an administrator can validate a staged payload without touching live Group Policy
Details
(
SKARN_MANAGED_REGISTRY_ROOT='HKCU\Software\SkarnStage'skarn doctorreads HKCU\Software\SkarnStage\HKLM\SOFTWARE\Policies\ClaudeCode). The hive stays a key component under the staging root, so the HKLM and HKCU policies stage to distinct keys instead of collapsing into one. Empty or unset means the live policy keys. Whenever it is active, doctor echoes it in the report header and emits it as managed_registry_root in--json, so a staged report can never pass as a report about the live machine. Only doctor reads it. GROK_HOME- Grok Build's data and configuration directory, default ~/.grok.
Details
It relocates the whole Grok home surface that vet reads - config.toml, managed_config.toml, requirements.toml, the hooks/ directory, and the hooks-paths registry - so a relocated Grok home is examined rather than reported clean over an unexamined one.
XDG_CACHE_HOME- Base directory for the rule and feed cache.
Details
Defaults to ~/.cache, so the cache lives in ~/.cache/skarn/.
Files
/Library/Application Support/ClaudeCode/managed-settings.json, /etc/claude-code/managed-settings.json, C:\Program Files\ClaudeCode\managed-settings.json- Claude Code's MDM-managed settings (macOS, Linux/WSL, Windows).
Details
Doctor reads the platform's path as the claude host's managed precedence layer; allowManagedHooksOnly: true there makes every lower layer inert. Read-only; never written.
/Library/Application Support/ClaudeCode/managed-settings.d/*.json, /etc/claude-code/managed-settings.d/*.json, C:\Program Files\ClaudeCode\managed-settings.d\*.json- Claude Code's managed-settings drop-in directories (macOS, Linux/WSL, Windows), where separate teams deploy policy fragments without editing one shared file.
Details
Doctor folds a drop-in directory into the SAME managed layer as its sibling managed-settings.json, in the order Claude merges them: the base file first, then every *.json in the directory sorted by name, wired hooks unioned and de-duplicated on the event and the exact command, and allowManagedHooksOnly taken from the last file that sets it (a file that omits the key changes nothing, a file that sets it to false unlocks an earlier true). Files whose name begins with a dot are ignored, as Claude ignores them. Read-only; never written.
C:\ProgramData\ClaudeCode\managed-settings.json- Claude Code's retired Windows managed-settings path.
Details
Claude Code no longer reads it, so doctor never counts a hook found there as protection: when the file is present the report carries a note naming the supported path (C:\Program Files\ClaudeCode\managed-settings.json), and when it is absent it is silent. Read-only; never written.
HKLM\SOFTWARE\Policies\ClaudeCode, HKCU\SOFTWARE\Policies\ClaudeCode- Claude Code's Windows registry policy keys (a Settings value of type REG_SZ or REG_EXPAND_SZ holding the same JSON), deployed through Group Policy or Intune.
Details
Doctor reads both as claude's managed precedence layer, so a fleet managed entirely through Group Policy or Intune is examined and reported rather than skipped, and finding one is enough to examine the host even where Claude Code itself is not installed. A REG_EXPAND_SZ value is read verbatim without environment expansion, because doctor reports what is configured rather than what it resolves to on this machine. Claude Code reads exactly ONE managed source and ignores the rest rather than merging them, so HKLM outranks the system managed-settings.json and its drop-ins, which in turn outrank the user-writable HKCU key; doctor reports the loser as inert and never counts its hooks as protection. A key that exists but whose Settings value cannot be read or is not a string type is a coverage gap with a reg query command, never a silent absent. On WSL, Claude Code reads the Windows policy chain in addition to /etc/claude-code and gives the Windows sources priority (wslInheritsWindowsSettings, default true), and a Linux skarn binary cannot reach the registry from there; rather than report a protection a Windows-side allowManagedHooksOnly may already have silenced, doctor downgrades what would have been a claude pass to a warn naming that unread chain, with /status inside Claude Code as the way to see which source won. Read-only; never written.
server-managed settings (claude.ai admin console or a self-hosted Claude apps gateway)- Claude Code's remotely delivered managed settings, fetched at sign-in with no local file on the machine, and the policyHelper executable that can compute managed settings at startup.
Details
Both outrank every local managed source and, because Claude Code reads only its highest-precedence managed source, both silence the file and registry policies doctor can read. Doctor cannot read either, so a fleet whose hooks arrive only through one of them sees its machines report as unwired. Declared here so the set of managed delivery surfaces is complete. Confirm the winning source on a machine with /status inside Claude Code, which names the delivery channel it loaded.
/Library/Managed Preferences/com.anthropic.claudecode.plist- Claude Code's macOS managed-preferences domain, and the macOS half of the same MDM/OS-level policy tier the Windows HKLM registry key occupies.
Details
Declared as a managed source but not decoded; when present, doctor surfaces it as a coverage gap with a plutil command to inspect it, never as a silent absent. Because that tier outranks the file-delivered policy and Claude Code reads only its highest-precedence managed source, a present plist also stops doctor from counting the hooks in managed-settings.json and its drop-ins: those hooks genuinely never run, and the report names the coverage gap instead of a protection it cannot confirm.
/etc/codex/requirements.toml, %ProgramData%\OpenAI\Codex\requirements.toml- Codex's admin-managed requirements file (Unix, Windows).
Details
Doctor reads it as the codex host's managed precedence layer via a scoped reader (allow_managed_hooks_only and the [[hooks.<Event>.hooks]] command strings); allow_managed_hooks_only = true makes every lower layer inert. Read-only; never written.
/Library/Managed Preferences/com.openai.codex.plist- Codex's macOS managed-preferences domain.
Details
Doctor decodes the XML form (requirements_toml_base64 and config_toml_base64, base64 to the same scoped reader; the lockdown key is honored only from the requirements payload, matching Codex); a binary plist is surfaced as present-but-unreadable with the exact plutil conversion command, never as a silent absent.
/Library/Application Support/Cursor/hooks.json, /etc/cursor/hooks.json, C:\ProgramData\Cursor\hooks.json- Cursor's enterprise-managed hooks (macOS, Linux/WSL, Windows).
Details
Doctor reads the platform's path as the cursor host's managed precedence layer; Cursor layers additively (no lockdown key), so every present layer stays active. Read-only; never written.
/etc/github-copilot/policy.d/*.json, C:\ProgramData\GitHub\Copilot\policy.d\*.json- Copilot's managed policy directory (Linux/macOS, Windows).
Details
Doctor folds every *.json in the directory into the copilot host's managed precedence layer, sorted by name; Copilot layers additively. Read-only; never written.
/Library/Application Support/GeminiCli/system-defaults.json, /etc/gemini-cli/system-defaults.json, C:\ProgramData\gemini-cli\system-defaults.json- Gemini CLI's managed system-defaults file, the LOWEST of its four settings layers.
Details
Read by doctor. Gemini derives this path from the system settings file's directory, so
$GEMINI_CLI_SYSTEM_SETTINGS_PATHmoves it too, and$GEMINI_CLI_SYSTEM_DEFAULTS_PATHreplaces it outright; doctor reads whichever path wins. Hook arrays concatenate across layers, so hooks declared here run alongside the user and project ones rather than replacing them. /Library/Application Support/GeminiCli/settings.json, /etc/gemini-cli/settings.json, C:\ProgramData\gemini-cli\settings.json- Gemini CLI's managed system settings file, the HIGHEST of its four settings layers - it has the final say on single-valued settings such as hooksConfig.enabled.
Details
Read by doctor.
$GEMINI_CLI_SYSTEM_SETTINGS_PATHreplaces this path, and doctor reads whichever path wins; hook arrays still concatenate across every layer. ./.claude/settings.local.json- Claude Code's personal, gitignored project settings file.
Details
Claude merges hooks across every settings file and runs all of them, so a guard wired here protects this checkout and doctor reads it as part of the project layer.
skarn setupnever writes it: it writes only the committed ./.claude/settings.json. ./.claude/settings.json, ./.cursor/hooks.json, ./.codex/hooks.json, ./.github/hooks/skarn.json, ./.gemini/settings.json- A repo's committed project-scope hook configs (claude, cursor, codex, copilot, gemini)
Details
written by
skarn setup --scopeproject and read by doctor as each host's project precedence layer whenever it runs in that directory. Portable by construction: the committed command resolves skarn from PATH at run time and exits 0 where skarn is not installed. Gemini reads one command field on every platform, so its committed POSIX command fails open on a native-Windows teammate; Gemini also runs hooks from a project file only once that folder is trusted. ./.github/copilot/settings.json, ./.github/copilot/settings.local.json, ~/.copilot/settings.json- The repository's Copilot CLI settings.
Details
Doctor reads one key from them, the top-level disableAllHooks: setting it true makes the CLI skip the user- and repository-delivered hooks for that repository, the operator's own user-scope hook included, and the CLI logs nothing when it does - so the state is knowable only by reading the file. The settings.local.json sibling takes precedence over settings.json, the CLI reads the same key from the shared cross-tool ./.claude/settings.json and ./.claude/settings.local.json, and the operator's own ~/.copilot/settings.json (honoring
$COPILOT_HOME) carries it too, outranked by whatever the repository says. Doctor resolves the repository scope first and consults the user file only when no repository file spoke; nothing documents which of the two repository families wins when they disagree, so it honors a true from either - reporting a live hook as silenced is a false alarm the named file settles, reporting a silenced hook as protection is not. Comments are tolerated on a retry, since the CLI documents JSONC for its settings. When the switch is on, doctor reports the user and project hook layers as inert instead of counting them as protection, and reports a managed policy layer with a note rather than as either: it does not stop a host application's own in-process hooks, which arrive through the SDK rather than from a file, and machine policy hooks kept running under it on CLI 1.0.82, the one version measured (GitHub documents them as exempt). The switch takes effect only once the CLI trusts the folder: on 1.0.82 an untrusted repository carrying the switch still ran the user hook, and doctor reads the switch but not the CLI's trustedFolders list, so in an untrusted folder it can call a user hook inert that the CLI still runs. Read-only; never written. ~/.grokbot/- Grok Bot's local-exec daemon state: the daemon connection and credential files, its settings.json, and its rolling daemon log.
Details
Doctor detects this directory and the daemon-connection file beside it by stat alone, each one only when the path is of the kind its name implies, and reads exactly one body here, settings.json, for the egressTunnelEnabled and webauthnProxyEnabled posture flags, and only once the open handle itself proves the path is that file and nothing else, so a symlink, a hard link to a credential file, or a pipe left at that name is refused unread. The connection and credential files hold a gateway bearer token, a network token and VNC proxy tokens; skarn never opens them, so no value from them can reach the report. Presence is reported as a warning with no fix, because no skarn command changes it and what to do about an installed app is the operator's decision. Read-only; never written.
~/Library/Application Support/Grok Bot/ (macOS)- Grok Bot's desktop app root.
Details
Doctor detects the directory and its sand-secrets.json and sand-client-persistence markers by stat alone and reads no body here at all; the transcript replicas under sand-client-persistence are scanned by the session commands, not by doctor, and the token store is never opened by either. The probe is macOS-only, the platform where the app root is observed; ~/.grokbot/ is checked on every platform. Read-only; never written.
~/.skarn.json- Optional tool configuration: the set of assistant tools and their session paths, plus an optional projects alias map.
Details
Both the recall surface and scan discovery (check, assess, baseline audit, the guard's stop advisory, and serve's Security scan) read it, so the security scan and the recall views cover the same corpus. Falls back to a builtin tool set when absent. The projects object renames a resolved project for display: a key beginning ~, $, or / is a path prefix (with ~ and a leading $VAR expanded like sessions_path) matched against the canonical project root on whole path components, longest match winning (so /repo never matches /repository); any other key matches the derived display name case-insensitively; the value is the shown name. Aliases change display only, never the grouping key.
~/.cache/skarn/- Cache for downloaded rule and maintained-feed bundles.
Details
Honors
$XDG_CACHE_HOME. ~/.config/skarn/baseline.json- The personal accepted-findings baseline, applied automatically when it exists: check, assess, and serve suppress its findings, and guard stops flagging them.
Details
Written by
skarn baseline audit/acceptandskarn guard accept. Honors $XDG_CONFIG_HOME. Holds fingerprints and hashes, never a raw secret; treat it as sensitive. ~/.config/skarn/eula-accepted.json- The EULA acceptance record: the agreement version accepted, an RFC-3339 timestamp, and the method (prompt, command, env, license-install).
Details
Written when acceptance is given at the first-run prompt, by
skarn eula accept, or by installing a License Token; never transmitted. Honors $XDG_CONFIG_HOME. ~/.claude/- Default Claude Code session root.
Details
Scanned automatically; extend with
$SKARN_CLAUDE_DIRSor$CLAUDE_CONFIG_DIR. ~/.kimi-code/sessions/- Default Kimi Code CLI session root.
Details
One wire.jsonl per agent under sessions/<workdir-key>/<session-id>/agents/<agent>/; the main conversation and every sub-agent stream are scanned as separate sessions. Relocate with
$KIMI_CODE_HOME. The legacy python kimi-cli root ~/.kimi/ stores a different session layout and is not scanned;kimi migrateconverts it. ~/.kimi-code/user-history/- Kimi Code CLI's per-working-directory prompt log, one file per workdir.
Details
Scanned in addition to the session tree because it retains prompts from sessions that were aborted before any session record was written. Relocate with
$KIMI_CODE_HOME. ~/.local/share/opencode/opencode*.db- OpenCode's SQLite session store, since v1.2.0.
Details
The filename carries the release channel, so a non-stable channel writes opencode-<channel>.db beside it and every matching file in the directory is read. Relocate the whole data root with $XDG_DATA_HOME, which OpenCode honours on macOS and Windows too - it uses the XDG path on every platform, not Application Support or %APPDATA%. The store is WAL-mode and OpenCode holds it open while running, so skarn reads it read-only inside one transaction and never writes to it; a store it cannot read is reported as an incomplete scan rather than counted clean.
~/.local/share/opencode/storage/- OpenCode's pre-v1.2 session tree, one JSON record per session, message and part.
Details
Upgrading to the SQLite store neither imports nor deletes it, so sessions written before v1.2 live only here and both layouts are scanned. A session id present in both is reported once, preferring the database copy.
~/.grok/sessions/- Default Grok Build session root.
Details
One transcript per session at sessions/<url-encoded-cwd>/<session-id>/chat_history.jsonl, with a summary.json sidecar beside it read for the session id, branch, timestamps, model, and title, and for the working directory when the path yields none. The session title is scanned like any other session text. The recorded working directory is re-derived from the group directory name, or from its .cwd file when the encoded path exceeds 255 bytes, and a recorded directory always wins over the sidecar's copy. Relocate with
$GROK_HOME. updates.jsonl, rewind_points.jsonl, events.jsonl, and session_search.sqlite are deliberately not scanned. One more sidecar, signals.json, is read for two counters only, compactionCount and totalTokensBeforeCompaction, and so is a non-empty compaction_checkpoints or compaction directory beside the transcript: Grok rewrites the transcript when it compacts a session, dropping turns from the only file Skarn reads, so a session either signal reports as compacted is counted as incomplete coverage and named in the scan-incomplete warning. The two signals are independent, not a fallback chain, and either alone is enough - a saved checkpoint means the compaction happened whatever a sidecar written at some other moment says, since under-reporting a coverage gap is the failure this counter exists to prevent. An empty checkpoint directory counts for nothing, and neither does a sidecar that is missing, unreadable, or malformed; the counter is raised only by a positive signal, never by the absence of one. No session content is taken from either. ~/.grok/sessions/<url-encoded-cwd>/prompt_history.jsonl- Grok Build's per-working-directory prompt log, one file beside the session directories of that working directory.
Details
Each record carries a session id, so one file holds prompts from many sessions and each id is scanned as its own session. It is read in addition to the transcripts because it outlives them: a removed, pruned, or partially copied session directory takes its transcript and leaves its prompts, text cleared before it was sent is saved here and reaches no transcript at all, a shell prompt entered with a leading ! is recorded here as the bare command it ran, without the !, while the transcript keeps only a rendered narration of it, and a torn transcript still leaves the prompt. It is not a record of prompts written ahead of the transcript: the transcript is written first. A prompt the session transcript already carries is dropped at scan time, matched on the exact text within the same working directory and session id, so it is reported once; a session whose every prompt the transcript carries does not appear at all. Shell prompts additionally surface in
skarn cmds. Relocate with$GROK_HOME. ~/Library/Application Support/Grok Bot/sand-client-persistence/ (macOS), ~/.config/Grok Bot/sand-client-persistence/ (Linux), the same directory under %APPDATA% (Windows)- Grok Bot's local chat-transcript store.
Details
Grok Bot is xAI's always-on desktop agents app, a different product from the Grok Build CLI above, and it keeps a cleartext replica of every agent's conversation here, so a credential pasted into a Grok Bot chat lands on disk in this directory. One .blob per persistence slice, each filename the base32 (RFC 4648, unpadded lowercase) encoding of a dotted slice name; Skarn decodes the name and scans only a sand.client.slice.account.<account>.transcript.replicas.<agent-id> slice, so the drafts, roster, send-journal, selection, sidebar and client-meta slices beside it are excluded by construction. One replica is one session, identified by the decoded agent id; two blobs decoding to the same agent id are reported once. A .blob whose filename does not decode is counted once per store as incomplete coverage, so it raises the unreadable-store count in the scan-incomplete warning rather than being passed over as if the store were fully read; the warning carries that count, not the offending filename. A document whose value object is missing, is not an object, or holds an entries member that is not an array is reported unreadable rather than as an empty session; an absent entries member reads as an empty replica only at the schema version Skarn was verified against, so a truncated envelope or a later schema that renamed the collection is reported unreadable too, as is a non-empty entries array in which no entry declares a kind Skarn knows; an entries array is otherwise read whatever version the document declares, and recognized entries that carry no text of their own still make a valid session. On Linux the store list also folds $XDG_CONFIG_HOME, where Electron places userData when that variable is set, and an agent replicated into both roots is still reported once. Inside the document, whatever carries a content string is read - an agent turn at message.content and a chat message at content, both stamped in epoch milliseconds - whatever type the entry declares, so a body type a later Grok Bot release introduces is scanned rather than skipped; the widget, attachment and approval bodies observed keep their payload under other keys and so contribute no text. No entry records a working directory, so a Grok Bot session has no project and is left out of project grouping rather than named after the directory it sits in. The app names no data-directory variable, so there is nothing to relocate the store with. Grok Bot's other local files are deliberately not read: its OAuth token store, its local-exec daemon state under ~/.grokbot/, the Electron cookie stores, and its crash and memory telemetry.
~/.copilot/session-state/, ~/.scout/copilot/session-state/- GitHub Copilot CLI session roots, one events.jsonl per session under <root>/session-state/<id>/.
Details
Both are scanned automatically, each only when it has a session-state child, and
$COPILOT_HOMEadds another when it names a distinct root. The second root is Microsoft Scout's: Scout spawns the Copilot CLI it bundles withCOPILOT_HOME=~/.scout/copilot, so that CLI writes its transcript there in the clear, in the same format as the standalone CLI. What Skarn reads is that transcript. Discovery under ~/.scout goes to that one location and nowhere else: the root directory is never enumerated, so Scout's own encrypted session index (~/.scout/m-sessions/sessions-index.json) and every other m- file are outside what discovery reaches, and nothing is decrypted. Naming a project for the session afterwards uses the same resolver every source uses, on two inputs: a workspace.json probed three directories above the transcript, which neither the Copilot CLI nor Scout writes, and the cwd the transcript itself names, with a .git pointer stat'd beside it. No session content is read from either. Verified against Scout 0.23.331, 2026-07-30. ~/.claude/settings.json, ~/.claude/settings.local.json, ./.claude/settings.json, ./.claude/settings.local.json- Claude Code hooks and permission grants.
Details
Read, never written. The project-local pair is read at the current working directory only.
~/.claude.json, ~/.mcp.json, ./.mcp.json- Claude Code MCP server definitions.
Details
Read, never written. The project-local file is read at the current working directory only.
~/.claude/plugins/, ~/.claude/skills/- Installed Claude Code plugins and skills.
Details
Vet reads each plugin.json and skill.json manifest for its install source and integrity marker.
~/.codex/sessions/, ~/.codex/archived_sessions/- Default Codex CLI session roots, scanned automatically and extendable with
$CODEX_HOME.Details
zstd-compressed rollouts (rollout-*.jsonl.zst, written for rollouts older than 7 days) are read transparently through the same reader as plain ones; when both a plain rollout and its .zst twin exist the plain one is preferred. Only rollout-* files are parsed as sessions, so session_index.jsonl is never scanned.
~/.codex/config.toml, ~/.codex/hooks.json- Codex CLI MCP server definitions and hooks.
Details
Read by vet through a scoped reader that keeps only the launcher command, its arguments, and the endpoint url.
~/.cursor/mcp.json, ~/.cursor/hooks.json- Cursor MCP server definitions and hooks.
Details
Read by vet.
~/.copilot/mcp-config.json, ~/.copilot/config.json, ~/.copilot/settings.json- Copilot CLI MCP server definitions, application state, and user settings, all resolved under
$COPILOT_HOMEwhen it is set, which replaces the default root rather than layering over it.Details
A declared root holding no Copilot store reads exactly as an absent default one does: installation is decided by a config file that was actually read or by the session-state and hooks markers under whichever root is in force, never by the root's own existence. Read by vet. From settings.json vet resolves whether CLI sessions are exported to GitHub. remoteExport: false is the opt-out GitHub documents as the way to stop session syncing, remoteSessions: true forces export back on regardless of it, and the documented default with neither set is sync on. remote is recorded as a contributing key but never decides, and GitHub documents it two ways that do not agree: the settings table says off keeps session data local only, while the page on session syncing names remoteExport as the opt-out and does not mention remote at all. Skarn resolves that conflict in the direction where being wrong is recoverable. A config carrying only remote: off is reported as exporting, and the finding lists every key that was set, so a reader who has decided the settings table is authoritative can see exactly what skarn read and dismiss it. The opposite resolution would report a machine as local-only on a reading the syncing page contradicts, and a scanner that says nothing is a scanner nobody can correct. Where no settings.json exists at all - the state a fresh install is in, since neither the CLI nor its
--no-remote-exportflag writes one - the documented default is reported against the path the file would occupy, so an untouched machine is not mistaken for an opted-out one. Comments are tolerated, since GitHub documents JSONC for this file and the CLI writes a comment header into config.json beside it. Read-only; never written. ~/.scout/m-settings.json- Microsoft Scout's permission grants, auto-approve settings, and experiment flags.
Details
Read by vet. The path has no platform branch: Scout resolves its config root to ~/.scout on macOS and Windows alike.
~/.scout/m-mcp-servers.json- Microsoft Scout MCP server definitions.
Details
Read by vet. A user-added server nests its launcher or endpoint under a config object; a built-in server has none, because Scout generates its command at run time.
~/.copilot/data.db- The Copilot CLI's SQLite state store, which holds the signed-in GitHub account's access token and any bring-your-own-key provider headers alongside projects, workflows and review comments.
Details
Vet reads this file's POSIX mode by a non-following stat and never opens it: no byte of its contents is read, the database is never opened as a database, so no token and no header value can reach a finding and the only thing reported is whether the mode grants group or other read; a symlinked store is reported as a coverage gap rather than measured through its target, and a store whose owner-read bit is off is still measured. Its presence marks ~/.copilot as a live Copilot CLI install for the Microsoft Scout residue rule, the same way session-state/ and hooks/ do, so the row is never skipped as residue. Never a scan source: the session commands do not read it.
~/Library/Application Support/Grok Bot/sand-secrets.json- Grok Bot's plaintext third-party credential store, on macOS.
Details
Grok Bot is xAI's always-on desktop agents app, a different product from the Grok Build CLI. Vet reads this file's POSIX mode by a non-following stat and never opens it: not one byte of its contents is read and the store is never parsed, so no key name and no value from it can reach a finding and the only thing reported is whether the mode grants group or other read; a symlinked store is reported as a coverage gap rather than measured through its target. The path carries no platform branch, so the store is vetted on macOS only; the Linux and Windows locations are not read.
~/.grokbot/settings.json- Grok Bot's local-exec daemon settings.
Details
Vet reads two declared posture flags from this file, egressTunnelEnabled and webauthnProxyEnabled, and records only whether each is present and true. A flag that is absent or false raises nothing, so a default install stays silent.
~/.grokbot/local-exec-daemon-connection.json- Grok Bot's local-exec daemon connection state: the gateway base URL and the bearer, network and VNC proxy tokens the cloud side uses to execute on this machine.
Details
Vet treats the file as a presence signal and never parses it, so the gateway URL and every token stay out of the process as well as out of every output format. Its presence declares that the channel is configured, not that a daemon is running.
~/.gemini/settings.json- Gemini CLI's user settings: MCP server definitions read by vet, and the hooks object
skarn setup --agentgemini merges the guard into and doctor reads as the user precedence layer. ~/.grok/hooks/skarn.json- Grok Build's user hook file for skarn, written whole by
skarn setup --agentgrok and read by doctor as the setup-owned half of grok's user layer.Details
Grok loads every *.json in ~/.grok/hooks, so skarn owns a file of its own there and never merges into a foreign one; doctor folds the directory's other files into the same layer, so a hook wired by hand under another name still counts.
$GROK_HOMEmoves the whole directory. .grok/hooks/skarn.json- Grok Build's project hook file for skarn, written by
skarn setup --agentgrok--scopeproject and meant to be committed.Details
Grok runs a project hook only after the folder is trusted (/hooks-trust, or launching with
--trust); until then it skips the file silently, so doctor reports that layer as inert rather than as protection. ~/.grok/trusted_folders.toml- Grok Build's folder-trust store, the single gate for whether a repository's own hooks, MCP servers, and LSP servers run.
Details
Doctor reads it to decide whether a project hook layer counts: a grant covers its folder and cascades to subdirectories, the nearest recorded folder wins (so an explicit untrust beats an ancestor's grant), and an over-broad key naming the filesystem root or the home directory is ignored the way grok ignores it. A store skarn cannot read or parse is reported as a coverage gap, never as an absent grant. Read-only; never written.
/etc/grok/managed_config.toml, ~/.grok/managed_config.toml- Grok Build's organization-distributed config, root-owned at the system path and server-synced at the user path.
Details
Doctor reads the [[hooks.<Event>]] groups through a scoped reader that takes both documented handler notations (an inline-table array and the nested [[hooks.<Event>.hooks]] form) and reports them as managed precedence layers. Grok has no managed-only lockdown key, so these layers add hooks and never silence the others. The system path exists on Unix only; grok resolves no system config directory on Windows. Read-only; never written.
/etc/grok/requirements.toml, ~/.grok/requirements.toml- Grok Build's requirements layer, the highest-authority config tier an organization distributes.
Details
Doctor reads its hooks with the same scoped reader as managed_config.toml and reports them as managed layers, which is what makes a skarn hook declared there visible to the fleet conformance check. The system path exists on Unix only. Read-only; never written.
~/.grok/config.toml- Grok Build's user config.
Details
Doctor reads two things from it: the [[hooks.<Event>]] groups a user can declare there instead of in a hook file, and [folder_trust] enabled, which when false ungates every project hook (as does
GROK_FOLDER_TRUST=0) and so decides whether an untrusted project layer is reported inert at all. Read-only; never written. ~/.grok/config.toml, ~/.grok/managed_config.toml, ~/.grok/requirements.toml- Grok Build's user, managed, and requirements configuration layers.
Details
Read by vet through a scoped TOML reader that collects MCP server launchers and endpoints, the variable NAMES (never the values) of an MCP env table, the [ui] permission_mode and yolo settings, allow-action [permission] rules in both the compact string-array and the structured rules forms, hook handlers in both TOML notations, and [[ui.notifications.hooks]] commands. Relocate the whole directory with
$GROK_HOME. Syntax the reader does not model, such as a multiline string, is reported as a coverage gap naming the file and line rather than skipped silently. /etc/grok/managed_config.toml, /etc/grok/requirements.toml- Grok Build's system-wide managed and requirements layers, deployed by an organization.
Details
Read by vet exactly as the user layers are;
SKARN_MANAGED_ROOTprefixes both paths, so a staged payload can be vetted before it reaches a machine. ~/.grok/hooks/, ~/.grok/hooks-paths- Grok Build's global JSON hook directory and the registry file naming extra hook sources.
Details
Vet reads the .json files one level down in the directory, regular files only, and loads each ABSOLUTE line of the registry as a further hook source; relative lines are ignored the way Grok ignores them, and a UNC or //host/share target is recorded as a coverage gap and never opened. Both are bounded per directory and per registry, and exceeding a bound is reported rather than silently truncated.
./.grok/config.toml, ./.grok/hooks/- Grok Build's project-scoped configuration and hook directory, contributing MCP servers, plugins, and permission rules.
Details
Vet reads them at the current working directory only, while Grok itself discovers a .grok/config.toml at every level from the repository root down. Project hooks are collected whatever the folder-trust state, because a declared hook becomes live the moment the folder is trusted, with no configuration change.
Guard hook hosts
The hook events skarn guard receives on each supported host, what each event lets the guard scan, and the decision channel it answers on. Events marked opt-in are supported but not wired by the shipped configs.
Claude Code
Claude Code fires PascalCase events with a JSON envelope on stdin. Five events are wired by default; the two output-scanning events are supported but opt-in because they fire on every tool result.
Events and routing
Codex shares Claude's PreToolUse and PermissionRequest names, so auto-detection keys on a Codex-only tell (turn_id, or the apply_patch/spawn_agent tools); a Claude event carries none of them and routes to the Claude adapter. VS Code Copilot also shares the envelope, so its own tool-name vocabulary routes it to the Copilot adapter. The shipped Claude PermissionRequest hooks pass --agent claude explicitly anyway.
A non-zero guard exit fails closed on the blocking events. An unparseable event asks in enforce mode.
Cursor
Cursor fires camelCase events, each with its own stdin shape and its own verdict schema - unlike Claude's single envelope. All four blocking events are wired by default.
Events and routing
The camelCase event names are unique to Cursor, so auto-detection is unambiguous.
Fail-open by default; --strict plus enforce exits 2 (Cursor's schema-agnostic hard block) on an unparseable event.
Codex CLI
Codex's hook system mirrors Claude's - PascalCase events and a near-identical PreToolUse JSON - but its verdict semantics differ: permissionDecision ask and a bare allow both FAIL OPEN, so a would-be ask degrades to deny. Codex fires more events than Skarn wires; the rest are evaluated and deliberately left off the matrix (verified against the OpenAI Hooks guide, 2026-08-30): SessionStart and SubagentStart carry only session and subagent metadata (model, permission_mode, agent_id/type), no credential-bearing tool or prompt content; PreCompact and PostCompact carry only a compaction trigger over already-seen transcript the recall scan covers; SubagentStop carries last_assistant_message (so it is NOT content-free), but that post-hoc subagent output lands in the session store the recall scan and the turn-end advisory already cover, so it is a deliberate deferral pending the cross-action daemon the codex README names. SessionEnd, which the previous sweep recorded as absent and the reference now documents, carries a session id, a transcript path where one exists, and a reason (always other); it fires on archive, on deletion, on a normal close, and after 30 minutes idle, so it reaches a lifecycle moment the turn-scoped Stop row cannot - a codex session that ends without another turn produces no Stop, and if the shared hourly advisory budget was spent on the other host in the meantime that session's nudge is simply lost. It stays unwired anyway: its output is advisory and cannot steer Codex, so the nudge has no committed surface there, and Codex runs it synchronously under a 1-second default timeout capped at 3 seconds, which the recent-session scan can exceed on a large store. The gap is recorded rather than closed.
Events and routing
Codex shares Claude's event names, so pass --agent codex explicitly. Auto-detection falls back to a Codex-only tell: turn_id (on every turn-scoped event, PermissionRequest included) or the apply_patch/spawn_agent tools.
Fail-open by default; --strict plus enforce emits an explicit deny JSON on an unparseable event.
GitHub Copilot CLI
The Copilot CLI's native payload is camelCase (toolName / toolArgs / sessionId) and carries no event-name field on most events, so the event is inferred from the field shape; permissionRequest is the exception: on CLI 1.0.82 its payload names itself with hookName and carries the arguments as toolInput rather than toolArgs (measured live 2026-08-30), the guard reads both keys, and the shipped config entry still pins it with --event permissionRequest so an older CLI that sends the preToolUse shape there is answered in the right schema. preToolUse and permissionRequest both block; the other events run full detection and write the audit log but cannot decide. GitHub documents fourteen Copilot CLI hook events; Skarn declares five of them (preToolUse, permissionRequest, userPromptSubmitted, userPromptTransformed, postToolUse) plus preMcpToolCall, and evaluates the rest as deliberately not wired (verified against the GitHub hooks reference, 2026-08-30): sessionStart carries an initialPrompt (scannable), but a session-open detection arm beyond userPromptTransformed is out of this round's scope; subagentStart and subagentStop carry subagent metadata (agentName, transcriptPath), and the subagent's own tool calls are gated by preToolUse while any post-hoc output lands in the session store the recall scan covers; postToolUseFailure carries the failed call's toolArgs plus its error text, which can hold output preToolUse never saw, so leaving it unwired is a deliberate coverage deferral of the same class as the opt-in postToolUse output scan; errorOccurred and notification carry human-readable error and message text (a low-value surface deferred this round, not a claim they can never carry a secret); preCompact carries a compaction trigger and any customInstructions over already-seen transcript; agentStop (Stop) and sessionEnd carry only a stopReason/reason over transcript the recall scan covers. Every one of these is a deliberate coverage deferral, not an assertion that the event can never carry a credential.
Events and routing
The camelCase field set is the CLI tell. A Copilot payload in Claude-compat mode is byte-indistinguishable from a real Claude event (field names AND tool names), so the shipped Copilot configs always pass --agent copilot explicitly. The CLI loads hooks from policy, then the user, then the repository (its hook files and its inline settings block), then plugins (GitHub hooks reference, 2026-08-30), and how several hooks for one event compose differs by event. On preToolUse any hook returning deny blocks the tool, so a Skarn deny there is final; measured on CLI 1.0.70 the entries after the denying one did not run at all, and on 1.0.61 under SDK 1.0.1 the host's own SDK-registered callback was never invoked for that call either. On permissionRequest every configured hook runs and their outputs are MERGED with later outputs overriding earlier ones, so a Skarn deny there is not final: a hook loading after it that answers allow replaces the decision. That is why preToolUse remains the durable gate and permissionRequest is a second chokepoint rather than a stronger one. A sandbox escape narrows what the merge can produce: when toolInput carries requestSandboxBypass: true, GitHub's reference states that a hook allow never pre-approves the request or short-circuits the user prompt and only a deny propagates, so the merged permissionRequest decision on such a call can block it or leave it to the interactive prompt, never pre-approve it; a hook loading after Skarn can still replace the deny with an allow that falls through to the user. A top-level disableAllHooks: true in the repository's .github/copilot/settings.json skips every hook from repository files, user files, plugins and inline blocks for that repository, the operator's own included, and logs nothing when it does; machine policy hooks keep running under it (GitHub documents them as unaffected; measured on CLI 1.0.82 in a trusted repository, where the same session suppressed the user hook and honored the policy hook's deny). It silences the layers it reaches across events (sessionStart as well as preToolUse) and leaves the host application's own SDK-registered callbacks running, so doctor reads that file and reports the file layer as inert rather than counting it as protection or calling the machine unprotected.
preToolUse fails CLOSED on a non-zero exit, but a hook TIMEOUT fails OPEN (the shipped configs set timeoutSec 10). permissionRequest treats exit 2 as a deny.
GitHub Copilot (VS Code agent mode)
VS Code agent mode speaks a second Copilot dialect: PascalCase event names in a Claude-shaped envelope, camelCase tool_input keys, and VS Code's own tool-name vocabulary (run_in_terminal, create_file, ...), which Skarn maps to canonical names. MCP calls arrive as PreToolUse with an mcp_<server>_<tool> name.
Events and routing
VS Code discovers hooks from ~/.claude/settings.json (chat.hookFilesLocations), so a machine already running Skarn's Claude guard receives VS Code Copilot events. The VS Code tool-name vocabulary routes them to the Copilot adapter instead of a silent Claude fast-allow; the shipped configs pin --agent copilot.
VS Code blocks only on exit 2; any other non-zero exit fails OPEN.
Gemini CLI
Gemini CLI fires eleven PascalCase events with a JSON envelope on stdin; hooks ship on by default since v0.26.0. Skarn gates three of them - BeforeTool (the enforcing pre-execution gate), BeforeAgent (the submitted prompt, an egress channel), and AfterTool (the tool result, opt-in) - and every other event fast-allows. The stdout protocol is strict: the host requires that a hook print nothing to stdout but its final JSON object, so the guard's emit arm is the sole stdout writer and an allow prints nothing at all. Gemini's PUBLISHED output schema documents only allow and deny (alias block), with no ask value; gemini-cli 0.49.0 does route an undocumented decision "ask" on BeforeTool to an interactive confirmation, but skarn deliberately does not emit it: a version that drops the undocumented behavior would read "ask" as no decision and let the call through, so a would-be ask degrades to deny (fail-closed on an undocumented channel). Timeouts are MILLISECONDS here, not seconds (the shipped entries use 5000).
Events and routing
The Before*/After* event vocabulary is unique to Gemini - no other host uses those names - so auto-detection is unambiguous; the shipped configs pin --agent gemini anyway, the same policy every other host follows. MCP tools arrive named mcp_<server>_<tool> with SINGLE underscores, so the guard keys MCP treatment on that prefix rather than on the canonical mcp__ form.
A non-2 non-zero exit is a warning and fails open; exit 2 blocks with stderr as the reason. --strict plus a licensed enforce exits 2 on an event the guard cannot parse (malformed or oversized) and on a scan that cannot run (unreadable rules); an out-of-scope action still fast-allows, and an unlicensed guard is forced to audit and exits 0. A hook that runs past its timeout has its decision discarded and the call proceeds, and the observed wait tracks the hook's own runtime up to about 30 seconds rather than the configured value, so the timeout bounds nothing - a fast guard is the real protection. From gemini-cli 0.56.0 a crashed, timed-out, or exit-2 hook also prints a 'Hook execution for <event>: N succeeded, M failed' summary and a '[WARNING] Hook(s) [skarn-guard] failed' line on stderr; only the exit-2 case blocks.
Grok Build
Grok Build fires a PascalCase event set with a JSON envelope on stdin, in a camelCase dialect of its own: hookEventName carries a snake_case VALUE ("pre_tool_use"), the tool fields are toolName/toolInput/toolUseId/toolInputTruncated, and PostToolUse adds toolResult. Skarn gates three of those events - PreToolUse (the only enforcement point grok offers), UserPromptSubmit (the submitted prompt, an egress channel), and PostToolUse (the tool result, opt-in) - and every other event fast-allows. Grok has NO non-deciding channel: its passive events ignore stdout entirely and every recognized PreToolUse output decides, so the guard emits nothing at all in audit mode and the would-be verdict lands only in the guard log, which skarn guard report reads. Timeouts are seconds (the shipped entries use grok's 5-second default). The honest posture is fail-open: every grok hook failure, timeout, crash or malformed output is recorded for the session scrollback and blocks nothing, so an explicit deny is the only thing that stops a call.
Events and routing
The camelCase hookEventName key is unique to grok - Claude, Codex, Cursor and VS Code Copilot spell it hook_event_name, and the Copilot CLI carries no event-name field - so an unpinned grok payload auto-detects on key presence, before the Copilot CLI's toolName/sessionId structural tells that it would otherwise trip. Grok is also the ONE place the guard overrides an explicit --agent pin: grok natively runs the hooks configured in ~/.claude/settings.json and ~/.cursor/hooks.json and invokes them with its own dialect, so a hook pinned --agent claude is handed grok events it cannot read. When the process environment carries GROK_HOOK_EVENT (grok's runner injects it for every hook and strips any value a config sets) AND the payload carries hookEventName, the event routes to the grok adapter whatever the pin says. Neither signal alone moves a pin, and a real Claude payload under a claude pin is unaffected either way. MCP tools arrive under their resolved server__tool name with no prefix; the guard rewrites that to the canonical mcp__ form so every tool-keyed detector sees an MCP call, and an MCP call never fast-allows.
Every failure fails open, which is grok's own posture for hooks: a non-zero exit other than 2 is recorded and blocks nothing. Exit 2 is an explicit PreToolUse deny, and a deny on stdout is honored regardless of the exit code (a stdout allow paired with exit 2 still denies, so the guard never pairs the two). --strict plus enforce turns an unparseable event into one stderr line and exit 2.
Antigravity CLI (agy)
The Antigravity CLI (agy) fires five PascalCase events - PreToolUse, PostToolUse, PreInvocation, PostInvocation, Stop - with a camelCase protojson envelope on stdin and NO event-name field: the hooks.json entry that fired is the only thing that names the event, so the adapter reads the event off the payload shape (a toolCall with no error key is the PreToolUse it gates; every other shape fast-allows). PreToolUse is the whole guard surface on this host: PreInvocation carries no prompt text and PostToolUse carries no tool output, so there is no prompt-submit gate and no result scan (verified on agy 1.1.18 and 1.1.19). The stdout contract is a flat {"decision","reason"} object, and agy FAILS CLOSED on everything but an explicit allow: a deny blocks, and a crash, a timeout (seconds; the shipped entries use 5), invalid JSON, and an empty {} (a missing decision) all block the call and the model sees the hook-failure text; only an empty stdout was observed to proceed (1.1.19), which is undocumented and which the guard never relies on. The guard therefore answers EVERY tool event with an explicit decision: enforce prints deny or allow, audit prints allow with the would-be verdict in reason (agy has no non-deciding channel), an out-of-scope tool gets an explicit allow, and a non-tool event gets the empty object. ask is not a block on agy (it hands the call to the permission layer, which auto-denies in print mode), so a would-be ask degrades to deny. An allow never grants a permission: agy's own permission check still runs after the hook.
Events and routing
The camelCase toolCall / conversationId / workspacePaths / artifactDirectoryPath field set is unique to agy - Claude, Codex, Cursor, Gemini, and VS Code Copilot use snake_case envelopes, the Copilot CLI spells its fields toolName/toolArgs/sessionId, and grok's tell is hookEventName - so an unpinned agy payload auto-detects (before the Claude PascalCase fallback, so a future payload that adds hook_event_name still routes here); the shipped configs pin --agent antigravity anyway, uniform policy. The agy tool vocabulary on the hook wire was pinned live (1.1.19): a file write fires as write_to_file (TargetFile/CodeContent) and an edit as replace_file_content or multi_replace_file_content (TargetFile/ReplacementContent), while run_command, view_file, browser_*, the read_url_content/open_browser_url/search_web network steps, and the agency_tool_call/invoke_subagent/browser_subagent subagent steps keep their step-type spellings; the step-type spellings of the write tools (file_change, code_action, edit_notebook) stay mapped and matched as drift aliases. The MCP dispatch is call_mcp_tool on the hook wire (the binary's hook tool table) and mcp_tool in the transcript the scan parser reads; both are rewritten to the canonical mcp__ form (from the ServerName/ToolName args), so an MCP call never fast-allows. The grok override still applies: a hook process grok spawned routes to grok whatever the pin.
Fail-closed by the host's design, on every outcome but an explicit allow: a crashed, slow (past the entry's timeout, in seconds), or malformed skarn BLOCKS the tool call, and a missing skarn binary blocks every matched call the same way (sh -c exits 127). Enforce and audit are both hard gates here - audit cannot fail more open than enforce, so a machine where the hook is wired and the binary is gone blocks matched calls until the binary is back or the entry is removed. --strict plus a licensed enforce answers an event the guard cannot parse with an explicit deny; without --strict it answers an explicit allow, which is the only way to fail open on this host.
Kimi Code
Kimi Code fires PascalCase events with a JSON envelope on stdin - hook_event_name, session_id, cwd - because its hook runner builds the payload from camelCase keys and snake-cases them on the way out, so the shape is Claude's with two differences that matter: every payload carries a client_type naming the host, and UserPromptSubmit delivers prompt as an ARRAY of content blocks rather than a string (verified on kimi-code 0.39.1). Of the twenty events kimi defines, only PreToolUse, UserPromptSubmit and Stop can block; the rest are fire-and-forget, so a verdict on one would be a claim the host does not honor. Both blocking events skarn gates are wired by default. PermissionRequest is deliberately not wired - it is observation-only on kimi, unlike Claude Code, where it is a real second gate - and Stop stays unwired because blocking it forces the agent to keep going.
Events and routing
Kimi shares Claude's envelope and event names, so the tell is the client_type field its own hook runner stamps on every payload: no other host emits it, and the value is matched rather than just the key, so only kimi's own CLI identity routes here. The pin still matters and every shipped entry carries it: a host embedding kimi's older hook engine sends no client_type, and that payload is byte-shaped like Claude's. The misroute is not symmetric - a claude-routed PreToolUse deny happens to be schema-compatible and still blocks, but a claude-routed UserPromptSubmit answers with a top-level decision block that kimi does not honor, so the prompt is allowed while the guard log records a deny that never happened, under a claude label that corrupts the per-agent denominators guard report is built from. The kimi tool vocabulary is Claude's for everything skarn gates except FetchURL (mapped to WebFetch), Agent and AgentSwarm (mapped to spawn_agent) and ReadMediaFile (mapped to Read); MCP calls already arrive in Claude's own mcp__<server>__<tool> form.
Fail-open by the host's design: exit 2 blocks, exit 0 with a deny object blocks, and every other non-zero exit, every hook error and every timeout allows the action. The shipped entries set timeout = 10, below kimi's 30-second default. --strict plus a licensed enforce answers an unparseable event with exit 2 and one stderr line.
Examples
Show which license this machine is using, where it came from, and when it expires.
skarn license
Validate a license file and install it; the previous license, if any, is backed up alongside it.
skarn license ~/Downloads/team.skarnlicense
Fetch a fresh license for this subscription, verify it against the keys built into this binary, and install it; nothing is written unless it verifies.
skarn license renew
Scan every AI coding session on this machine and print a friendly risk summary in one command; no flags, no license.
skarn assess
Drive the MCP handshake by hand: the server answers one JSON-RPC line on stdout and exits 0 when stdin closes.
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' | skarn mcpRun the MCP server with the two content tools enabled; put the argument in the client's own mcpServers args, never in a shipped plugin.
skarn mcp --enable-recall
Print what the MCP server exposes and how to register it in a client; it returns before the protocol loop starts.
skarn mcp --help
Write a self-contained, redacted security report to share with a colleague; -o report.md writes a plain-text version.
skarn assess -o report.html
Statically vet this machine's AI assistant configuration - hooks, MCP servers, permission grants, plugins and skills - and list the risky patterns found. Read-only, offline, no license.
skarn vet
Emit the config findings as SARIF for a code-scanning pipeline and exit 1 on anything high or above; an unreadable config file exits 6 rather than reporting a partial view as clean.
skarn vet --format sarif --fail-on-severity high
Detect installed AI coding agents and wire the guard hook into each one in audit mode, with a wizard on a terminal; ends with the guard self-test and a list of every file touched.
skarn setup
Print the exact Cursor hooks.json content that setup would write, without writing anything.
skarn setup --print --agent cursor
Check that skarn is really protecting this machine: license, every wired agent hook, the guard log, and the guard self-test. Each warning or failure names the command that fixes it.
skarn doctor
The same checks as one JSON object for fleet scripts; the check ids are stable and a rendered report always exits 0 (an unknown option is refused with exit 1 and an unresolvable home directory with exit 6, both before any check runs).
skarn doctor --json
Flip every agent that already carries skarn entries from audit to enforce, leaving everything else alone.
skarn setup --update --mode enforce
Summarize the last 30 days of flagged calls per agent (verdicts, top rules, latency, the most recent denies) and, when the window is clean, print the exact command that flips the hooks to enforce.
skarn guard report --window 30d
The same aggregate as one JSON object for fleet scripts: counts are over flagged actions, since the guard does not log clean calls.
skarn guard report --format json
Accept a finding the guard flagged (the fingerprint printed under the deny in guard report) as a false positive, so the identical call stops being blocked. Writes the personal baseline the guard reads; a real leak is never accepted this way.
skarn guard accept 7d343e3a105ae026589b3371d565a4ad2943dd5ba5f81a19c7500b2ab4dbb1f0 --reason 'internal test credential'
Prove the guard wiring: run synthetic benign and fake-credential events through each adapter's real code path and report the verdicts (credential shown redacted).
skarn guard --self-test
Scan the default window (the last 30 days) of all sessions for leaked secrets and attack patterns.
skarn check
Scan all history, report only high-severity-and-above findings, and emit JSON for a pipeline.
skarn check --hours 0 --severity high --format json
Exit non-zero in CI when a session's risk score exceeds 60.
skarn check --fail-on-risk 60
Write a redacted Markdown evidence pack for one product build (Team); redirect it to a dated file such as skarn-evidence-2026-07-24.md to file into a technical file. Omitting the lineage flags renders a pack that states it cannot be attached to a specific technical file.
skarn check --format evidence --product acme-gateway --product-version 3.2.1 --build-id 9f2c1ab
Search past sessions for a regular-expression pattern.
skarn search 'AWS_SECRET' --regex
List recent Claude Code sessions.
skarn recent --cli claude
Render per-project analytics to a self-contained HTML file.
skarn stats --by project --format html -o stats.html
Browse and scan sessions in a local web UI on 127.0.0.1:7777 (localhost only, no egress); open the token-carrying URL printed at startup.
skarn serve --port 7777
Serve the web UI with a custom rule pack layered on the bundled rules; the Security view surfaces its findings too.
skarn serve --rules ./team-rules.toml
Walk each new finding and label it a true or false positive with a reason; the decisions are written into the committed baseline and survive re-scans.
skarn baseline audit .skarn-baseline.json
Record a single false-positive fingerprint (from SARIF partialFingerprints or the ndjson skarn.fingerprint field) into the baseline without the interactive loop.
skarn baseline accept .skarn-baseline.json 7d343e3a105ae026589b3371d565a4ad2943dd5ba5f81a19c7500b2ab4dbb1f0 --reason 'internal test credential'
Security
Skarn scans locally and makes no network connection by default. Secrets are redacted in check's reports and in everything the recall commands print (search, recent, messages, stats, cmds, tools, mcps, restore, export). --no-redact lifts the mask only where it is honored - check's text, json and sarif reports, and the session content the recall commands print; the ndjson stream, the evidence pack, the artifacts written by --drop, serve and assess, the baseline files, the mcp tools, the guard, and every serve API route that returns session content ignore it and stay redacted.
Two commands transmit anything off the machine, and only when you type them. skarn check --update-rules fetches a signed feed bundle from the subscriber channel, presenting $SKARN_FEED_TOKEN as a bearer credential; --feed-url names that channel when $SKARN_FEED_URL does not. The feed is off by default and is disabled by --offline. skarn license renew posts the installed license token to the license service to receive a re-signed one. Both refuse any endpoint that is not https, or http against loopback, and any endpoint carrying userinfo. No session content, no finding, and no scanned secret ever leaves the machine through a connection skarn makes. skarn mcp makes no network connection; the results it hands to the connected MCP client (redacted findings by default, redacted session content only with --enable-recall) are forwarded by that client to its model provider - that egress is the client's, and it happens only when you configure the server.
skarn vet reads the AI assistant configuration files listed under FILES read-only: it opens each one for reading, never writes, rewrites, or removes one, and makes no network call. It reports what it finds and leaves every decision about the configuration to you. --offline is accepted for parity and changes nothing.
skarn mcp reads the same session stores as assess and the same configuration files as vet, read-only and with no network call, and answers only the AI coding assistant that spawned it over stdin and stdout. Its results are the redacted scan report, the masked vet report, and session metadata carrying neither message text nor any label authored inside a transcript; with --enable-recall the two content tools add session text and labels with every detected secret masked, and the search response carries no echo of the query or of the project filter. Because the assistant receives those results, they travel wherever that assistant sends its context, so treat them as leaving the machine even though skarn itself opens no socket.