Skip to content
Open Source · Apache 2.0 · GitHub stars npm downloads

Governed Action Runtime for AI Coding Agents

Every tool call your AI agent makes — file writes, shell commands, git operations — passes through a deterministic governance kernel. 21 safety invariants. 87 destructive patterns. Full audit trail.

Get Started View on GitHub
0
Tests
0
Destructive Patterns
0
Event Kinds
0
Action Types
0
Invariants
0
CLI Commands

What AgentGuard Prevents

Real scenarios blocked by the governance kernel. No configuration required.

Secret Leakage
Agent writes API keys to .env
× DENIED
CRITICAL no-secret-exposure
Destructive Command
Agent runs rm -rf node_modules/
× DENIED
HIGH destructive pattern #14
Untested Push
Agent pushes to main without tests
× DENIED
HIGH protected-branch + test-before-push
Script Injection
Agent alters package.json scripts
× DENIED
HIGH no-package-script-injection

The Problem

  • AI agents execute file writes, shell commands, and git operations with no governance layer
  • One bad tool call can push to main, leak secrets, or delete production files
  • No audit trail means no way to understand what happened or why
  • Traditional AI safety focuses on model behavior, not execution-layer enforcement

The Solution

  • Deterministic decision point between proposal and execution
  • YAML policies declare what agents can and cannot do — version-controlled boundaries
  • 21 built-in invariants + 87 destructive patterns detected automatically
  • Pre-execution simulation predicts impact before anything runs

Built for Safety at Scale

Everything you need to govern AI agent actions in development, CI, and production environments.

21 Safety Invariants

Secret detection, credential protection, branch guards, blast radius limits, lockfile integrity, script injection, CI/CD protection, network egress control, governance self-modification prevention. Always on.

87 Destructive Patterns

rm -rf, sudo, docker prune, DROP TABLE, pkill, systemctl—detected and classified by the AAB before execution.

Deterministic Kernel

Same action + same policy = same decision. Every time. No probabilistic surprises.

Impact Simulation

Filesystem, git, and package simulators predict blast radius and risk level before execution.

YAML Policies

Version-controlled boundaries. Compose multiple policies with precedence. 7 built-in policy packs.

Full Audit Trail

49 event kinds across JSONL or SQLite. Inspect, replay, export, diff, and attach evidence to PRs.

Escalation System

NORMAL → ELEVATED → HIGH → LOCKDOWN. Repeated violations trigger automatic lockdown.

RTK Token Optimization

Integrated with RTK for 60-90% token savings. Shell commands auto-rewrite to compact output after governance approval. Git, npm, cargo, docker, kubectl, and more.

Kernel Architecture

Every agent action passes through a governed pipeline. Seven stages, deterministic outcome.

Propose
Agent action
Normalize
AAB mapping
Evaluate
Policy rules
Invariants
20 safety checks
Simulate
Impact forecast
Execute / Deny
Final decision
Emit
49 event kinds

The kernel is the single decision point. Same action + same policy = same outcome. No side channels, no probabilistic evaluation, no exceptions.

Action Authorization Boundary

The AAB normalizes raw tool calls into 23 canonical action types across 8 classes. Every agent operation—whether a Bash command, file write, or git push—gets classified before evaluation.

Simulation Engine

Three simulators (filesystem, git, package) predict impact before execution. High-risk simulations can flip ALLOW → DENY at runtime. Blast radius scored 0–100.

Escalation State Machine

Tracks denial and violation counts. Escalation levels persist as state-change events. In LOCKDOWN, all actions are denied until a human resets the state.

20 Built-in Invariants

Safety checks that run on every action. Zero configuration. Always on.

Invariant Severity Description
no-secret-exposure CRITICAL Blocks access to .env, credentials, .pem, .key files
no-credential-file-creation CRITICAL Blocks creation of SSH keys, .netrc, cloud credentials, Docker config
protected-branch HIGH Prevents direct push to main/master
no-force-push HIGH Forbids force push that rewrites shared history
no-skill-modification HIGH Prevents modification of .claude/skills/ files
no-scheduled-task-mod HIGH Prevents modification of scheduled task files
no-package-script-injection HIGH Blocks package.json modifications that alter lifecycle script entries
blast-radius-limit MEDIUM Enforces file modification limit (default 20 files)
test-before-push MEDIUM Requires tests pass before git push
lockfile-integrity LOW Ensures package.json changes sync with lockfiles
no-cicd-config-modification CRITICAL Prevents modification of CI/CD pipeline configurations
no-governance-self-modification CRITICAL Prevents agents from modifying governance config and policy files
no-permission-escalation HIGH Blocks filesystem permission escalation (setuid, sudoers, ownership)
transitive-effect-analysis HIGH Detects scripts whose contents would be denied if executed directly
no-network-egress HIGH Denies HTTP requests to non-allowlisted domains
no-destructive-migration MEDIUM Flags migration files containing DROP, TRUNCATE, or destructive DDL
large-file-write MEDIUM Enforces file write size limits to prevent data dumps
no-container-config-modification MEDIUM Blocks modification of Dockerfile and container config files
no-env-var-modification MEDIUM Prevents modification of environment variables and shell profiles
recursive-operation-guard LOW Flags recursive operations combined with write/delete actions
no-ide-socket-access HIGH Blocks access to IDE socket files (vscode-ipc-*.sock)

