activate-agentmd

Security for the instructions AI coding agents obey, and the actions they take.

npx activate-agentmd demo     # two minutes, offline, no keys
npx activate-agentmd init     # attach to the agents in this project

Every coding agent obeys files in your repo before it reads the code: CLAUDE.md, AGENTS.md, Cursor rules, skills, MCP configs. Agent.md checks those files, turns their "never" lines into each agent's own controls, and, with the runtime guard, stops irreversible calls while the agent runs. No model is called on the enforcement path.

init attaches once; after that the hooks run on their own:

agentmd init  attaching to the agents in this project

  ● Claude Code  because of .claude, CLAUDE.md
  ● Codex        because of AGENTS.md

  Compile
✓ 3 deny rules added to .claude/settings.json.
✓ 3 forbidden commands written to .codex/rules/agentmd.rules (Codex loads it in trusted projects).
✓ 3 rules written to .agentmd/policy.json (the runtime guard refuses them on every attached agent).
  Hooks
  ✓ pin       hard rules re-injected after compaction and resume
  ✓ guard     every install the agent runs is checked first

What is enforced where, today:

| Agent | "Never" lines from your files | Runtime guard (pause, signed refusal) | | --- | --- | --- | | Claude Code | blocked: permissions.deny | blocks, through the PreToolUse hook | | Codex | blocked in trusted projects: .codex/rules | not attached (an advisory MCP check exists) | | Gemini CLI | refused by the runtime guard; also printed for ~/.gemini/policies | blocks, through the BeforeTool hook | | Cursor | refused by the runtime guard | blocks, through the preToolUse hook (editor and cursor-agent) |

The runtime guard (agentmd-guard, a proprietary Go binary) comes with this package: npm installs only the one built for your machine (Linux, macOS, Windows; x64, arm64), and init uses it only if its SHA-256 matches the hash pinned here. If your install skipped optional packages, agentmd guard-install fetches it from the npm registry with the same check. Registry presets are now agentmd init --presets.

Commands

| Command | What it does | | --- | --- | | init | Attach to the agents here: compile rules, install hooks, attach the runtime guard when installed | | demo | Runtime pause, compile, Codex check and provenance, offline | | init --presets | Scan the stack and install matching registry standards | | guard-install | Add the runtime guard if npm skipped it (from the npm registry, SHA-256 pinned) | | broker aws\|github\|gcp\|azure / broker run [--aws] [--github-repo R] [--gcp SA] [--azure] -- <agent> | Short-lived, scoped credentials (AWS minus destructive actions, a 1-hour GitHub token for one repo, a GCP service account token, an Azure token without refresh); the agent runs where your long-lived logins are out of reach (bubblewrap on Linux, Seatbelt on macOS, a fresh profile on Windows) | | digest [--days N] [--out file] | One Markdown message: what the guard stopped, rules learned, rules in force, credentials kept off the agent, lint now | | allow | Approve the call the runtime guard paused (a person, at a terminal) | | receipts [id] | List signed refusals, or verify one (receipts key --signer github:<login> names the key) | | memory [on\|off\|status\|forgive] | Opt-in per project: an action the guard refused twice here, with no approval since, is blocked the next time instead of paused. Never refuses anything else | | verify <receipt.json> | Who signed a receipt (guard decision, bundle, Team evidence) and whether it is intact, against keys you trust or the signer's GitHub signing keys | | impact | What the runtime guard has done in this project | | scan [dir] | Credentials an agent here could read (values never shown) | | link | Wire installed packages into your agent config files | | search <query> | Search names, categories, descriptions | | list [model/category] | Browse the registry | | list --installed | What this project has | | info <package> | Details for one package | | install <package> | Install a package, or a whole category | | remove <package> | Uninstall | | outdated | What's changed upstream, and what you've edited | | update | Pull current versions | | validate | Check registry + manifest integrity | | agents | List supported agent config targets | | lint | Check every file your agent reads: leaked keys, prompt injection, bloat, stale pins. Exit 1 on an error; --sarif for code scanning | | pins | The breaking changes for the dependency majors this project runs | | audit <owner/repo> | Run lint on any public GitHub repo, no clone, nothing executed | | guard [--install] | Block the agent's installs of look-alike packages, untrusted indexes and vulnerable pins before they run; --install adds it as a Claude Code hook | | pin [--install] | Keep the hard rules in context through compaction: a SessionStart hook re-reads them after every /compact and resume | | enforce [--write\|--check\|--print codex\|gemini] | Turn "never do X" lines into deny rules for Claude Code, forbidden rules for Codex and the runtime guard's policy, and report which rules are still prose only; --check fails CI on a gap | | learn [--write\|--pr] | The corrections you keep giving in sessions, and the calls the runtime guard keeps refusing, proposed as rules; --write adds them and compiles them for every agent, --pr opens them as a pull request | | cost [--budget <tokens>] | What your always-on context costs per developer per month, and what lint --fix saves; --budget fails CI over a token limit | | sbom [--out bom.json] | Context bill of materials (CycloneDX 1.6): every file, skill, hook, MCP server and grant an agent loads, with hashes | | bundle sign\|verify\|attest | Sign the exact set of files your agent reads with your org's key; fail CI on any unsigned change |

Package paths are <model>/<category>/<package>. A trailing slash installs the whole category:

agentmd install claude/Security/owasp    # one
agentmd install claude/Testing/          # all 11

lint works on any repository, no install or manifest needed:

npx activate-agentmd lint

Full reference: docs/cli.md

Updates respect your edits

agentmd update never overwrites a package you've edited. It reports the conflict and leaves it alone until you pass --force.

$ agentmd outdated

  ↑  claude/Testing/unit       update available
  ✎  claude/Security/owasp     edited locally

1 outdated, 1 modified, 24 current

The distinction comes from a SHA-256 checksum recorded at install time.

Where things go

| Path | What | | --- | --- | | .agentmd/presets/ | Package content | | .agentmd/manifest.json | What's installed, with version, checksum and source |

Commit both — that's how a team shares one set of standards, and how changes to your agent's instructions show up in code review.

Registry

304 canonical standards, tuned for 11 model families (3,348 total): claude, deepseek, gemini, glm, grok, kimi, minimax, mistral, open-ai, qwen and sarvam-ai.

agentmd list claude              # all categories
agentmd list claude/Security     # packages, with descriptions

Security

This CLI distributes content your agent reads as instructions, so:

• Package content is never executed — it's markdown written to disk.
• HTTPS only; a redirect to plaintext HTTP is refused.
• Writes are resolved against .agentmd/presets/ and refuse to escape it.
• Fetches are bounded by timeout, redirect count and response size.
• No accounts. Telemetry is off by default and opt-in (agentmd telemetry --enable). Two runtime dependencies: picocolors and the Anthropic SDK, used only by review, test and extract under your own key.

Packages are not signed — see SECURITY.md for the full threat model, including what is not guaranteed.

Environment

| Variable | Meaning | | --- | --- | | AGENTMD_REGISTRY_BASE | Override the registry base URL (mirrors, testing) | | AGENTMD_TIMEOUT_MS | Per-request timeout, default 30000 | | AGENTMD_DEBUG | Print a stack trace on error |

Requires Node 18+.

Contributing

Adding a package is a directory and one markdown file — see CONTRIBUTING.md.

cd packages/cli && npm ci && npm test

MIT licensed.