Installation
Install the CLI, enroll your second factor, and hook your assistant.
Requirements
| Requirement | Notes |
|---|---|
| Python 3.11+ | Older versions are not supported |
| pipx | Recommended installer — isolates the CLI's dependencies |
| macOS or Linux | Touch ID on macOS (TOTP fallback); TOTP on Linux |
| Kimi Code CLI or Claude Code | AIGuard uses their official PreToolUse hook mechanisms |
1 · Install the CLI
pipx install aiguard-gate
# macOS Touch ID support:
pipx inject aiguard-gate pyobjc-framework-LocalAuthentication
Package vs. command
The PyPI package is aiguard-gate; the installed CLI is
aiguard. (The name aiguard-cli was rejected by
PyPI as too similar to an existing, unrelated project.)
2 · Enroll TOTP
aiguard setup
This enrolls a 6-digit RFC 6238 TOTP secret — scan it with any authenticator app. Required on Linux; on macOS it is the fallback when Touch ID is unavailable. The secret is stored in the system keyring where available, with a 0600-file fallback on headless systems.
3 · Hook your assistant
aiguard install kimi # or: aiguard install claude
This registers aiguard-evaluate as a PreToolUse hook in the
assistant's own configuration. To remove it later:
aiguard uninstall kimi # or: aiguard uninstall claude
4 · Optional: desktop notifications
aiguard daemon-install # macOS LaunchAgent
The daemon is informational only
Approval works without it. If it is not running you get no
notifications — watch for AIGUARD_CHALLENGE: messages from
the assistant instead. Notifications display the first 50 characters of
the challenged command on screen.
Approving a challenge
When the assistant hits an ask decision it relays a token. Approve it in any terminal:
aiguard approve <token> # Touch ID on macOS aiguard approve --totp <token> # force TOTP
Approvals are single-use, bound to the exact command string, and expire after 5 minutes. Then tell the assistant to retry.
Do not rely on AIGuard in yolo/auto-approve mode
Both assistants fail open if a hook times out or crashes. Combining that with auto-approval bypasses everything. AIGuard must not be your only safeguard — see Risk Disclosures.