agentguard-governance 0.10.0

Governance layer for autonomous AI agents — pre-flight checks, runtime monitoring, and post-session reporting.

AgentGuard

Governance layer for autonomous AI agents — pre-flight checks, runtime monitoring, and post-session reporting.

"You wouldn't launch a rocket without a pre-launch checklist. Why run an autonomous agent without one?"

Maximum instruction, minimum interpretation.

AgentGuard doesn't eliminate the probability of failure. It reduces the impact.

---

The Problem: Observability vs Governance — the Gap

The AI agent tooling landscape is rich with observability tools — LangSmith, Langfuse, Helicone, Arize. They answer: "What did the agent do?"

But they don't answer: "Should the agent have started at all?"

AgentGuard fills the gap before execution: it checks that governance prerequisites are in place, monitors for loops and stalls at runtime, and produces a post-session governance report.

Read the full context: The Blind Spot of Agentic AI Systems

---

AgentGuard vs Observability Tools

Feature	LangSmith	Langfuse	Helicone	Arize	AgentGuard
Pre-flight governance check	—	—	—	—	Yes
Owner / scope / escalation enforcement	—	—	—	—	Yes
Killswitch verification	—	—	—	—	Yes
Instruction file validation	—	—	—	—	Yes
Runtime loop detection	Partial	—	—	Partial	Yes
Post-session governance report	—	Partial	—	—	Yes
Token / cost monitoring	Yes	Yes	Yes	Yes	Threshold
Trace visualization	Yes	Yes	—	Yes	—
Prompt replay / debugging	Yes	Yes	—	—	—
Works with any agent framework	—	—	—	—	Yes

AgentGuard is not a replacement for observability tools — it is the layer that runs before they do.

---

Prerequisite Level 0: The "Fuel in the Car" Metaphor

Before you drive, you check: fuel, seatbelt, mirrors. These are non-negotiable prerequisites — you don't skip them because you're in a hurry.

AgentGuard's Level 0 checks are the equivalent for autonomous agents:

Check	What it verifies
OWNER	Someone is responsible for this agent
SCOPE	The agent knows what it's allowed to do
ESCALATION	There is a human to contact when things go wrong
KILLSWITCH	There is a documented way to stop the agent

These are CRITICAL by default. An agent without an owner is an unaccountable system. An agent without a killswitch is a runaway process waiting to happen.

---

Quick Start

pip install agentguard-governance
cd my-agent-project
agentguard check

If your project lacks governance prerequisites, you'll see:

╭─────────── AGENTGUARD — PRE-FLIGHT CHECK ────────────╮
│   Project:  ./my-agent-project                       │
│   Checked:  2026-06-06 15:00:00                      │
│                                                      │
│   🔴 CRITICAL   No agent owner defined               │
│   🔴 CRITICAL   No authorized scope defined          │
│   🔴 CRITICAL   No prohibited actions defined        │
│   🔴 CRITICAL   No escalation path configured        │
│   🔴 CRITICAL   No killswitch defined                │
│   🔴 CRITICAL   No CLAUDE.md or AGENTS.md found      │
│                 (fix: create CLAUDE.md first)        │
│                                                      │
│   RESULT: BLOCKED — 6 critical gaps                  │
│                                                      │
│   This agent cannot start until governance           │
│   gaps are resolved or explicitly overridden.        │
│                                                      │
│   agentguard init --interactive                      │
│   agentguard override --reason "..."                 │
╰──────────────────────────────────────────────────────╯

Fix it interactively:

agentguard init --interactive

---

How It All Works Together

After agentguard init --guided, three things are in place:

1. Claude Code reads your governance automatically CLAUDE.md is read by Claude Code at the start of every session. AgentGuard adds your governance rules to this file — so Claude knows what it's allowed to do before it starts.

2. Every tool call is enforced .claude/settings.json wires agentguard enforce as a PreToolUse hook. Before Claude executes any Bash command, file write, or edit — AgentGuard checks it against your governance.yaml. Prohibited actions are blocked. Period.

