Beta — for evaluation and testing only. AIGuard is a guardrail, not a security boundary. Read the risk disclosures
AIGuard

Execution-Layer Security for AI agents

A guardrail between your AI assistant and your shell.

AIGuard hooks into Kimi Code CLI and Claude Code via their PreToolUse hooks and evaluates every shell command against a policy — allow, ask, or block. Dangerous commands wait for an out-of-band approval that only you can give: Touch ID on macOS, TOTP elsewhere.

Install with pipx Read the docs
  • Python 3.11+
  • macOS & Linux
  • Apache-2.0
  • pipx install aiguard-gate
zsh — demo (illustrative)
kimi "clean up the build directory"
 
› Bash(ls build/)
└ aiguard: allow · risk low — runs instantly
 
› Bash(rm -rf build/)
└ aiguard: ask · risk high — command blocked
AIGUARD_CHALLENGE:9f3ac1d72e4b
approve out-of-band, in any terminal:
 
aiguard approve 9f3ac1d72e4b
Touch ID ✓ approved: rm -rf build/
single-use · bound to the exact command · expires in 5:00
 
› retry: Bash(rm -rf build/)
└ approval consumed — command runs
 
› Bash(sudo rm -rf /)
└ aiguard: block · risk critical
Absolute Block — no approval, no override
allow — proceeds ask — needs your approval block — refused, no override

How it works

Four steps between intent and execution

1

Hook intercepts

Before the assistant runs a shell command, its official PreToolUse hook pipes the command to aiguard-evaluate.

2

Policy decides

Every command gets a Decision — an action (allow / ask / block), a risk tier, and a plain-English warning.

3

You approve out-of-band

ask commands return AIGUARD_CHALLENGE:<token>. You run aiguard approve in any terminal — Touch ID on macOS, 6-digit TOTP elsewhere.

4

Assistant retries

The approval is single-use, bound to the exact command string, and expires after 5 minutes. Retry, and the command runs.

Three possible outcomes for every command

allow

Safe commands — git status, ls — proceed instantly. No friction for everyday work.

ask

Everything else is blocked with a challenge token until you approve it out-of-band. ask is the default for unrecognized commands — treat it as the normal case, not an alarm.

block

Catastrophic commands — rm -rf /, writes to ~/.aiguard/ — are refused. No override exists: not by approval, not by user policy.

Features

What the guardrail gives you

Policy engine

Built-in block → ask → allow rules, first match wins. Extend with your own patterns in ~/.aiguard/policy.toml — user allow rules can never override an Absolute Block.

Out-of-band approval

Approvals happen in a separate terminal, outside the assistant's session. The assistant relays a token; it never sees your Touch ID or TOTP.

Platform-native auth

Touch ID via LocalAuthentication on macOS. RFC 6238 TOTP with any authenticator app on Linux (and as a macOS fallback).

Absolute Blocks

Filesystem-destroying commands and writes to AIGuard's own state are refused outright. No approval and no policy can override them.

Verbatim audit log

Every evaluated command and its Decision is appended to ~/.aiguard/audit.jsonl (0600) — a complete record of what the assistant tried to run.

Local by design

No account, no cloud service, no telemetry. All state lives in ~/.aiguard/ (0700) on your machine.

Honesty section

What AIGuard does NOT do

AIGuard is a guardrail, not a sandbox. It reduces the chance that an honest-but-fallible assistant runs a dangerous command — it does not make agents safe, and it is not a security boundary.

  • Not a sandbox

    No filesystem, network, or memory isolation. An approved (or ungated) command runs with your full privileges.

  • Not adversarial-proof

    The threat model is the honest-but-fallible agent. A deliberately evasive or prompt-injected assistant that crafts obfuscated commands is out of scope and may bypass the regex-based policy.

  • Commands only

    File writes and network access performed without spawning a shell command are not gated.

  • Host platforms fail open

    Per Kimi and Claude documentation, a hook that times out or crashes allows the command (AIGuard itself always fails closed). Do not rely on AIGuard in yolo/auto-approve assistant modes, and do not use it as your only safeguard.

  • The audit log records commands verbatim

    ~/.aiguard/audit.jsonl may contain secrets passed as CLI arguments. It is 0600 — keep it that way.

Full threat model & security policy

Install

Up and running in three commands

1 · Install the CLI

pipx install aiguard-gate

# macOS Touch ID support:
pipx inject aiguard-gate pyobjc-framework-LocalAuthentication

2 · Enroll & hook your assistant

aiguard setup            # TOTP enrollment (required on Linux)
aiguard install kimi     # or: aiguard install claude

3 · Approve a challenge when one appears

aiguard approve <token>          # Touch ID on macOS
aiguard approve --totp <token>   # force TOTP

Requirements

  • Python 3.11 or newer
  • macOS (Touch ID or TOTP) or Linux (TOTP)
  • pipx
  • Kimi Code CLI or Claude Code

Package vs. command

The PyPI package is aiguard-gate; the installed CLI is aiguard.

Beta software

Evaluate on non-critical machines first. Policy rules, state formats, and CLI behavior may change between pre-releases without a deprecation period.