GitHub - AgentGuardHQ/agentguard

Run AI agents without fear.
Install in 30 seconds. Your agents can't break what matters.

AI coding agents (Claude Code, Codex CLI, GitHub Copilot CLI, Google Gemini CLI, OpenCode, Goose, and more) run autonomously — writing files, executing commands, pushing code. AgentGuard prevents them from doing catastrophic things: no accidental pushes to main, no credential leaks, no runaway destructive loops. 24 built-in safety checks, zero config required.

For individuals: stop your AI from wrecking your machine or repo. For teams: run fleets of agents safely at scale, with audit trails that pass compliance.

See it live — We run 100+ autonomous AI agents building AgentGuard itself, governed 24/7. Every deny, every escalation, every code review — visible in real time. Watch the live swarm →

Get Started

npm install -g @red-codes/agentguard
cd your-project
agentguard claude-init
# Interactive wizard: choose enforcement mode and a policy pack
# → Creates agentguard.yaml, installs Claude Code hooks, and activates governance

Or use npx without a global install:

cd your-project
npx @red-codes/agentguard claude-init

→ Sign up for Cloud — team governance, fleet dashboard, real-time telemetry → Join GitHub Discussions — ask questions, share your setup

The claude-init wizard walks you through setup interactively:

  Choose an enforcement mode:
    ❯ 1) Monitor  — log threats, don't block (recommended to start)
      2) Educate  — log + explain why the action was flagged
      3) Guide    — log + suggest a corrected command
      4) Enforce  — block dangerous actions immediately

  Enable a policy pack?
    ❯ 1) essentials — secrets, force push, protected branches, credentials
      2) strict — all 24 invariants enforced
      3) none — monitor only, configure later

Verify it's running:

agentguard status
# ✓ Claude Code hooks installed
# ✓ Policy file (agentguard.yaml)
# ✓ Runtime active

Test a deny rule without executing anything:

echo '{"tool":"Bash","command":"git push origin main"}' | agentguard guard --dry-run
# ✗ git.push main → DENIED (protect-main)

Non-interactive setup (CI or scripted installs):

agentguard claude-init --mode monitor --pack essentials

Ready for the cloud? — team governance, fleet dashboard, real-time telemetry across all your agents: agentguard-cloud-dashboard.vercel.app/onboarding · GitHub Discussions — questions, setup help, community

Cloud Dashboard & Live Office

Connect to the AgentGuard Cloud for team governance, real-time telemetry, and multi-tenant management:

npm install -g @red-codes/agentguard   # Install AgentGuard
agentguard cloud login                  # Opens browser → authenticate → CLI auto-configures

Link	Description
Live Office	Watch our 100+ agent swarm build software 24/7 — real-time governance visualization
Dashboard	Team dashboard — runs, violations, analytics

Agent Identity

Every governed session has an identity. Set it via the CLI flag or let the interactive prompt ask:

agentguard guard --agent-name my-agent
# Or omit --agent-name and an interactive prompt will ask for role + driver

Identity consists of a role (developer, reviewer, ops, security, ci) and a driver (human, claude-code, copilot, opencode, ci). Identity flows to cloud telemetry for attribution, dashboard grouping, and persona-scoped policy rules.

What It Does

Capability	Details
Policy enforcement	YAML rules with deny / allow / escalate — drop `agentguard.yaml` in your repo
24 built-in invariants	Secret exposure, protected branches, blast radius, path traversal, CI/CD config, package script injection, and more
48 event kinds	Full lifecycle telemetry: `ActionRequested → ActionAllowed/Denied → ActionExecuted`
Real-time cloud dashboard	Telemetry streams to your team dashboard; opt-in, anonymous by default
Multi-tenant	Team workspaces, GitHub/Google OAuth, SSO-ready
Live Office visualization	24/7 live view of our actual 100+ agent swarm — watch AI build software under governance
Agent SDK	Programmatic governance for custom integrations and RunManifest-driven workflows
Agent identity	Declare agent role + driver for governance telemetry — automatic prompt or CLI flag
Pre-push hooks	Branch protection enforcement via git pre-push hooks, configured from agentguard.yaml
Works with	Claude Code, Codex CLI, GitHub Copilot CLI, Google Gemini CLI, OpenCode, Goose (Block), any MCP client