3. You own the governance governance.yaml is your source of truth. Review it, update it with agentguard review, verify it with agentguard verify.

Think of it this way:

• CLAUDE.md tells Claude what the rules are
• agentguard enforce makes sure it can't break them
• governance.yaml is where you define both

Without step 1, Claude knows no boundaries. Without step 2, boundaries are suggestions, not enforcement. Without step 3, nothing is reproducible.

All three together — that's the foundation.

Session Logging (automatic)

Every tool call Claude Code makes is automatically logged to .agentguard/session.log in your project directory — written by the PreToolUse hook without any configuration required.

# Watch live in terminal
agentguard watch

# Watch in browser UI
agentguard web  # → Live Watch tab

.agentguard/ is gitignored — session logs are runtime data, not version-controlled.

What gets logged:

• Timestamp, tool name, input summary
• Decision: allow or deny
• Reason if denied (governance rule violated)
• Session ID for correlation

---

CLI Commands

agentguard check

Run a pre-flight governance check.

agentguard check                          # check current directory
agentguard check --path ./my-project      # check a specific path
agentguard check --config ./gov.yaml      # use a specific governance.yaml
agentguard check --format json            # machine-readable output
agentguard check --ai-review              # include AI-powered scope quality review

Exit codes:

• 0 — OK or warnings only (with or without AI review)
• 1 — CRITICAL findings found
• 2 — Config error

--ai-review requires AGENTGUARD_AI_PROVIDER and AGENTGUARD_AI_API_KEY in .env or environment. Without them, AI review is silently skipped.

---

agentguard init

Initialize governance for a project.

agentguard init --guided        # AI-powered 5-step concretization (requires API key)
agentguard init --interactive   # guided Q&A with inline examples,
                                # generates governance.yaml + CLAUDE.md block
agentguard init --template-only # copies governance.yaml.example to ./governance.yaml

Interactive mode guides you through:

• Agent owner, scope (authorized / prohibited / confirmation-required)
• Escalation contact with format validation
• Escalation method (log / terminal / file)
• Killswitch definition

All free-text inputs are sanitized — quote characters are stripped automatically to prevent YAML parse errors.

---

agentguard init --guided

AI-powered 5-step guided concretization. Answer 5 questions in plain language — AgentGuard uses an AI provider to transform your intent into enforceable rules.

agentguard init --guided

Requires AGENTGUARD_AI_PROVIDER and AGENTGUARD_AI_API_KEY in .env. Without them, use agentguard init --interactive instead.

What it does:

1. Owner — who is responsible for this session
2. Mission — free-text description → AI splits into authorized / prohibited / confirmation scope
3. Hard Limits — things the agent must never do → AI adds to prohibited scope
4. Escalation — how to reach you when something goes wrong
5. Killswitch — how to stop the agent

After all 5 steps, a review panel shows the full governance before saving. You can adjust individual fields or start over.

Adjustment loop: Each AI-concretized field offers up to 3 rounds of refinement. If the AI cannot improve further, your raw input is saved with a warning.

What gets written:

• governance.yaml — with metadata comment block (Generated by: agentguard init --guided)
• .claude/settings.json — PreToolUse hook (merge-safe)
• CLAUDE.md — AgentGuard governance block appended

Graceful degradation: API failure → raw input saved, flow continues. Ctrl+C → prompted to save progress before exiting.

---

agentguard watch

Live terminal monitor — streams every tool call in real time.

agentguard watch                              # auto-discovers .agentguard/session.log
agentguard watch --log ./my-agent.log         # watch a specific log file
agentguard watch --interval 5                 # poll interval in seconds
agentguard watch --loop-threshold 8           # custom loop detection threshold

Output:

AgentGuard Watch — monitoring session activity
Press Ctrl+C to stop

  DEC  TIME      TOOL                 INPUT
  ─────────────────────────────────────────────────────
