Operate

Claude Code plugin

A Claude Code plugin that packages AgentFox as skills, slash commands, subagents, a safety hook and a read-only MCP server, so a coding agent can do the work without you learning the CLI first.

When to use this

Use it when you would rather say "get my support agent governed" than type the commands, or when you want a coding agent to wire AgentFox into a codebase. It drives the same agentfox CLI documented here, so everything it does you can also do by hand. It is not the same thing as the Claude Code hooks that govern a coding agent's own tool calls; those are on Coding agents.

Install

The plugin calls the CLI, so AgentFox must be installed where Claude Code runs:

pip install agentfox

Then add the plugin from GitHub:

claude plugin marketplace add architsharm/agentfox
claude plugin install agentfox@agentfox

Or try it from a local clone without installing anything into Claude Code:

claude --plugin-dir ./plugins/claude-code

Both manifests validate with Claude Code's own checker:

claude plugin validate ./plugins/claude-code
claude plugin validate .

Validating plugin manifest: …/plugins/claude-code/.claude-plugin/plugin.json

✔ Validation passed
Validating marketplace manifest: …/.claude-plugin/marketplace.json

✔ Validation passed

Other coding agents (Codex, Cursor, Gemini CLI, Aider) can use the same material: point them at plugins/shared/AGENTS.md. The skills are plain markdown, and the Claude Code plugin carries a copy of the same files.

The plugin finds the CLI through plugins/claude-code/scripts/agentfox.sh: an agentfox on PATH first, then uv run or a local .venv in a source checkout. If none is found it prints the install line and exits 127.

Slash commands

Start with /agentfox:tour to see the product in a scratch database, then /agentfox:start in your repository. That is the same path as the Quickstart.

Skills

The commands load these. Claude Code also loads them on its own when a request matches their description, so "red-team my agent" works without the slash command.

Subagents

The safety hook

A PreToolUse hook on Bash turns every command that changes what gets blocked into a permission prompt with a plain-language reason. Anything else passes through untouched. For example:

echo '{"tool_name":"Bash","tool_input":{"command":"agentfox policy enforce baseline"}}' \
  | python3 plugins/claude-code/scripts/guard_blocking_commands.py

{"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "ask", "permissionDecisionReason": "AgentFox plugin: this command promotes a policy to ENFORCE \u2014 matching production traffic starts being blocked. Confirm the user asked for exactly this."}}

It asks before: policy enforce and policy observe; agents kill, quarantine and resume; policy proposals apply, rollback, and verify --failed; demo and admin seed (they write demo data into the configured database); admin db downgrade; admin auth issue and revoke; any rule, boundary or escalation written with --mode enforce; scan --submit; and the equivalent curl calls to the control-plane API. The old command names are matched too. It never blocks outright, and a command it cannot parse goes through.

The read-only MCP server

The plugin starts an MCP server over stdio. Any other MCP client can run the same process:

agentfox serve mcp

It exposes 27 tools, all of which read or analyse:

agentfox admin mcp tools

agentfox_doctor                 Reports whether this deployment is configured the way you think it is: database, traffic, authentication, detectors, modes
agentfox_findings               Returns what the platform has found (ungoverned calls, shadow agents, policy gaps) as JSON, newest first
agentfox_finding_occurrences    Findings ranked by how many times the same underlying problem has recurred, …
agentfox_agents                 Returns every agent, registered or shadow, plus an inventory summary …
agentfox_agent_lineage          Shows what an agent can reach (tools, data, other agents) up to a depth: its blast radius
agentfox_policy_list            Lists policies with their version, enforcement mode (observe or enforce) and rule count
…
agentfox_audit_verify           Verifies the tamper-evident audit chain, optionally over a sequence range
…
agentfox_guard_text             Evaluates text for an agent on one surface (input, output, retrieved, tool_result) against the policy in force, without calling a model and without recording a decision

Nothing there enforces a policy, stops an agent, issues a token, seeds data, or decides, applies or rolls back a proposal. The server says so in its instructions to the client, and asks for a person to run those with the CLI. It reads the same database as the CLI in that environment, so set AGENTFOX_STATE_DIR or AGENTFOX_DATABASE_URL for it the same way. AGENTFOX_MCP_LOG_LEVEL sets its log level.

Troubleshooting

• "agentfox is not installed" from a command: install it in the environment Claude Code was started from, or start Claude Code inside your venv.
• The tour changed your data: it should not; it uses a throwaway database. If you ran agentfox demo yourself, set AGENTFOX_STATE_DIR to a scratch directory first.
• The MCP server shows different findings from the CLI: the two processes see different environments, so they read different databases.

Limits

• The hook does not prompt on agentfox permit grant. The command asks for confirmation itself, but --yes skips that, so read grants an agent proposes before it runs them.
• The plugin is a guide for a coding agent, not a control. It governs nothing at runtime.
• The safety hook only sees Bash commands in a Claude Code session with the plugin enabled.