AgentGuard
A guardrail layer for autonomous coding agents. AgentGuard classifies the risk of every shell command and file edit your AI coding agent attempts, routes the risky ones to your phone for approval, and — critically — denies by default when no one responds. Every decision is logged.
Not a remote-control app. Anthropic's Remote Control already lets you drive a Claude session from your phone. AgentGuard is the policy layer underneath: it decides what an agent is allowed to do, enforces protected files unconditionally, fails safe, and is built to gate any agent — not just one vendor's.
Why it exists
Native permission prompts (and Remote Control's mirrored version of them) ask "allow this?" with no risk model, no protected-file enforcement, and no fail-safe: ignore the prompt and nothing is denied. AgentGuard adds the missing governance layer:
| Native prompt / Remote Control | AgentGuard | |
|---|---|---|
| Risk classification | — | CRITICAL → LOW, defaults to "ask" |
Protected files (.env, CI, lockfiles, .claude/) |
— | Always re-affirm, bypass auto-allow |
| No-response behavior | nothing denied | default-deny (fail-safe timeout) |
| Phone-set guards / auto-rules | — | yes |
| Audit trail | — | every classify/approve/deny logged |
How it works
A PreToolUse hook intercepts the agent's tool call, a classifier scores it, and:
- LOW → auto-approve.
- CRITICAL → auto-deny.
- MEDIUM / HIGH → sent to your phone with a diff/snippet; blocks until you decide.
- Protected file (gate config, secrets, supply-chain/CI) → always reaches you, regardless of score.
- No decision within the timeout → deny (fail-safe).
Install
pip install agentsguard # the CLI command is `agentguard`
agentguard setup # one step: pair phone + wire every installed agent
agentguard setup (or agentguard install) auto-detects and wires Claude Code, OpenAI Codex, and Google Gemini CLI — whichever are installed. To target one explicitly:
agentguard install --claude # Claude Code (or install-hooks / --global for all projects)
agentguard install --codex # OpenAI Codex (or install-codex-hooks)
agentguard install --gemini # Google Gemini CLI (or install-gemini-hooks)
agentguard install --all # every supported agent
Then restart the agent you wired — Claude Code (or run /hooks), Codex, or Gemini (in auto-accept/YOLO so the phone is the sole gate). It's idempotent and leaves any other hooks in place.
Approval channels
AgentGuard is transport-agnostic — the gate is the product, the channel is a detail:
- Telegram (default, zero infra):
agentguard init # bot token + chat id
- Cloud relay + mobile app (approvals from anywhere):
agentguard pair # link this machine to the phone app
Quick manual test (no agent needed):
agentguard approve-command "git push origin main" # exits 0 (allow) / 1 (deny)
Approval modes (agentguard mode)
| Mode | Who approves | Use when |
|---|---|---|
phone (default) |
Only your phone. The local popup is suppressed — the hook tells Claude Code allow/deny directly, so work continues the instant you tap. | You're away, or don't want anyone at the keyboard approving for you. |
laptop |
Only the local prompt. No phone notifications; the hook steps aside. | You're at the desk and don't want phone pings. |
agentguard mode laptop takes effect immediately (read at runtime).
Claude Code hook
install-hooks wires the gating + notification hooks with the correct local path filled in.
The gating hook looks like:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "agentguard hook --timeout 1800", "timeout": 1800 }
]
}
]
}
}
- Critical invariant: the inner
--timeoutmust be ≤ the outer"timeout", or Claude Code kills the hook before your phone can respond.install-hookskeeps them matched. - Hook config changes take effect only after restarting Claude Code (snapshotted at session start). Hook code is live with an editable install.
Other commands
agentguard logs -n 20 # activity timeline
agentguard pending # is a command awaiting me, or did it stop?
agentguard resume # lift a Stop kill-switch
agentguard instructions # show instructions sent from the phone
Storage
All state lives in ~/.agentguard/: config.json, approvals.json, instructions.json,
audit_log.json.
License
Proprietary. See LICENSE.
Metadata
Release files for agentsguard 0.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentsguard-0.4.1.tar.gz | 85.2 kB | Without provenance | Details for agentsguard-0.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentsguard-0.4.1-py3-none-any.whl | Python 3 | none | any | Details for agentsguard-0.4.1-py3-none-any.whl |
Total release size: 178.0 kB
Release files / agentsguard-0.4.1.tar.gz
| Download URL | agentsguard-0.4.1.tar.gz |
|---|---|
| Size | 85.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
498aed801dad34d5084fb93b99d07e0c4cb68911d994faefbcc7f31b5ad58021
|
|
BLAKE2b-256 checksum How to use checksums |
d870d8ee19f929b74c5d592740decb14648584caa4e21393b3d639cb3d760526
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / agentsguard-0.4.1-py3-none-any.whl
| Download URL | agentsguard-0.4.1-py3-none-any.whl |
|---|---|
| Size | 92.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
92523d18a69891419a347cb9bbd025ea61fddb85a4bb7c3e20866ddffffd5407
|
|
BLAKE2b-256 checksum How to use checksums |
a4845dce7df0d0971b5a548c76259d7e74b29a0d2de8e4afa9b5d77a85953e10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for agentsguard 0.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.