✓ 14:32:01  Read                 /src/main.py
✓ 14:32:02  Bash                 pytest --tb=short
✗ 14:32:05  Bash                 rm -rf dist → HARD_LIMIT: ...
[LOOP_WARNING] Tool 'Bash' called 6x — possible loop

Also emits LOOP_WARNING, STALL_WARNING, and BURN_WARNING events and appends them to agentguard.log.

---

Live Watch

AgentGuard provides real-time monitoring of every tool call Claude Code makes during a session.

Terminal

cd my-project
agentguard watch

Output:

AgentGuard Watch — monitoring session activity
Press Ctrl+C to stop

  DEC  TIME      TOOL                 INPUT
  ─────────────────────────────────────────────
✓ 14:32:01  Read                 /src/main.py
✓ 14:32:02  Bash                 pytest --tb=short
✗ 14:32:05  Bash                 rm -rf dist → HARD_LIMIT: ...
[LOOP_WARNING] Tool 'Bash' called 6x — possible loop

Browser

agentguard web  # → Live Watch tab

Identical feed to the terminal — live updates via WebSocket.

Session log location

All tool calls are written to .agentguard/session.log in your project directory. The file is created automatically on the first Claude Code tool call.

Loop detection

AgentGuard warns when the same tool is called repeatedly:

• Default threshold: 6 calls in a 10-call window
• Override: agentguard watch --loop-threshold 8

Understanding Loop and Stall Detection

AgentGuard uses a sliding window of the last 10 tool calls to detect anomalies:

LOOP_WARNING — same tool called too often:

Window: [Bash, Bash, Read, Bash, Bash, Bash, Bash, ...]
→ Bash appears 6+ times in last 10 calls → LOOP_WARNING

STALL_WARNING — too little diversity:

Window: [Bash, Bash, Bash, Bash, Bash, Bash, Bash, Bash, Bash, Bash]
→ Only 1 unique tool in last 10 calls → STALL_WARNING

What is normal?

Task type	Expected pattern
Research / exploration	5-8 Bash calls in sequence — normal
File editing	Mix of Read, Write, Bash — low repetition
Testing	pytest called multiple times — can be legitimate
Code analysis	find, grep, cat in sequence — normal

When to act on a warning:

• Single WARNING during a long task → likely normal, monitor
• Repeated WARNINGs without progress → agent may be stuck
• STALL_WARNING → high chance of loop, consider stopping

Adjust the threshold for your workflow:

# More sensitive — warn earlier
agentguard watch --loop-threshold 4

# Less sensitive — allow more repetition
agentguard watch --loop-threshold 10

The right threshold depends on your project and task type. Start with the default (6) and adjust based on experience.

---

agentguard report

Generate a post-session Markdown governance report.

agentguard report                                      # reads agentguard.log, writes report.md
agentguard report --session ./run1.log --output r.md   # custom paths

---

agentguard review

Review and update existing governance.yaml interactively.

agentguard review                          # interactive field-by-field review
agentguard review --guided                 # AI-assisted rule concretization
agentguard review --field authorized       # review a specific field only
agentguard review --path ./my-project      # review a project in another directory

Shows a summary of current governance, then offers:

• Review all fields — walk through each scope field, keep/add/remove/replace rules
• Review specific field — focus on one field
• Add new rules — append to an existing field
• Mark ambiguities as resolved — close open ambiguities with an audit timestamp
• View full governance.yaml — Rich syntax-highlighted display

All changes are logged in governance_history with the date, tool, and changed fields.

---

agentguard override

Override CRITICAL findings and proceed. The --reason flag is mandatory and the override is logged.

agentguard override --reason "Emergency hotfix — owner notified verbally"
agentguard override --reason "Demo environment — no real escalation needed" --path ./demo

Override log is written to agentguard-overrides.log.

---

agentguard verify

Checks that your governance.yaml was generated consistently and has not drifted since creation.

agentguard verify                    # verify current directory
agentguard verify --path ./project   # verify specific project
agentguard verify --repair           # repair missing pins

