AgentShield (by affaan-m, MIT, ~1.1k stars, Everything Claude Code ecosystem) is a security auditor for AI agent configs: scans your ~/.claude/ (and similar directories like Cursor), checks for hardcoded secrets, misconfigured permissions, hook injection, MCP server risks and prompt-injection surfaces, and outputs a graded security report. Three forms: CLI, GitHub Action, GitHub App.

In one sentence: before installing any community skill/MCP/hook, run it once — it is read-only and changes nothing.

You installed a pile of plugins, skills and MCP servers for Claude Code — are there secret leaks, dangerous permissions, or suspicious hooks in the config? AgentShield exists for this: it scans Claude Code config for secrets, permissions, hooks, MCP servers and prompt-injection surfaces, and outputs a severity-graded security report. Its most reassuring property is being read-only: scanning changes nothing (verified zero write surface), so you can run it any time without worry. There are two usage paths: npx no-install trial (verified here) or global install for long-term use (officially recommended).

When to use it:

• You just installed a bunch of agent site docs and want to see what risk surfaces exist in the config;
• You want a security check of agent config before CI or opening a PR;
• You want to hand scan results to an agent/CI for decisions (-f json machine-readable).

When not to use it: when you need fixing, not checking — it only reports, it does not fix.

note: No-install form (verified here); use the npmmirror registry on mainland networks

# Source: Trove detailed guide · verified 2026-08-28
npm_config_registry=https://registry.npmmirror.com npx -y ecc-agentshield scan

Expected output: AgentShield Security Report (target = auto-discovered ~/.claude/ or current directory; graded report + findings list)

One command plus a version check:

# Source: Trove detailed guide · verified 2026-08-28
npx -y ecc-agentshield --version

Expected output: 1.5.0 (verified here)

# Source: Trove detailed guide · verified 2026-08-28
npx -y ecc-agentshield scan

Expected output: Security Report (graded + findings list; scanning is read-only, running it any number of times changes nothing)

• version prints correctly = the package fetches and executes;
• a scan produces a report (even all-low/no findings) = the scan path works.

npm package ecc-agentshield, CLI command agentshield scan. Scan target = auto-discovered ~/.claude/ or the current directory (or a specified directory); output = graded report + findings list (Secrets / Permissions / Hooks / MCP Servers / Agents sections + file-level findings).

Two usage forms:

• Method A: npx direct scan (no install, verified here);
• Method B: global install (officially recommended for long-term use).

Where it writes: nowhere — scanning has zero write surface; global install only writes the npm global directory.

Measured command = npx ecc-agentshield scan (verified in this environment 2026-08-28, npm package ecc-agentshield 1.5.0, npmmirror); GitHub release v1.4.0 (2026-03-22) has no assets, official distribution via npm; scan = read-only (measured zero write surface); no background processes; the npm package includes a global install form (npm i -g ecc-agentshield)

Step 1: Run the first scan

Why: the npx form does not install anything globally — one scan, done, gone; good for seeing results before deciding on a permanent install. Mainland npm direct is slow, use the npmmirror registry prefix. First scan target = auto-discovered ~/.claude/ or the current directory.

# Source: Trove detailed guide · verified 2026-08-28
npm_config_registry=https://registry.npmmirror.com npx -y ecc-agentshield scan

Expected output: AgentShield Security Report (target = auto-discovered ~/.claude/ or current directory; graded report + findings list)

After install, confirm:

• output is a Security Report with grades and findings;
• version check: npx -y ecc-agentshield --version → 1.5.0.

Stuck? How to recover:

• npx slow/fails to fetch → make sure the command has the npm_config_registry=https://registry.npmmirror.com prefix;
• Node version error → confirm Node >= 18.

Step 2: Global install for long-term use

Why: after a global install you call agentshield directly — good for hooking scans into daily flows (CI, before PRs).

# Source: Trove detailed guide · verified 2026-08-28
npm_config_registry=https://registry.npmmirror.com npm install -g ecc-agentshield
agentshield scan

Expected output: same as above (Security Report)

After install, confirm:

• agentshield --version works;
• agentshield scan outputs a report.

Stuck? How to recover:

• global command not found → confirm the npm global bin directory is on PATH;
• scan shows many findings and you do not know where to start → the report is graded; handle high-risk items first (Secrets / permissions), then review Hooks/MCP one by one.

Step 3: Scan a specific directory + hand to an agent

Why: scanning a specified directory (e.g. /path/to/.claude) targets a specific config; -f json outputs a machine-readable report (verified 2026-08-30: JSON contains timestamp/targetPath/findings[]/score/summary) for agent post-processing.