Quick Start

Three commands. That's it.

01 Install globally 
$ npm install -g @red-codes/agentguard
02 Install RTK for token savings (optional) 
# Homebrew (macOS/Linux) — 60-90% token savings
$ brew install rtk
# Windows: github.com/rtk-ai/rtk/releases
03 Hook into Claude Code 
$ agentguard claude-init
04 Check governance status 
$ agentguard status

Not Like Other Tools

AgentGuard operates at the execution layer — after the model decides what to do, before the action touches your system.

Category What they do What AgentGuard does
LLM Guardrails Filter model output text Governs actual tool execution
Prompt Filters Block unsafe prompts Operates after the prompt, at execution time
Static Analysis Scan code at rest Intercepts actions in real-time
Git Hooks Pre-commit / pre-push checks Governs all agent actions, not just git
Policy-as-Code Infrastructure policy (OPA, Sentinel) Agent action policy with simulation

Policy as Code

Define governance boundaries in YAML. Compose multiple policies with precedence. Drop them in your repo root.

# agentguard.yaml
id: default-policy
name: Default Safety Policy
severity: 4

rules:
  - action: git.push
    effect: deny
    branches: [main, master]
    reason: Direct push to protected branch

  - action: git.force-push
    effect: deny
    reason: Force push rewrites shared history

  - action: file.write
    effect: deny
    target: .env
    reason: Secrets files must not be modified

  - action: file.read
    effect: allow
    reason: Reading is always safe

Deny rules block dangerous actions

Prevent direct pushes to protected branches, force pushes, and secrets file modifications.

Allow rules grant explicit permission

Safe operations like file reads are explicitly allowed. Clear intent, no ambiguity.

Composable with precedence

Stack multiple policies: --policy base.yaml --policy team.yaml. Later policies take precedence.

7 built-in policy packs

Pre-built packs for common scenarios: ci-safe, enterprise, open-source, strict.

29 CLI Commands

Full lifecycle governance from your terminal.

Governance

  • guard — Start governed runtime
  • inspect — Action graph + decisions
  • events — Raw event stream
  • analytics — Violation patterns
  • status — Governance session status
  • audit-verify — Audit chain integrity

Replay & Debug

  • session-viewer — Interactive HTML dashboard
  • replay — Session timeline replay
  • diff — Compare two sessions
  • traces — Policy evaluation traces
  • simulate — Impact prediction

Portability & CI

  • export / import — Session portability
  • ci-check — CI verification
  • evidence-pr — PR evidence reports
  • policy validate — Policy linting
  • policy-verify — Structure verification

Plugins

  • plugin list — Installed plugins
  • plugin install — Add a plugin
  • plugin remove — Remove a plugin
  • plugin search — Search npm

Setup & Integration

  • claude-init — Claude Code hooks
  • copilot-init — GitHub Copilot hooks
  • cloud connect — Connect to AgentGuard Cloud
  • cloud events/runs — Query cloud data
  • auto-setup — Auto-detect & configure
  • config — Show/get/set config
  • init — Scaffold extensions
  • demo — Interactive showcase

Adoption & Migration

  • adoption — Metrics & onboarding
  • learn — Interactive tutorials
  • migrate — Version migration

Claude Code Mapping

  • Write/Edit → file.write
  • Read → file.read
  • Bash → shell.exec / git.*
  • Glob/Grep → file.read

Agent Swarm

Deploy a coordinated team of governed AI agents. 26 agents across 5 tiers, each with dedicated skills, schedules, and governance policies.

26 Agents
5 Tiers
60+ Skills
24 Prompts
Autonomous SDLC Swarm — Control Plane architecture diagram showing 5 tiers of governed AI agents connected to a central control plane with recovery controller escalation states

Core

7 agents
  • Implementation — Picks issues, codes, opens PRs
  • Code Review — Reviews open PRs
  • PR Merger — Auto-merges approved PRs
  • CI Triage — Diagnoses failing CI
  • Conflict Resolver — Fixes merge conflicts
  • PR Responder — Addresses review comments
  • Branch Janitor — Cleans stale branches

Governance

3 agents
  • Risk Escalation — Assesses cumulative risk
  • Recovery Controller — Self-healing playbooks
  • Governance Monitor — Audits governance logs

Ops