How it works

When agentguard init --guided runs, it records concretization pins in governance.yaml — SHA-256 hashes of the exact prompt and output used during AI concretization:

concretization_pins:
  - field: "mission"
    input_hash: "a1b2c3d4e5f6g7h8"
    prompt_hash: "b2c3d4e5f6g7h8i9"
    output_hash: "c3d4e5f6g7h8i9j0"
    model: "claude-sonnet-4-20250514"
    provider: "anthropic"
    temperature: 0
    date: "2026-06-11"

agentguard verify checks that all pins are present and valid.

Exit code	Meaning
0	All pins verified — governance is reproducible
1	Pin issues found — missing, incomplete, or temperature drift
2	governance.yaml not found

When to run

• Before starting a critical Claude Code session
• After model updates (check for drift)
• As part of CI/CD governance gate
• After agentguard review to verify updated fields

---

agentguard verify --repair

Generates baseline pins for projects that have no pins.

When you need it

Pins are only created by agentguard init --guided. If you have a governance.yaml without pins — because you used agentguard init --interactive, created it manually, or migrated from an older version — agentguard verify will report missing pins.

--repair fixes this without requiring a full re-initialization:

agentguard verify --repair

✅ Repaired 2 pin(s) — baseline created
   🔧 mission — pinned as baseline
   🔧 hard_limits — pinned as baseline

What repair does

Repair does not call any AI model. It hashes the existing content of your governance.yaml and stores that hash as a baseline pin.

This means:

• agentguard verify will pass after repair
• Future changes to governance will be detectable
• Repaired pins are marked repaired: true to distinguish them from AI-generated pins

Repair vs. re-init

	verify --repair	init --guided
AI call	No	Yes
Existing governance	Preserved	Overwritten
Pin quality	Baseline only	Full AI concretization
Use when	Already have governance.yaml	Starting from scratch

Web UI

Both verify and repair are available in the browser: agentguard web → Verify Pins tab → Run Verify / 🔧 Repair Pins

---

Consistency & Reproducibility

When agentguard init --guided generates governance rules, it records prompt-pins alongside each concretized field:

concretization_pins:
  - field: "mission"
    input_hash: "abc123def456abcd"
    prompt_hash: "def456abc123ef01"
    output_hash: "1234567890abcdef"
    model: "claude-sonnet-4-20250514"
    provider: "anthropic"
    temperature: 0
    date: "2026-06-09"

This answers: "How were these governance rules generated — and can we reproduce them?"

The hashes are SHA-256 truncated to 16 chars for readability. They don't re-verify the AI output automatically (the AI is non-deterministic even at temperature=0 across versions), but they document the exact conditions under which governance was created. Use agentguard verify to check structural integrity.

---

How AgentGuard Works — Four Layers

Layer 1 — Before the agent starts (Pre-Flight)

agentguard check validates governance prerequisites. agentguard check --ai-review adds AI-powered scope quality scoring.

Layer 2 — While the agent runs (Enforcement)

agentguard enforce runs as a Claude Code PreToolUse hook. Deterministic — no LLM. Checks every tool call against governance.yaml. Exit 2 = blocked. Exit 0 = allowed.

Layer 3 — Monitoring (Runtime Watch)

agentguard watch reads native Claude Code JSONL transcripts. Detects loops, stalls, and token burn in real time.

Layer 4 — After the session (Reporting & Audit)

agentguard report generates a Markdown governance report. agentguard verify checks governance consistency via prompt pins. agentguard review updates governance for changed projects.

---

Complete Command Reference