Policy Format (YAML)

Drop agentguard.yaml in your repo root. It's picked up automatically.

Minimal policy

mode: monitor      # monitor | educate | guide | enforce
pack: essentials   # curated invariant profile

rules:
  - action: git.push
    effect: deny
    branches: [main, master]
    reason: Protected branch — use a PR

Enforcement Modes

Four enforcement modes control how AgentGuard responds to policy violations:

Mode	Blocks?	Suggests?	Behavior
`monitor`	No	No	Log only — observe violations without interfering
`educate`	No	Yes	Allow + attach a `suggestion` explaining the violation via `additionalContext`
`guide`	Yes	Yes	Block + attach a `suggestion` with a `correctedCommand` the agent can retry
`enforce`	Yes	No	Deny the action outright

Set the mode globally and override per-invariant:

mode: monitor                # global default

invariants:
  no-secret-exposure: enforce   # always block secrets (hardcoded)
  blast-radius-limit: educate   # explain but don't suggest a fix
  no-force-push: guide          # suggest the safe alternative

In educate and guide modes, denied decisions include a suggestion field:

{
  "effect": "deny",
  "mode": "guide",
  "suggestion": {
    "message": "Force push is not allowed on protected branches",
    "correctedCommand": "git push origin main"
  }
}

Full schema reference

# Metadata
id: my-project
name: My Project Policy
description: Governance for the Acme repo
severity: 4                   # 1 (lowest) – 5 (highest)
version: "1.0.0"
agentguardVersion: ">=2.3.0"  # minimum AgentGuard version

# Enforcement mode
mode: enforce                 # monitor | educate | guide | enforce

# Policy pack (curated invariant profiles)
pack: essentials              # essentials | strict | or a named pack

# Compose with other policies (paths or built-in pack names)
extends:
  - soc2
  - hipaa
  - ./policies/team-overrides

# Per-invariant mode overrides
invariants:
  no-secret-exposure: enforce
  blast-radius-limit: monitor
  no-force-push: enforce

# Disable specific invariants entirely
disabledInvariants:
  - lockfile-integrity

# Default persona (conditions for the agent running this policy)
persona:
  model: claude-sonnet-4-6
  provider: anthropic
  trustTier: verified
  autonomy: supervised
  riskTolerance: low
  role: developer
  tags: [internal, ci]

# Rules
rules:
  # Basic deny rule
  - action: git.push
    effect: deny
    branches: [main, master]
    reason: Protected branch — use a PR

  # Target glob pattern
  - action: file.write
    effect: deny
    target: "**/.env"
    reason: No secrets modification

  # Multiple action types in one rule
  - action:
      - file.write
      - file.delete
    effect: deny
    target: "*.key"
    reason: Cryptographic key files are protected

  # Blast radius limit
  - action: file.write
    effect: deny
    limit: 20
    reason: Too many files modified at once

  # Require tests before push
  - action: git.push
    effect: deny
    requireTests: true
    reason: Tests must pass before pushing

  # Persona-scoped rule
  - action: deploy.trigger
    effect: deny
    persona:
      trustTier: [untrusted, limited]
      autonomy: [autonomous]
    reason: Only trusted agents can deploy

  # Forecast-conditioned rule (predictive governance)
  - action: git.push
    effect: deny
    forecast:
      testRiskScore: 70
      blastRadiusScore: 80
      riskLevel: [high]
    reason: Predicted risk too high

  # Intervention type
  - action: infra.destroy
    effect: deny
    intervention: PAUSE
    reason: Infrastructure destruction requires human approval

  # Allow rule
  - action: file.read
    effect: allow
    reason: Read access is unrestricted

Supported rule fields

