agentsguard 0.3.1

Approve or deny your AI coding agent's risky commands from your phone, with an audit trail. Works with Claude Code and OpenAI Codex.

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 install-hooks          # wire hooks into this project (.claude/settings.local.json)
agentguard install-hooks --global # …or all projects (~/.claude/settings.json)

Then restart Claude Code (or run /hooks). 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.