Command	Purpose	Requires API Key
agentguard check	Pre-flight governance validation	No
agentguard check --ai-review	+ AI scope quality scoring	Yes
agentguard init --interactive	Basic guided setup	No
agentguard init --guided	AI-concretized governance setup	Yes
agentguard enforce	PreToolUse hook handler	No
agentguard watch	Live terminal monitor — all tool calls + loop/stall/burn warnings	No
agentguard watch --loop-threshold 8	Custom loop detection threshold	No
agentguard report	Post-session governance report	No
agentguard review	Update existing governance	No
agentguard review --guided	AI-assisted governance update	Yes
agentguard verify	Check governance consistency/drift	No
agentguard override	Proceed despite critical gaps	No
agentguard web	Browser UI — check, governance, terminal	No (API key optional)
agentguard web --path p1 --path p2	Multi-project browser UI	No

---

AI-Powered Scope Review (Optional)

AgentGuard can use an AI provider to assess the quality of your governance scope — catching vague, incomplete, or ungovernable definitions that string-based checks miss.

Model selection: AgentGuard uses different models for different tasks:

• Scope review (--ai-review): provider default (e.g. claude-haiku, gpt-4o-mini)
• Governance concretization (--guided): higher-capability model (claude-sonnet for Anthropic, gpt-4o for OpenAI) for schema reliability
• All concretization calls use temperature=0 for consistency

API Key Setup

Option 1: Project-level .env (recommended for per-project keys)

cd my-agent-project
cat > .env << 'EOF'
AGENTGUARD_AI_PROVIDER=anthropic
AGENTGUARD_AI_API_KEY=your-api-key-here
EOF

Option 2: Global config (works across all projects)

mkdir -p ~/.agentguard
cat > ~/.agentguard/.env << 'EOF'
AGENTGUARD_AI_PROVIDER=anthropic
AGENTGUARD_AI_API_KEY=your-api-key-here
EOF

Option 3: Environment variables

# Add to ~/.zshrc
export AGENTGUARD_AI_PROVIDER=anthropic
export AGENTGUARD_AI_API_KEY=your-api-key-here

Priority: environment variables → project .env → global config. Project-level always overrides global — local settings win.

Setup

Supported providers:

Provider	Value	Default Model
Anthropic	anthropic	claude-haiku-4-5-20251001
OpenAI	openai	gpt-4o-mini
Anysphere (Cursor)	anysphere	cursor-small
OpenAI-compatible	openai-compatible	set AGENTGUARD_AI_MODEL

Model Selection for Concretization

AgentGuard uses different models for different tasks:

Task	Default Model	Override
Scope quality review (--ai-review)	claude-haiku-4-5	AGENTGUARD_AI_MODEL
Governance concretization (--guided)	claude-sonnet-4-6	AGENTGUARD_MISSION_MODEL

Upgrade to Claude Fable 5 for maximum concretization quality:

# In .env
AGENTGUARD_MISSION_MODEL=claude-fable-5

Claude Fable 5 (June 9, 2026) is Anthropic's first publicly available Mythos-class model — the tier above Opus. It delivers significantly better results on complex, multi-step governance definitions. Priced at $10/$50 per million tokens (2× Sonnet).

Free on Anthropic Pro/Max/Team plans until June 22, 2026.

Usage

agentguard check --ai-review

AI review is always opt-in. Without --ai-review, AgentGuard runs fully offline with no API calls and no external dependencies.

---

How AgentGuard Enforces — Layer 2

After agentguard init, your project contains .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash|Write|Edit|MultiEdit|NotebookEdit",
      "hooks": [{"type": "command", "command": "agentguard enforce"}]
    }]
  }
}

Every tool call Claude Code attempts fires agentguard enforce first. AgentGuard reads your governance.yaml and checks:

• Does this action violate the prohibited scope?
• Does this action require human confirmation?

If yes → exit 2. Claude Code receives the denial reason and cannot proceed with that action. This is deterministic — it fires every time, regardless of model behavior or context length.

All enforcement decisions are logged to agentguard-enforcement.log.

What AgentGuard cannot do

AgentGuard enforces at the tool execution layer. It cannot prevent Claude from reasoning toward a blocked action — only from executing it. For production systems, combine with OS-level sandboxing.

See What AgentGuard Cannot Do for the full list.

---

governance.yaml Reference

# Required (CRITICAL if missing)
owner: "Jane Smith"