Field	Type	Description
`action`	`string \| string[]`	Action type(s): `file.read`, `git.push`, `shell.exec`, `mcp.call`, etc. (41 types across 10 classes)
`effect`	`string`	`deny` or `allow`
`target`	`string`	Glob pattern for file paths or command patterns
`branches`	`string[]`	Git branch names this rule applies to
`reason`	`string`	Human-readable explanation
`limit`	`number`	Max file count (blast radius)
`requireTests`	`boolean`	Require passing tests
`requireFormat`	`boolean`	Require passing format check
`persona`	`object`	Agent persona conditions (`trustTier`, `role`, `autonomy`, `riskTolerance`, `tags`)
`forecast`	`object`	Predictive conditions (`testRiskScore`, `blastRadiusScore`, `predictedFileCount`, `dependencyCount`, `riskLevel`)
`intervention`	`string`	Intervention type: `deny`, `pause`, `rollback`, `modify`
`suggestion`	`string`	Suggested alternative command or action
`correctedCommand`	`string`	Auto-corrected command (e.g., safer equivalent)
`requireWorktree`	`boolean`	Require action to run inside a git worktree

Built-in Invariants

24 safety invariants run on every action evaluation:

Invariant	Severity	What it blocks
`no-secret-exposure`	Critical	`.env`, credentials, `.pem`, `.key` files
`no-credential-file-creation`	Critical	SSH keys, cloud configs, auth tokens
`no-cicd-config-modification`	Critical	`.github/workflows/`, `.gitlab-ci.yml`, Jenkinsfile
`no-governance-self-modification`	Critical	Agents modifying their own governance config
`no-scheduled-task-modification`	Critical	Cron jobs, scheduled task files
`protected-branch`	High	Direct push to main/master
`no-force-push`	High	`git push --force`
`no-network-egress`	High	HTTP requests outside your allowlist
`no-permission-escalation`	High	`chmod` world-writable, setuid/setgid
`no-skill-modification`	High	`.claude/skills/` files
`no-package-script-injection`	High	`package.json` lifecycle script changes
`transitive-effect-analysis`	High	Downstream policy violations from a file write
`no-ide-socket-access`	High	VS Code IPC socket files
`commit-scope-guard`	High	Staged files not written by the current session
`script-execution-tracking`	High	Shell commands executing session-written scripts (write-then-execute bypass)
`blast-radius-limit`	Medium	Caps file modification count per action (default: 20)
`no-container-config-modification`	Medium	Dockerfile, docker-compose.yml
`no-env-var-modification`	Medium	Shell profile and env var files
`no-destructive-migration`	Medium	Migration files with DROP/TRUNCATE DDL
`large-file-write`	Medium	Per-file size limit (prevents data dumps)
`test-before-push`	Medium	Requires tests to pass before push
`recursive-operation-guard`	Low	`find -exec`, `xargs` with write/delete
`lockfile-integrity`	Low	`package.json` changes without lockfile sync
`no-verify-bypass`	High	`git push/commit --no-verify` — prevents skipping pre-push/pre-commit hooks

Architecture

Agent tool call
      │
      ▼
AgentGuard Kernel
  1. Normalize   — map tool call to canonical action type
  2. Evaluate    — match policy rules (deny / allow / escalate)
  3. Check       — run 24 built-in invariants
  4. Execute     — run action via adapter (file, shell, git)
  5. Emit        — 48 event kinds → SQLite audit trail + cloud telemetry

Storage: SQLite audit trail at .agentguard/. Every decision is recorded and verifiable.

Kernel overhead: < 3ms end-to-end with the Go kernel (policy evaluation < 100µs, full invariant suite < 300µs).

Go Kernel — Performance

AgentGuard ships a high-performance Go kernel that runs as a single 3.2MB static binary. It evaluates every agent tool call with near-zero overhead:

Metric	Go Kernel	Node.js Kernel	Improvement
Startup	2ms	67ms	33x faster
Hook evaluation	<3ms	290ms	~100x faster
Memory	2.7 MB	80 MB	30x less
Binary size	3.2 MB	281 MB (node_modules)	88x smaller
Dependencies	1	~400 npm packages	400x fewer

Normalization benchmarks (AMD EPYC, Go 1.18+):

Action Type	Latency	Allocations
File read/write	105 ns	1
Git push	70 µs	6
Destructive command	82 µs	3
GitHub CLI	89 µs	2
Compound command (AST)	130 µs	6

Per-session impact — at 100 tool calls per agent session, governance adds 0.3 seconds total overhead with the Go kernel vs 29 seconds with Node.js:

Scenario	Node.js Kernel	Go Kernel	Time Saved
Single agent session (100 calls)	29s overhead	0.3s	28.7s
30-min coder session (~400 calls)	116s (2 min)	1.2s	~2 min back for coding
Daily fleet (100 agents × 2 runs)	96 min/day	1 min/day	95 min/day
Monthly fleet	48 hours/month	30 min/month	~47.5 hours/month

For teams running agent fleets, governance becomes invisible. Agents get 8% more productive time in every session — no startup tax, no dependency overhead, no bootstrap delays.

Zero-dependency deployment — the Go kernel is a single static binary. No node_modules, no pnpm install, no bootstrap deadlocks. Drop it in a worktree and it works. This is critical for CI/CD and fleet scenarios where agents spin up fresh environments.

The Go kernel includes: action normalization with AST-based shell parsing, policy evaluation, 24 invariants, escalation state machine, blast radius engine, telemetry shipper (stdout/file/HTTP), and a control plane signals API. It ships automatically via npm install — a postinstall script downloads the prebuilt binary for your platform.

For Teams and Enterprise

Feature	Details
Compliance packs	`extends: soc2`, `extends: hipaa` — pre-built policy packs mapping to SOC 2 CC6/CC7 and HIPAA 164.312 controls
Audit trail	Tamper-resistant SQLite event chain; export to JSONL for SIEM ingestion
Evidence PRs	`agentguard evidence-pr` — attach governance evidence summary to any PR
CI gates	`agentguard ci-check <session>` — fail CI if a governance session contains violations
Branch protection	Policy-enforced push controls on top of GitHub branch rules
SSO	GitHub and Google OAuth via cloud dashboard
Multi-tenant	Isolated workspaces per team or project

CLI Reference

# Setup (interactive wizard)
agentguard claude-init                    # Interactive wizard: mode + pack → creates policy + hooks
agentguard claude-init --global           # Install hooks globally (~/.claude/settings.json)
agentguard claude-init --mode monitor --pack essentials  # Non-interactive setup
agentguard copilot-init                   # Set up GitHub Copilot CLI hook integration
agentguard codex-init                     # Set up OpenAI Codex CLI hook integration
agentguard gemini-init                    # Set up Google Gemini CLI hook integration
agentguard goose-init                     # Set up Goose (Block) CLI integration
agentguard init --template strict         # Scaffold policy from a template
agentguard status                         # Show governance status

# Runtime
agentguard guard                          # Start governed action runtime
agentguard guard --policy <file>          # Use a specific policy file
agentguard guard --dry-run                # Evaluate without executing
agentguard guard --agent-name <name>      # Set agent identity for session

# Inspect
agentguard inspect --last                 # Show last run action graph
agentguard events --last                  # Raw event stream (pipe to jq)
agentguard traces [runId]                 # Policy evaluation traces
agentguard replay --last                  # Replay session timeline

# Cloud
agentguard cloud login                    # Device code auth — opens browser
agentguard cloud status                   # Check cloud connection
agentguard cloud events                   # Query events from cloud
agentguard cloud runs                     # List governance runs
agentguard cloud summary                  # Analytics summary

# CI / Compliance
agentguard ci-check <session>             # Verify session for violations (CI gate)
agentguard evidence-pr                    # Attach evidence summary to PR
agentguard audit-verify                   # Verify tamper-resistant audit chain
agentguard analytics                      # Violation pattern analysis

