agentsward

Agentsward

A guardrail layer for autonomous coding agents. Agentsward 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. Agentsward 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. Agentsward adds the missing governance layer:

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 agentsward            # the CLI command is `agentsward`
agentsward setup                   # one step: pair phone + wire every installed agent

agentsward setup (or agentsward install) auto-detects and wires Claude Code, OpenAI Codex, and Google Gemini CLI — whichever are installed. To target one explicitly:

agentsward install --claude        # Claude Code (or install-hooks / --global for all projects)
agentsward install --codex         # OpenAI Codex        (or install-codex-hooks)
agentsward install --gemini        # Google Gemini CLI   (or install-gemini-hooks)
agentsward 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

Agentsward is transport-agnostic — the gate is the product, the channel is a detail:

• Telegram (default, zero infra):

  agentsward init                 # bot token + chat id
  

• Cloud relay + mobile app (approvals from anywhere):

  agentsward pair                 # link this machine to the phone app
  

Quick manual test (no agent needed):

agentsward approve-command "git push origin main"   # exits 0 (allow) / 1 (deny)

Approval modes (agentsward mode)

agentsward 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": "agentsward 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

agentsward logs -n 20      # activity timeline
agentsward pending         # is a command awaiting me, or did it stop?
agentsward resume          # lift a Stop kill-switch
agentsward instructions    # show instructions sent from the phone

Storage

All state lives in ~/.agentsward/: config.json, approvals.json, instructions.json, audit_log.json.

License

Proprietary. See LICENSE.