scope:
  authorized:
    - action: "Read and write Python files in ./src"
      reason: "Core task — agent must modify source files"
      added: "2026-06-07"

  prohibited:
    - action: "No database schema changes or production writes"
      reason: "Production data changes require human review — no exceptions"
      severity: "HARD_LIMIT"
      added: "2026-06-07"
    - action: "No git push to main branch"
      reason: "All changes must go through pull request review"
      severity: "HARD_LIMIT"
      added: "2026-06-07"

  requires_confirmation:
    - action: "Any file deletion outside ./tmp"
      reason: "File deletion is irreversible — requires explicit sign-off"
      added: "2026-06-07"

escalation:
  contact: "[e-mail]"
  method: "log"              # log | terminal | file
  trigger: "2+ critical failures or loop detected"

killswitch: "Ctrl+C"

governance_history:
  - date: "2026-06-09"
    action: "Initial governance created"
    tool: "agentguard init --guided"
    version: "0.5.1"

# Concretization consistency (added by agentguard init --guided)
concretization_pins:
  - field: "mission"
    input_hash: "a1b2c3d4e5f6g7h8"
    prompt_hash: "b2c3d4e5f6g7h8i9"
    output_hash: "c3d4e5f6g7h8i9j0"
    model: "claude-sonnet-4-20250514"
    provider: "anthropic"
    temperature: 0
    date: "2026-06-09"

# Severity overrides (critical | warning | info)
severity:
  no_owner: critical
  no_scope: critical
  no_escalation: critical
  no_killswitch: critical
  no_instruction_file: critical
  no_loop_detection: warning
  no_root_cause_rule: warning
  no_api_research_rule: info
  no_attempt_counter: warning
  no_action_log: warning
  no_skill_md: warning

# Runtime thresholds
runtime:
  loop_threshold: 2
  progress_check_interval: 10
  token_burn_threshold: 5000
  progress_scoring: false        # requires ANTHROPIC_API_KEY

# Override policy
override:
  allowed: true
  require_reason: true
  log_overrides: true

Why structured governance matters

Each governance rule includes:

• action — what is allowed, prohibited, or requires confirmation
• reason — why this decision was made (critical for future reference)
• severity — HARD_LIMIT, CRITICAL, or WARNING (prohibited rules only)
• added — when the rule was created

Six months from now — after staff changes, project handovers, or simply forgetting — the reason field answers: "What did we mean by this?"

Governance without context is a checklist. Governance with context is institutional memory.

Legacy flat-string format is still supported for backward compatibility.

---

What AgentGuard Checks

Level 0 — Governance Prerequisites (CRITICAL)

Check	Rule
Owner	governance.yaml has non-empty owner field
Scope	governance.yaml has non-empty scope field
Escalation	governance.yaml has escalation.contact field
Killswitch	governance.yaml has killswitch field
Instruction file	CLAUDE.md or AGENTS.md present in project root
security.md absent	INFO — consider documenting security policies

Prompt Quality (WARNING)

Check	Keywords scanned in CLAUDE.md / AGENTS.md
Loop detection	loop, iteration, attempt, stuck, retry
Root-cause analysis	root cause, root_cause, diagnose before, confirm before
External API research	fetch, documentation, never rely on memory, aktuelle

Harness Quality (WARNING)

Check	Patterns scanned in *.py files
Attempt counter	attempt_count, retry_count, max_attempts
Action log	action_log, log_action, append.*log
Error pattern detection	same_error, error_pattern, consecutive_errors

---

Governance Review Cycle

Governance defined today may not fit your project in three months. agentguard review ensures governance stays current.

# Review all governance fields interactively
agentguard review

# Review with AI-assisted concretization
agentguard review --guided

# Review a specific field only
agentguard review --field authorized

# Review a project in another directory
agentguard review --path ./my-project

Use agentguard review when:

• The project scope has changed significantly
• Team members have changed (handover situation)
• Unresolved ambiguities need to be addressed
• A governance audit is due
• The agent produced unexpected results