# Policy
agentguard policy validate <file>         # Validate a policy file
agentguard policy verify <file>           # Verify policy structure and rules
agentguard init --template <name>         # Scaffold from template (strict/permissive/ci-only/development)

Agent SDK

Use AgentGuard programmatically in your own tooling:

npm install @red-codes/core @red-codes/events

import { createKernel } from '@red-codes/kernel';

const kernel = createKernel({ policy: './agentguard.yaml' });
const decision = await kernel.propose({
  tool: 'Bash',
  command: 'git push origin main',
});
// decision.effect === 'deny'

Policy Packs

Use pack for quick setup or extends for composition:

# Quick: single pack with the pack shorthand
pack: essentials

# Advanced: compose multiple policies
extends:
  - soc2
  - hipaa
  - ./policies/team-overrides

Pack	Description
`essentials`	Core safety: secrets, force push, protected branches, credentials, blast radius (default for new installs)
`soc2`	SOC 2 Type II access controls and change management (CC6.1, CC6.6, CC7.1-7.2)
`hipaa`	HIPAA technical safeguards for PHI protection (164.312(a)-(e))
`engineering-standards`	Balanced dev-friendly guardrails: test-before-push, format checks, safe deps
`ci-safe`	Strict CI/CD pipeline protection
`enterprise`	Full enterprise governance
`strict`	Maximum restriction — all 24 invariants enforced
`open-source`	OSS contribution-friendly defaults

Community & Updates

Stay in the loop and connect with other AgentGuard users:

Sign up for early access — cloud dashboard, team governance, real-time telemetry
GitHub Discussions — ask questions, share setups, give feedback
Issues — bug reports and feature requests

From the CLI:

agentguard cloud signup    # Open cloud early access signup
agentguard cloud login     # Connect after you have an API key

Links

Resource	URL
Dashboard	agentguard-cloud-dashboard.vercel.app
Live Office	agentguard-cloud-office-sim.vercel.app — watch our swarm build software 24/7
Website	agentguardhq.github.io/agentguard
Docs	docs/
Architecture	docs/unified-architecture.md
Hook design	docs/hook-architecture.md
Event model	docs/event-model.md
Roadmap	ROADMAP.md
Contributing	CONTRIBUTING.md
Issues	github.com/AgentGuardHQ/agentguard/issues

License

Apache 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 1,405 Commits
.agent		.agent
.agentguard		.agentguard
.claude		.claude
.codex		.codex
.gemini		.gemini
.github		.github
.worktrees		.worktrees
apps		apps
docs		docs
examples		examples
go		go
hooks		hooks
logs		logs
npm-wrapper/aguard		npm-wrapper/aguard
packages		packages
paper		paper
policies		policies
policy		policy
scripts		scripts
site		site
spec		spec
templates		templates
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
TEST_COVERAGE_ANALYSIS.md		TEST_COVERAGE_ANALYSIS.md
agentguard.yaml		agentguard.yaml
eslint.config.js		eslint.config.js
package.json		package.json
plan.md		plan.md
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
swarm-state.json		swarm-state.json
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
vitest.workspace.ts		vitest.workspace.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Get Started

Cloud Dashboard & Live Office

Agent Identity

What It Does

Policy Format (YAML)

Minimal policy

Enforcement Modes

Full schema reference

Supported rule fields

Built-in Invariants

Architecture

Go Kernel — Performance

For Teams and Enterprise

CLI Reference

Agent SDK

Policy Packs

Community & Updates

Links

License

About

Uh oh!

Releases 30

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Get Started

Cloud Dashboard & Live Office

Agent Identity

What It Does

Policy Format (YAML)

Minimal policy

Enforcement Modes

Full schema reference

Supported rule fields

Built-in Invariants

Architecture

Go Kernel — Performance

For Teams and Enterprise

CLI Reference

Agent SDK

Policy Packs

Community & Updates

Links

License

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 30

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages