Skip to main content

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 --timeout must be ≤ the outer "timeout", or Claude Code kills the hook before your phone can respond. install-hooks keeps 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)

Source distribution for agentsguard 0.4.1
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)

Table of built distributions (wheels) for agentsguard 0.4.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page