# Source: Trove detailed guide · verified 2026-08-28
npx -y ecc-agentshield scan /path/to/.claude

Expected output: security report (Secrets/Permissions/Hooks/MCP Servers/Agents sections + file-level findings)

# Source: Trove detailed guide · verified 2026-08-28
npx -y ecc-agentshield scan -f json

Expected output: JSON report (verified fields: timestamp / targetPath / findings[] (id/severity/category/title/file/fix) / score (grade/numericScore/breakdown) / summary (totalFindings/critical/high/medium/low/info/filesScanned)) (verified 2026-08-30: -f json works)

Stuck? How to recover:

• -f json output misbehaves → confirm the flag is -f json (not --json);
• specified directory missing/no permission → confirm the path exists and is readable, then scan.

Startup and entry

No background process; entry = agentshield scan (or the npx form).

Common operations

Operation 1: View the version (verified here)

# Source: Trove detailed guide · verified 2026-08-28
npx -y ecc-agentshield --version

Expected output: 1.5.0

Operation 2: Scan a specific directory

# Source: Trove detailed guide · verified 2026-08-28
npx -y ecc-agentshield scan /path/to/.claude

Expected output: security report (Secrets/Permissions/Hooks/MCP Servers/Agents sections + file-level findings)

Operation 3: Integrate with agent flows (hand the report to an agent after scanning)

# Source: Trove detailed guide · verified 2026-08-28
npx -y ecc-agentshield scan -f json

Expected output: JSON report (verified fields: timestamp / targetPath / findings[] (id/severity/category/title/file/fix) / score (grade/numericScore/breakdown) / summary (totalFindings/critical/high/medium/low/info/filesScanned)) (verified 2026-08-30: -f json works)

Data and directories

• No dedicated data directory; scanning reads ~/.claude/ (or the specified directory) read-only.

Same source as the tool-page matrix — 19 pairs total (3 measured compatible / 16 inferred possibly compatible / 0 inferred possibly conflicting); full pairs, states and evidence: Conflict pairs (co-install matrix).

• No standalone handbook yet; for install/uninstall issues first see the agent-executable guide notes

# Source: Trove detailed guide · verified 2026-08-28
npm rm -g ecc-agentshield 2>/dev/null || true; npm cache clean --force 2>/dev/null || true

note: the npx form leaves no global residue (idempotent); a global install needs explicit uninstall; scanning has zero write surface

# Source: Trove detailed guide · verified 2026-08-28
npm rm -g ecc-agentshield 2>/dev/null || true
npm ls -g ecc-agentshield 2>/dev/null | grep -q ecc-agentshield && echo '残留: ecc-agentshield 仍存在' || echo 'agentshield removed: OK'

Expected output: agentshield removed: OK

• Runtime preflight (needs Node >= 18)
• Official npm path (measured here); npmmirror registry recommended in China
• Each operation = one command block + expected output
• npx form leaves no global residue (idempotent); global install needs an explicit uninstall; scan has zero write surface
• Read-only: the scan writes nothing (measured zero write surface), safe to put into an Agent pipeline

• Q: Will scanning change my config? A: No. Read-only auditor, verified zero write surface.
• Q: npx or global install? A: try npx first (no install); install globally for long-term use (officially recommended).
• Q: What if the report shows high-risk findings? A: the report is graded; handle Secrets and permission high-risk items first; evaluate Hooks/MCP one by one as needed. This tool only reports, it does not fix.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel; project issues go to the author's repository.

• Version: [1.5.0, 1.5.0] locked (verified at collection).
• Environment: Node >= 18.
• Network: npm via npmmirror prefix (verified mainland path).
• Write surface: zero (read-only auditor, verified); global install writes the npm global directory.
• Co-install: no conflict-matrix pairs (read-only tool, no shared write surface).

Local verification record（2026-08-28）

• Not tested: -p specified-directory scan (same command shape, flag confirmed via --help); --fix auto-fix (writes config, not run here).

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方 README（npm 包内同源，v1.4.0）：AgentShield 完整用法 [官方文档 · AgentShield 官方 · 2026-08-31（包 1.4.0）]
  官方用法全解——Quick Start（npx 免安装扫描 / 全局安装）、扫描指定目录、--fix 自动修复（硬编码密钥→env 引用）、-f json CI 输出、HTML 报告、--opus 多模型对抗分析（需 API key）、init 生成安全基线配置、检测面（密钥 10 规则 14 模式 / 权限 10 规则 / hooks 34 规则 / MCP 23 规则 / Agent 配置 25 规则）、GitHub Action 形态、CLI 参考