All changes are logged in governance_history — full audit trail of when governance changed, what changed, and which tool was used.

---

Pre-Inquiry — Quality In, Quality Out

The quality of your governance is directly proportional to the quality of your preparation.

AgentGuard cannot fill knowledge gaps — it exposes them. The owner bears responsibility for what they define.

Before running agentguard init --guided, know:

• Which directories and files the agent may touch
• Which external APIs or services are involved
• What success looks like — in measurable terms
• Who is accountable when something goes wrong
• What the agent must never do — without exceptions

Vague input produces vague governance. Vague governance produces unenforceable rules. Unenforceable rules produce incidents.

---

What AgentGuard Cannot Do

• Guarantee model behavior — AgentGuard enforces at the tool execution layer. It cannot prevent Claude from reasoning toward a blocked action, only from executing it.
• Fill knowledge gaps — Ambiguities in your governance definition reflect real gaps in your understanding of the agent's scope. AgentGuard documents them; you must resolve them.
• Replace security practices — For production systems, combine AgentGuard with OS-level sandboxing (Docker, seccomp, file ACLs).
• Enforce on non-hook frameworks — Enforcement requires Claude Code hooks. For other frameworks, use agentguard enforce manually in your own harness.

---

Regulatory Alignment

AgentGuard is designed to be compatible with:

• Singapore IMDA Model Governance Framework — human oversight, accountability, and documentation requirements
• Anthropic — Building Effective Agents — loop detection, progress monitoring, and controlled escalation
• EU AI Act GPAI provisions (effective August 2, 2026) — transparency, human oversight, and risk management for general-purpose AI systems

AgentGuard does not provide legal compliance. It provides the technical prerequisites that compliance frameworks require.

---

Web Interface

pip install "agentguard-governance[web]"
agentguard web

Opens http://localhost:8767 with:

Tab	Purpose
Pre-Flight Check	Run governance validation, see results visually
Governance	View all governance rules with color-coded sections
Verify Pins	Check concretization consistency — Repair Pins button for brownfield projects
Session Report	Post-session governance summary with tool distribution, blocked actions, and warnings
Terminal	Run any agentguard command interactively
Setup Governance	Guided, interactive, or template setup
Review & Update	Update governance as project evolves

All commands including interactive ones (init --guided, review --guided) run directly in the browser terminal. Click "▶ Run in Terminal" in Setup or Review to launch any command without leaving the browser.

agentguard web                                    # single project (current dir)
agentguard web --path ./my-project                # specific project
agentguard web --path ./proj1 --path ./proj2      # multiple projects
agentguard web --port 8888                        # custom port
agentguard web --no-browser                       # don't auto-open browser

Multiple projects: pass --path multiple times. The sidebar shows a project switcher — all panels update when you switch projects. Projects with governance.yaml show ✓, projects without show ⚠.

Inline Governance Editor

The Governance tab includes a built-in editor:

1. Click ✏️ Edit to enter edit mode
2. Edit any rule's action or reason directly
3. Add new rules with + Add Rule
4. Delete rules with 🗑️ Delete
5. Review pending changes in the banner
6. Click Save All to write to governance.yaml

All changes are logged in governance_history with timestamp, description, and tool reference.

Requires macOS or Linux (Python pty module).

Building the web frontend

Before packaging or running from source, build the frontend:

bash scripts/build_web.sh

This builds the React app and copies it to agentguard/web/dist/ where FastAPI can serve it.

For hot-reload development:

cd web
npm install
npm run build   # builds to web/dist/ — served by FastAPI
npm run dev     # hot-reload dev server (proxies API to :8767)

---

Development

git clone https://github.com/MyPatric69/agentguard
cd agentguard
pip install -e ".[dev]"
pytest --tb=short
ruff check agentguard tests

---

License

MIT — see LICENSE for details.

---

Built for developers who believe that governance should be a first-class concern, not an afterthought.