8 agents
  • Planning — Sprint planning from backlog
  • Observability — Monitors runtime health
  • Backlog Groomer — Triages stale issues
  • Docs — Keeps docs in sync
  • Product Health — Dependency & coverage checks
  • Progress Controller — Tracks sprint velocity
  • Repo Hygiene — Labels, templates, configs
  • Retrospective — Weekly retrospectives

Quality

7 agents
  • Testing — Runs & expands test suites
  • Test Generation — Generates new tests
  • Security Audit — Scans for vulnerabilities
  • Architecture Review — Detects drift & debt
  • CI/CD Hardener — Strengthens pipelines
  • PR Audit — Audits merged PRs
  • Infra Health — Infrastructure checks

Marketing

1 agent
  • Content Agent — Changelogs, social posts & community engagement from project activity

Quick Start

Scaffold all tiers:

agentguard init swarm

Select specific tiers:

agentguard init swarm \
  --tiers core,governance

Install with npm install -g @red-codes/agentguard. Generates .claude/skills/, agent prompts, and agentguard-swarm.yaml config.

Post-Setup — Required

Scaffolding generates the files, but agents still need to be configured in Claude Desktop before they can run:

  1. Create scheduled tasks — Register each agent as a scheduled task in Claude Desktop using the cron schedules from the agent manifest.
  2. Set worktree: true — Enable worktree isolation so parallel agents get their own git worktree and don't conflict on file writes or git state.
  3. Bypass permissions manually — Agents run unattended with no human to approve prompts. Pre-approve the required tool permissions (file, shell, git) in Claude Desktop for each agent.

AgentGuard's governance policy + invariant system enforces safety boundaries even with permissions bypassed.

Integrations

Governance where your agents already work.

Claude Code

Inline hook integration — no daemon, no sidecar. Fires on every tool call, evaluates policies in-process, and exits. Fail-open by design.

$ agentguard claude-init
PreToolUse PostToolUse SessionStart

GitHub Copilot

Same governance engine for Copilot CLI. Tool names normalized to canonical actions. All policies and invariants apply identically.

$ agentguard copilot-init
preToolUse postToolUse

VS Code Extension

Sidebar panels for run status and history. Inline diagnostics for invariant violations. Real-time governance notifications.

Run Status Inline Diagnostics Notifications

GitHub Actions

Reusable CI workflow for governance verification. Evidence packs attached to pull requests. Policy validation in your pipeline.

ci-check evidence-pr policy validate

Audit-Ready by Design

Deterministic governance produces verifiable evidence. Every decision is recorded, queryable, and exportable.

JSONL + SQLite

Append-only audit trail with indexed queries. Portable JSONL export for CI and archival.

Deterministic Decisions

Same action + same policy = same decision. No probabilistic evaluation. Reproducible outcomes.

Evidence Packs on PRs

Attach governance evidence summaries to pull requests. Provable compliance in code review.

Policy Composition

Org-wide base + team overrides. 4 built-in packs: ci-safe, enterprise, open-source, strict.

Session Replay & Diff

Replay any governance session. Compare runs side-by-side. Forensic analysis built in.

Session Viewer

Interactive HTML dashboard with action timeline, escalation progression, and violation breakdown. Auto-opens when a Claude Code session ends. Shareable via --share.

Export & Portability

Export sessions as portable JSONL. Import across environments. CI-ready verification.

What’s Next

AgentGuard is evolving from advisory interception to mandatory execution control. Here’s the trajectory.

ACTIVE

Rust Kernel — crates/kernel-core/

Native governance kernel in Rust for lower latency and smaller footprint. Early development — the TypeScript kernel remains the production implementation.

NEXT

Phase 6 — Reference Monitor Hardening

Default-deny unknown actions. Enforce PAUSE and ROLLBACK intervention types. Close all bypass vectors.

PLANNED

Phase 7 — Capability-Scoped Sessions

Each governance run gets a bounded authority set via RunManifest. No capability, no effect.

PLANNED

Phase 9 — Multi-Agent Integrations

Framework adapters for LangGraph, CrewAI, AutoGen, OpenAI Agents SDK. Generic MCP adapter. Cursor integration.

PLANNED

Phase 13 — Environmental Enforcement

OS-level sandboxing via Bubblewrap and Seatbelt. Read-only mounts, network deny-by-default, credential stripping.

PLANNED

Phase 14 — Multi-Agent Governance

Agent identity verification, PID-bound capability tokens, cross-agent policy, fleet orchestration.

PLANNED

Phase 18 — Remote Governance Runtime

Server mode, centralized event ingestion, remote policy distribution, multi-repo governance, team dashboard.

Full roadmap (18 phases)

Open Source

Apache 2.0 Licensed

AgentGuard is built in the open. Write invariants, create policy packs, build adapters, or contribute a renderer.

Contributing Guide Report Issues Star on GitHub