Metadata-Version: 2.4
Name: agentsguard
Version: 0.3.0
Summary: Approve or deny your AI coding agent's risky commands from your phone, with an audit trail. Works with Claude Code and OpenAI Codex.
Author: AgentGuard
License: Proprietary
Project-URL: Homepage, https://github.com/ismailLamdouar/agentguard
Project-URL: Issues, https://github.com/ismailLamdouar/agentguard/issues
Keywords: claude,claude-code,ai-agent,approval,human-in-the-loop,telegram,guardrail,security
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: requests>=2.31
Requires-Dist: qrcode>=7.4
Provides-Extra: car
Requires-Dist: gTTS>=2.3; extra == "car"
Dynamic: license-file

# 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](https://code.claude.com/docs/en/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

```bash
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):
  ```bash
  agentguard init                 # bot token + chat id
  ```
- **Cloud relay + mobile app** (approvals from anywhere):
  ```bash
  agentguard pair                 # link this machine to the phone app
  ```

Quick manual test (no agent needed):

```bash
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:

```json
{
  "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

```bash
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](LICENSE).
