{"id":48367106,"url":"https://github.com/getaxonflow/axonflow-claude-plugin","last_synced_at":"2026-07-18T02:01:39.468Z","repository":{"id":349037214,"uuid":"1200545219","full_name":"getaxonflow/axonflow-claude-plugin","owner":"getaxonflow","description":"AxonFlow governance plugin for Claude Code — policy enforcement, PII detection, and audit trails","archived":false,"fork":false,"pushed_at":"2026-04-05T14:40:18.000Z","size":46,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T15:26:09.445Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getaxonflow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T14:40:29.000Z","updated_at":"2026-04-05T14:40:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/getaxonflow/axonflow-claude-plugin","commit_stats":null,"previous_names":["getaxonflow/axonflow-claude-plugin"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/getaxonflow/axonflow-claude-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getaxonflow%2Faxonflow-claude-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getaxonflow%2Faxonflow-claude-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getaxonflow%2Faxonflow-claude-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getaxonflow%2Faxonflow-claude-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getaxonflow","download_url":"https://codeload.github.com/getaxonflow/axonflow-claude-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getaxonflow%2Faxonflow-claude-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31886937,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T11:36:10.202Z","status":"ssl_error","status_checked_at":"2026-04-16T11:36:09.652Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-05T15:01:58.768Z","updated_at":"2026-07-18T02:01:39.458Z","avatar_url":"https://github.com/getaxonflow.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AxonFlow Plugin for Claude Code\n\n**Runtime governance for Claude Code: block dangerous commands before they run, scan every tool output for PII and secrets, and keep a compliance-grade audit trail — without leaving your terminal.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-7c3aed)](https://docs.claude.com/claude-code/plugins)\n\n\u003e **→ Full integration walkthrough:** **[docs.getaxonflow.com/docs/integration/claude-code](https://docs.getaxonflow.com/docs/integration/claude-code/)** — architecture, policy examples, latency numbers, troubleshooting, and the 10 MCP tools the platform exposes.\n\n\u003e **Upgrade strongly recommended.** AxonFlow ships substantial monthly security and quality hardening; staying on the latest major is the security-supported release line. [Latest release](https://github.com/getaxonflow/axonflow-claude-plugin/releases/latest) · [Security advisories](https://github.com/getaxonflow/axonflow-claude-plugin/security/advisories)\n\n---\n\n## Why you'd add this\n\nClaude Code is Anthropic's official CLI — a fast, agentic coding assistant that edits files, runs shell commands, and calls MCP servers. It's excellent at developer productivity. It was never designed to be the layer where your security and compliance team lives.\n\nThe gaps start surfacing the moment Claude Code moves from one developer's laptop to a team or production setting:\n\n| Production requirement | Claude Code alone | With this plugin |\n|---|---|---|\n| Policy enforcement before tool execution | Hooks available, no governance logic | **80+ built-in policies evaluated on every governed tool call** |\n| Dangerous command blocking (`rm -rf /`, reverse shells, `curl \\| bash`) | Not addressed | **Blocked before execution with decision context** |\n| PII / secrets detection in tool outputs | Developer responsibility | **Auto-scan; Claude is instructed to use redacted version** |\n| SQL-injection detection on MCP queries | MCP server's problem | **30+ patterns evaluated on every MCP tool call** |\n| Compliance-grade audit trail | Session logs, not compliance-formatted | **Every governed call recorded with policies, decision, duration** |\n| Decision explainability after a block | Generic hook failure message | **`decision_id` surfaced in deny reason; `explain_decision` MCP tool returns the full record** |\n| Self-service, time-bounded exceptions | Not available | **`create_override` with mandatory justification, fully audited** |\n| Cloud metadata / SSRF / path traversal blocking | Not addressed | **Built in** |\n\nYou get all of that with zero change to how developers use Claude Code. Hooks fire automatically, the deny message tells you why, MCP tools are there when you want to investigate or unblock yourself.\n\n---\n\n## How it works\n\n```\nClaude selects a tool (Bash, Write, Edit, NotebookEdit, mcp__*)\n    │\n    ▼\nPreToolUse hook fires automatically\n    │ → check_policy(\"claude_code.Bash\", \"rm -rf /\")\n    │\n    ├─ BLOCKED → Claude receives denial reason with decision_id + risk_level,\n    │            can call explain_decision / create_override to unblock\n    │\n    └─ ALLOWED → Tool executes normally\n                      │\n                      ▼\n                 PostToolUse hook fires automatically\n                      │ → audit_tool_call(tool, input, output)  [non-blocking]\n                      │ → check_output(tool result for PII/secrets)\n                      │\n                      ├─ Sensitive data found → Claude instructed to use\n                      │                          redacted version in its reply\n                      └─ Clean → Silent\n```\n\n**Governed tools:** `Bash`, `Write`, `Edit`, `NotebookEdit`, and all MCP server tools (`mcp__*`). Read-only tools (`Read`, `Glob`, `Grep`) are not governed by default — they don't modify state or send data externally.\n\n**Fail behavior:**\n- AxonFlow unreachable (network) → fail-open, tool execution continues\n- AxonFlow auth/config error → fail-closed, tool call denied until config is fixed\n- PostToolUse failures → never block (audit and PII scan are best-effort)\n\n---\n\n## Where this kicks in during real coding\n\n### 1. The MCP data-exposure problem\n\nA developer connects an MCP server to a production database for debugging. Claude Code queries customer records. Results flow through the conversation with PII intact. Session logs exist but they aren't structured for compliance queries.\n\n**With the plugin:** `check_policy` fires before the MCP query runs (SQL injection scan, policy scan), `check_output` scans the result for SSN / credit card / email / phone / API keys, and `audit_tool_call` records the full interaction with matched policies and decision ID.\n\n### 2. The accidental production change\n\nA developer types *\"fix the database issue.\"* Claude Code picks a `Bash` tool and runs a migration against prod. The command ran because nothing stopped it.\n\n**With the plugin:** a dynamic policy scoped to production patterns matches, the call is denied with a decision ID, and Claude surfaces the deny reason in the REPL. A developer can call `explain_decision` to see exactly which policy family triggered, then `create_override` with justification if they have the authority — all without leaving the session.\n\n### 3. The security-review block\n\nA team wants to deploy Claude Code at scale and security says no: *\"No policy enforcement on MCP queries, PII flows through conversations unchecked, bash commands aren't governed, audit trail isn't compliance-ready, no approval gates.\"*\n\n**With the plugin:** every one of those gaps is filled at the plugin layer. The productivity surface doesn't change.\n\n---\n\n## Try AxonFlow on a real plugin rollout\n\nWe're opening limited **Plugin Design Partner** slots.\n\n30-minute hook lifecycle review, policy pack scoping, override workflow design, and IDE/CLI rollout pattern walkthrough — for solo developers and small teams putting governance on Claude Code.\n\n[Apply here](https://getaxonflow.com/plugins/design-partner?utm_source=readme_plugin_claude) or email [design-partners@getaxonflow.com](mailto:design-partners@getaxonflow.com). Personal email is fine — solo developers welcome.\n\n### See AxonFlow in Action\n\nFour short videos covering different angles of the platform:\n\n- **[Community Quickstart Demo (Code + Terminal, 2.5 min)](https://youtu.be/BSqU1z0xxCo)** — governed calls, PII block, Gateway Mode with LangChain/CrewAI, and MAP from YAML\n- **[Runtime Control Demo (Portal + Workflow, 3 min)](https://youtu.be/6UatGpn7KwE)** — approvals, retry safety, execution state, and the audit viewer\n- **[Architecture Deep Dive (12 min)](https://youtu.be/Q2CZ1qnquhg)** — how the control plane works, policy enforcement flow, and multi-agent planning\n- **[Plugin Setup \u0026 Usage Walkthrough](https://youtu.be/_dlnX_xLYmU)** — install AxonFlow and watch governance fire on real coding work (PII redaction, production-change guardrails, audit trail)\n\n### Plugin Evaluation Tier (Free 90-day License)\n\nOutgrown Community on a real plugin install? Evaluation unlocks the capacity and features that matter for plugin users — without moving to Enterprise yet:\n\n| Capability | Community | Evaluation (Free) | Enterprise |\n|---|---|---|---|\n| Tenant policies | 20 | 50 | Unlimited |\n| Org-wide policies | 0 | 5 | Unlimited |\n| Audit retention | 3 days | 14 days | Up to 10 years |\n| HITL approval gates | — | 25 pending, 24h expiry | Unlimited, 24h |\n| Evidence export (CSV/JSON) | — | 5,000 records · 14d window · 3/day | Unlimited |\n| Policy simulation | — | 300/day | Unlimited |\n| Session overrides (self-service unblock) | — | — | Enterprise-only |\n\nOrg-wide policies and session overrides are **Enterprise-only** — those are the actual upgrade triggers for plugin users.\n\n[Get a free Plugin Evaluation license](https://getaxonflow.com/plugins/evaluation-license?utm_source=readme_plugin_claude_eval)\n\n---\n\n## Privacy notice\n\n**Read before installing.** AxonFlow [Community SaaS](https://docs.getaxonflow.com/docs/deployment/community-saas/) at `try.getaxonflow.com` is the zero-config endpoint the plugin uses if neither `AXONFLOW_ENDPOINT` nor `AXONFLOW_AUTH` is configured. In that mode, governed tool inputs (tool name + arguments) and outbound message bodies are checked by AxonFlow's policy enforcement endpoint. **Community SaaS is for early exploration only** — not for production workloads, regulated environments, real user data, personal data, or any other sensitive information. It is offered \"as is\" on a best-effort basis with no SLA, no warranties, and no commitment to retention, deletion, or incident-response timelines.\n\nFor any serious use, choose one of the following instead:\n\n1. **[Self-host AxonFlow Community Edition](https://docs.getaxonflow.com/docs/deployment/self-hosted/)** — runs entirely on your infrastructure and keeps data within your boundary. Recommended for any real workload. The in-README quick start is in [Step 1](#step-1-install-the-axonflow-platform) below.\n2. **Community Edition with an [Evaluation License](https://docs.getaxonflow.com/docs/deployment/evaluation-rollout-guide/)** — for production use with real users or clients on the open core; adds production-fit limits and license-gated features. Free 90-day [evaluation license](https://getaxonflow.com/plugins/evaluation-license).\n3. **[AxonFlow Enterprise](https://docs.getaxonflow.com/docs/deployment/community-to-enterprise-migration/)** — production-grade governance, regulatory-grade controls, SLOs, and contractual commitments suitable for regulated industries. Contact [hello@getaxonflow.com](mailto:hello@getaxonflow.com).\n\nTo skip Community SaaS entirely: set `AXONFLOW_ENDPOINT` to a self-hosted AxonFlow URL. That alone flips the plugin into self-hosted mode — the Community SaaS auto-bootstrap is not attempted, and no env var is required. Get the AxonFlow platform from [getaxonflow/axonflow](https://github.com/getaxonflow/axonflow) and follow the [Getting Started](https://docs.getaxonflow.com/docs/getting-started/) guide for the Docker Compose setup. For air-gapped environments where AxonFlow is not yet reachable but you want to suppress the bootstrap attempt, set `AXONFLOW_COMMUNITY_SAAS=0`; set `AXONFLOW_TELEMETRY=off` to also disable the anonymous 7-day heartbeat.\n\nLLM provider keys never leave the user's machine in any mode — Claude Code makes the LLM calls; AxonFlow only enforces policies and records audit trails.\n\n---\n\n## Install\n\nThis is a **three-step** install: stand up the AxonFlow platform, add the plugin to Claude Code, then point the plugin at the platform. The plugin alone does not enforce policy — its hook scripts are thin clients that talk to an AxonFlow agent gateway. If the platform is not installed and reachable, governed tool calls have nothing to evaluate against. **Skipping Step 3 is the most common mistake**: the platform is running locally but the plugin still falls back to Community SaaS because no `AXONFLOW_ENDPOINT` is configured.\n\n### Step 1: install the AxonFlow platform\n\nFor any real workload, run AxonFlow on your own infrastructure via Docker Compose:\n\n```bash\ngit clone https://github.com/getaxonflow/axonflow.git\ncd axonflow \u0026\u0026 docker compose up -d\n\n# verify\ncurl -s http://localhost:8080/health | jq .\n```\n\nFollow the [Getting Started](https://docs.getaxonflow.com/docs/getting-started/) guide for prerequisites (Docker Engine or Desktop, Docker Compose v2, 4 GB RAM, 10 GB disk) and the [Self-Hosted Deployment Guide](https://docs.getaxonflow.com/docs/deployment/self-hosted/) for production options. For production with real users or clients, run Community Edition with a free 90-day [Evaluation License](https://docs.getaxonflow.com/docs/deployment/evaluation-rollout-guide/) or [AxonFlow Enterprise](https://docs.getaxonflow.com/docs/deployment/community-to-enterprise-migration/).\n\n\u003e Skipping Step 1 makes the plugin fall back to the [Community SaaS](https://docs.getaxonflow.com/docs/deployment/community-saas/) endpoint at `try.getaxonflow.com` for early exploration only. **Do not skip Step 1 for any real workload** — see the [Privacy notice](#privacy-notice) above.\n\n### Step 2: install the plugin\n\nAdd this repo as a custom marketplace (recommended):\n\n```\n/plugin marketplace add getaxonflow/axonflow-claude-plugin\n/plugin install axonflow\n```\n\nOr load locally for testing:\n\n```bash\ngit clone https://github.com/getaxonflow/axonflow-claude-plugin.git\nclaude --plugin-dir /path/to/axonflow-claude-plugin\n```\n\n\u003e The plugin has been submitted to the official Anthropic marketplace (`anthropics/claude-plugins-official`) and is currently in Anthropic's review queue. Until it appears in `/plugin \u003e Discover`, use one of the install methods above.\n\n### Step 3: point the plugin at the platform\n\nWithout this step the plugin auto-registers with Community SaaS regardless of whether you ran Step 1 — it does not auto-detect a locally-running AxonFlow. Set `AXONFLOW_ENDPOINT` (and `AXONFLOW_AUTH` if you have credentials):\n\n```bash\n# Self-hosted local agent — that alone flips mode to self-hosted, no other env var needed\nexport AXONFLOW_ENDPOINT=http://localhost:8080\n\n# Self-hosted remote agent with credentials\nexport AXONFLOW_ENDPOINT=https://axonflow.your-company.com\nexport AXONFLOW_AUTH=$(echo -n \"your-client-id:your-client-secret\" | base64)\n```\n\nEvery hook invocation logs a one-line canary on stderr confirming the active mode:\n\n```\n[AxonFlow] Connected to AxonFlow at http://localhost:8080 (mode=self-hosted)\n```\n\nIf the canary says `mode=community-saas` after you ran Step 1, the plugin is still hitting `try.getaxonflow.com` because Step 3 was skipped or `AXONFLOW_ENDPOINT` is unset. Fix Step 3 and reload.\n\n## Activate Pro tier\n\nPlugin Pro extends the Free baseline (3-day audit retention, 200 governed events / day, 2 active custom policies, 1 HITL approval per rolling 7d) to **30-day retention**, **2,000 events / day**, **unlimited active custom policies**, **unlimited HITL approvals**, and adds the **LLM cost pre-flight** tool (estimate token cost for a multi-step plan before it runs). 90-day window, one-time **$9.99 USD** payment, no auto-renewal, 14-day no-questions refund. See [getaxonflow.com/pricing](https://getaxonflow.com/pricing/) for the full breakdown and the Stripe buy button.\n\nTo activate Pro on an installed plugin:\n\n1. **Find your client ID.** Run `/axonflow-status` from any Claude Code session. The output includes a `client_id=cs_\u003cuuid\u003e` line — that's the value Stripe Checkout needs to bind the license to your account. Copy it. (Same value the v1.4.x and earlier output called `tenant_id`; renamed for terminology consistency with the rest of AxonFlow in v1.5.0.)\n2. **Buy at the pricing page.** Visit [getaxonflow.com/pricing](https://getaxonflow.com/pricing/) and click **Buy Plugin Pro — $9.99**. At Stripe Checkout, paste your `client_id` into the **AxonFlow tenant ID** custom field. (The Stripe form's field label is still \"AxonFlow tenant ID\" — same value, the label will be renamed in a future release.)\n3. **Install the issued license token.** After checkout you'll receive an `AXON-...` license token by email. Activate it via `/axonflow-login \u003cyour-AXON-token\u003e` (the slash command's argument is the token itself), or by setting `AXONFLOW_LICENSE_TOKEN=\u003cyour-AXON-token\u003e` in the environment Claude Code runs in.\n4. **Reload Claude Code.** The next governed call uses Pro-tier limits automatically. The plugin's status canary appends `Pro tier active` so you can verify at a glance.\n\nIf you lose the token (laptop reinstall, never archived the email), use `/axonflow-recover \u003cyour-email\u003e` to request a magic link, then `/axonflow-recover-verify \u003crecovery-token\u003e` to mint fresh credentials against the same email.\n\n### Check status\n\nRun `/axonflow-status` from any Claude Code session to see your `client_id`, the resolved AxonFlow endpoint, and current tier (`Free` vs `Pro`):\n\n```\nOK  endpoint=https://try.getaxonflow.com\nOK  client_id=cs_a1b2c3d4-...  (formerly tenant_id)\nOK  tier=Free\nOK  license_token=unset\nOK  upgrade_url=https://getaxonflow.com/pricing/\n    Paste your client_id above into the Stripe checkout custom field\n    (currently labeled 'AxonFlow tenant ID' on the Stripe form).\n```\n\nThe `client_id` is the value to paste into the Stripe checkout custom field (still labeled \"AxonFlow tenant ID\" on the Stripe form) when upgrading to AxonFlow Pro. The on-disk registration file at `~/.config/axonflow/try-registration.json` still uses the `tenant_id` JSON key for file-format compat — same value, two names during the v9 transition. The license token is always shown redacted (`set (AXON-...XXXX)`) — the full bearer credential is never printed, so the output is safe to screen-share or paste into a support ticket.\n\n\u003e **Tip:** the same information is available without spawning a shell — just ask Claude \"what's my AxonFlow client ID?\" (or \"tenant ID\" — both work) and it will call the agent-side `axonflow_get_tenant_id` MCP tool, which returns the same identifier under its original wire name, the server-resolved tier, and the upgrade URLs. Other agent-callable Pro-related tools include `axonflow_list_pro_features` (\"what would I get if I upgraded?\") and `axonflow_get_cost_estimate` (Pro-only LLM cost pre-flight). See [The 15 MCP tools Claude can call](#the-15-mcp-tools-claude-can-call) below.\n\n### Free-tier limits and upgrade prompts\n\nWhen the plugin's hooks hit a Free-tier cap (200 events/day, 2 active custom policies, 1 HITL approval per rolling 7d, or a Pro-only feature), the agent returns a structured upgrade envelope. The plugin parses it and prints a single-line nudge to stderr — for example:\n\n```\n[AxonFlow] Daily limit reached on Free tier (200 events). Pro raises this to 2,000/day. Resets at midnight UTC.\n[AxonFlow] Upgrade: https://buy.stripe.com/bJe28qbztcdVchjdkw8k800\n```\n\nThe plugin also stamps a local back-off file from the response's `Retry-After` header so subsequent governed calls fall through immediately (no thundering herd against the agent) until the cap clears. The upgrade nudge is shown at most once per UTC day so it doesn't spam every hook.\n\n---\n\n## Mode-specific reference\n\nThe recommended self-hosted path is covered in [Install Step 1](#step-1-install-the-axonflow-platform). Two more modes worth knowing about:\n\n### Community SaaS — for early exploration only\n\nThe plugin's zero-config fallback when neither `AXONFLOW_ENDPOINT` nor `AXONFLOW_AUTH` is configured. The plugin registers a tenant with `try.getaxonflow.com` on first run and persists credentials at `~/.config/axonflow/try-registration.json` (mode `0600`).\n\n**Use only for early exploration of the plugin's behaviour. Not for production workloads, regulated environments, real user data, personal data, or any other sensitive information.**\n\n| What goes to `try.getaxonflow.com` | What does NOT |\n|---|---|\n| Tool name + arguments before each governed call | LLM provider API keys |\n| Outbound message bodies before delivery (PII/secret scan) | Claude Code conversation history outside governed tools |\n| Anonymous 7-day heartbeat (plugin version, OS, runtime) | Files outside the Claude Code runtime |\n\nThe endpoint runs against shared Ollama models, rate-limits at 20 req/min · 500 req/day per tenant, and is offered \"as is\" on a best-effort basis with no SLA, no warranties, no commitment to retention or deletion timelines, and may be modified or discontinued without notice. Read the [Try AxonFlow — Free Trial Server](https://docs.getaxonflow.com/docs/deployment/community-saas/) page for the full disclosure, including [data retention](https://docs.getaxonflow.com/docs/deployment/community-saas/#limitations-and-disclaimers) and [registration mechanics](https://docs.getaxonflow.com/docs/deployment/community-saas/#registration).\n\n### Air-gapped: zero outbound\n\nFor environments where no outbound traffic is permitted at all — air-gapped labs, regulated networks, classified deployments — set both env vars before the Claude Code process starts:\n\n```bash\nexport AXONFLOW_COMMUNITY_SAAS=0   # disable Community SaaS auto-bootstrap\nexport AXONFLOW_TELEMETRY=off      # disable the anonymous 7-day heartbeat\nexport AXONFLOW_ENDPOINT=http://your-internal-axonflow:8080\n```\n\nWith both env vars set and `AXONFLOW_ENDPOINT` pointing at a same-network instance, no traffic leaves your environment.\n\n---\n\n## Configure\n\n[Step 3](#step-3-point-the-plugin-at-the-platform) above covers `AXONFLOW_ENDPOINT` and `AXONFLOW_AUTH`. Other connection options:\n\n```bash\n# Self-hosted local agent\nexport AXONFLOW_ENDPOINT=http://localhost:8080\n\n# Self-hosted remote agent with credentials\nexport AXONFLOW_ENDPOINT=https://axonflow.your-company.com\nexport AXONFLOW_AUTH=$(echo -n \"your-client-id:your-client-secret\" | base64)\n\n# Default (Community SaaS) — leave both unset\nunset AXONFLOW_ENDPOINT AXONFLOW_AUTH\n\n# Optional: increase hook timeout for remote / VPN'd deployments\n# (PreToolUse default 8s, PostToolUse default 5s)\nexport AXONFLOW_TIMEOUT_SECONDS=12\n\n# Optional: attribute governed requests to a specific developer so the\n# customer portal's User column and audit filter show a real person instead\n# of a synthetic id. See \"Per-developer identity\" below.\nexport AXONFLOW_USER_EMAIL=alice@your-company.com\n\n# Optional (Enterprise): admin-minted per-user token for a VERIFIED\n# {identity, role} — role-scoped access instead of asserted-label-only\n# attribution. See \"Per-user authorization token\" below.\nexport AXONFLOW_USER_TOKEN=\u003ctoken minted by your org admin\u003e\n```\n\nWhen `AXONFLOW_AUTH` is unset and `AXONFLOW_ENDPOINT` is unset, the plugin defaults to AxonFlow Community SaaS — no further configuration needed.\n\n### Per-developer identity (`AXONFLOW_USER_EMAIL`)\n\nBy default a self-hosted / Enterprise agent attributes every governed request to\nthe credential's tenant (a client-scoped synthetic id), so the customer portal's\n**User** column shows the same value for the whole team. Set `AXONFLOW_USER_EMAIL`\nto the developer's email and the plugin sends it as the `X-User-Email` header on\nevery governed call — the MCP connection and both hooks — so audit rows are\nattributed to the individual and the portal can filter by teammate.\n\n```bash\nexport AXONFLOW_USER_EMAIL=alice@your-company.com\n```\n\nResolution precedence:\n\n1. **`AXONFLOW_USER_EMAIL`** — the supported source, and the **only reliable\n   path for a fleet**. Claude Code does not expose the logged-in Anthropic\n   account email to plugins/hooks, so set this per developer via managed\n   settings / MDM (fleet) or the shell profile (individual). A value that is\n   set but blank/whitespace-only falls through to the git fallback.\n2. **`git config user.email`** — a best-effort fallback used only when the env\n   var doesn't resolve. The plugin first does a merged read from the hook's\n   working directory (repo-local value wins; outside a repo git still returns\n   the global value), then an explicit `--global` read that survives failures\n   the merged read dies on (corrupt `.git/config`, deleted working directory).\n   ⚠️ It still only resolves **if git is installed and a `user.email` is\n   actually configured** — on a fresh machine or container image neither is a\n   given — and it is the *git* identity, **not** the Anthropic account, so it\n   can be silently wrong on shared machines or service accounts. It is also\n   **repository-influenceable**: a repo obtained as an archive can ship a\n   `.git/config` with an arbitrary `user.email` that this fallback would\n   assert on your audit rows (a normal `git clone` cannot — config is not\n   cloned). Because of that, git-sourced attribution is **never silent**: the\n   hooks print a stderr notice naming the exact identity being asserted and\n   its unverified source — at most once per day **per asserted identity**; a\n   same-day identity change re-fires it immediately, and a second notice\n   naming a different address is exactly the repo-influenced red flag to\n   look for (same `AXONFLOW_IDENTITY_NOTICE=off` opt-out). Treat the\n   fallback as a convenience default, not an authoritative identity, and do\n   not rely on it for fleet rollouts or for trustworthy attribution.\n3. **Unset** — no `X-User-Email` header is sent; the agent falls back to its\n   client-scoped synthetic id (never a blank/broken User column). So that you\n   can see *why* attribution degraded, the hooks print a one-line notice to\n   stderr — at most once per day — naming the missing source and the fix.\n   Suppress it with `AXONFLOW_IDENTITY_NOTICE=off` if your fleet intentionally\n   runs without per-developer identity.\n\nThe resolved source is exported as `AXONFLOW_USER_IDENTITY_SOURCE`\n(`env` | `git` | `none`) for scripting/debugging.\n\nIdentity here is *asserted*, not cryptographically verified — it improves audit\nvisibility; it is not an authentication boundary. For a **verified** per-user\nidentity with role-based access, see the per-user authorization token below.\n\n### Per-user authorization token (`AXONFLOW_USER_TOKEN`)\n\n`AXONFLOW_USER_EMAIL` is an asserted label; the **per-user token** is the\nverified counterpart. On an Enterprise platform that validates per-user tokens\n(enterprise#2929, first platform release after v9.9.0), an org admin mints a\ntoken per developer (`POST /api/v1/admin/organizations/{org_id}/user-tokens`,\nor OIDC tokens from your IdP), and the plugin sends it as the `X-User-Token`\nheader on every governed request — the MCP connection and both hooks. The\nplatform validates it (signature, expiry, revocation, org binding) and\nresolves a **non-forgeable `{identity, role}`** for the developer: audit rows\nattribute to the verified identity, and role-scoped features (e.g. who can\nread the whole tenant's audit trail vs. only their own rows) key on the\nvalidated role instead of treating every fleet developer identically.\n\nResolution precedence (mirrors the license-token discipline):\n\n1. **`AXONFLOW_USER_TOKEN`** — set per developer via managed settings / MDM\n   (fleet) or the shell profile (individual). Wins outright.\n2. **`~/.config/axonflow/user-token.json`** — `{\"token\": \"\u003cminted token\u003e\"}`,\n   written by your fleet's provisioning tooling. The file **must be `0600`**\n   (owner read/write only); the plugin refuses a group/world-readable token\n   file with a stderr warning rather than loading it silently:\n\n   ```bash\n   umask 077\n   printf '{\"token\":\"%s\"}' \"\u003cminted token\u003e\" \u003e ~/.config/axonflow/user-token.json\n   chmod 600 ~/.config/axonflow/user-token.json\n   ```\n\n3. **Unset** — no `X-User-Token` header is sent (never an empty header) and\n   requests are exactly what a pre-1.10 plugin sends; the platform keeps its\n   least-privilege attribution path (`X-User-Email` label, own-rows access).\n\nThe token is a **credential**: the plugin never logs or echoes its value, and\na malformed candidate (whitespace/control/quote bytes — a mis-paste) is\ndropped locally with a diagnostic instead of being sent. Note the platform\n**fails closed** on a presented-but-invalid token (expired, revoked, minted\nfor a different org): governed calls are then denied until the token is\nrotated or removed — the deny message names the token as the likely cause.\nRotation/revocation is admin-driven on the platform; re-provisioning the new\ntoken to the developer's env/file is all the plugin needs.\n\n---\n\n## What gets checked\n\nAxonFlow ships with **80+ built-in system policies** that apply to Claude Code automatically. No configuration required — new policies added to the platform are immediately enforced in every session.\n\n| Category | Coverage |\n|---|---|\n| **Dangerous commands** | Reverse shells (`nc -e`, `bash -i`, `/dev/tcp/`), `rm -rf /`, `dd if=`, `curl \\| bash`, credential file access (`cat ~/.ssh/`, `cat ~/.aws/`), path traversal |\n| **SQL injection** | 30+ patterns including UNION injection, stacked queries, auth bypass, encoding tricks |\n| **PII detection** | SSN, credit card, Aadhaar, PAN, email, phone, NRIC/FIN (Singapore), and more — with redaction |\n| **Secrets exposure** | API keys, connection strings, hardcoded credentials, code secrets |\n| **SSRF** | Cloud metadata endpoint (`169.254.169.254`) and internal-network blocking |\n| **Prompt injection** | Instruction override, jailbreak attempts, role hijacking |\n| **Claude Code-specific** | `.claude/settings.json` write protection, `.claude/hooks/*.json` modification warnings (enabled via `AXONFLOW_INTEGRATIONS=claude-code`) |\n\nCustom policies are easy — `POST /api/v1/dynamic-policies` or the Customer Portal. See [Policy Enforcement](https://docs.getaxonflow.com/docs/mcp/policy-enforcement/).\n\n---\n\n## The 15 MCP tools Claude can call\n\nIn addition to automatic hooks, the agent's MCP server exposes **15 tools** Claude can call directly. All served by the platform at `/api/v1/mcp-server` — the plugin's `.mcp.json` just points Claude there. New platform tools are immediately available.\n\n### Governance (6)\n\n| Tool | Purpose |\n|------|---------|\n| `check_policy` | Evaluate specific inputs against policies |\n| `check_output` | Scan specific content for PII/secrets |\n| `audit_tool_call` | Record an additional audit entry |\n| `list_policies` | List active governance policies (system + tenant) |\n| `get_policy_stats` | Summary of governance activity |\n| `search_audit_events` | Search individual audit records for debugging and compliance evidence |\n\n### Decision explainability \u0026 session overrides (4)\n\n| Tool | Purpose |\n|------|---------|\n| `explain_decision` | Return the full [DecisionExplanation](https://docs.getaxonflow.com/docs/governance/explainability/) for a decision ID |\n| `create_override` | Create a time-bounded, audit-logged session override (mandatory justification) |\n| `delete_override` | Revoke an active session override |\n| `list_overrides` | List active overrides scoped to the caller's tenant |\n\n### Tenant identity \u0026 tier capability (5 — V1 Plugin Pro)\n\n| Tool | Free access | Pro access |\n|------|-------------|------------|\n| `axonflow_get_tenant_id` | Visible + callable — returns tenant_id, server-resolved tier, upgrade URL | Same |\n| `axonflow_list_pro_features` | Visible + callable — locked Pro feature list (5 differentiators + $9.99 / 90-day pricing) | Same |\n| `axonflow_request_approval` | Visible + 1 per rolling 7d | Unlimited |\n| `axonflow_create_tenant_policy` | Visible + 2 active max | Unlimited |\n| `axonflow_get_cost_estimate` | Filtered out of `tools/list` — Pro-only | Visible + callable |\n\nWhen a Free-tier cap is hit on these tools, the agent returns a structured upgrade envelope (same shape as the 429 daily-quota envelope) and the plugin surfaces the upgrade prompt to stderr — see [Free-tier limits and upgrade prompts](#free-tier-limits-and-upgrade-prompts).\n\n**The inline-unblock workflow:** a policy block → the deny reason includes `decision_id` and `risk_level` → the developer asks Claude to call `explain_decision` → if the decision is overridable, `create_override` unblocks with justification. No separate admin surface, full audit trail.\n\nSee [Session Overrides](https://docs.getaxonflow.com/docs/governance/overrides/).\n\n---\n\n## Latency\n\n| Operation | Typical overhead |\n|-----------|-----------------|\n| Policy pre-check | 2–5 ms |\n| PII detection | 1–3 ms |\n| SQL-injection scan | 1–2 ms |\n| Audit write (async) | 0 ms (non-blocking) |\n| **Total per-tool overhead** | **3–10 ms** |\n\nImperceptible in interactive Claude Code sessions.\n\n---\n\n## Sister integrations\n\nSame governance platform, same 80+ policies, same 10 MCP tools — different agent hosts:\n\n| Integration | Repo | Docs |\n|---|---|---|\n| Claude Code | *this repo* | [claude-code](https://docs.getaxonflow.com/docs/integration/claude-code/) |\n| Anthropic Computer Use | Docs-only integration (uses the Agent SDK pattern) | [computer-use](https://docs.getaxonflow.com/docs/integration/computer-use/) |\n| Claude Agent SDK | Docs-only integration | [claude-agent-sdk](https://docs.getaxonflow.com/docs/integration/claude-agent-sdk/) |\n| Cursor IDE | [axonflow-cursor-plugin](https://github.com/getaxonflow/axonflow-cursor-plugin) | [cursor](https://docs.getaxonflow.com/docs/integration/cursor/) |\n| OpenAI Codex | [axonflow-codex-plugin](https://github.com/getaxonflow/axonflow-codex-plugin) | [codex](https://docs.getaxonflow.com/docs/integration/codex/) |\n| OpenClaw | [axonflow-openclaw-plugin](https://github.com/getaxonflow/axonflow-openclaw-plugin) | [openclaw](https://docs.getaxonflow.com/docs/integration/openclaw/) |\n\n---\n\n## Plugin structure\n\n```\naxonflow-claude-plugin/\n├── .claude-plugin/\n│   ├── plugin.json        # Plugin metadata\n│   └── marketplace.json   # Marketplace listing\n├── .mcp.json              # MCP server connection (points at the platform)\n├── hooks/\n│   └── hooks.json         # PreToolUse + PostToolUse hook definitions\n├── scripts/\n│   ├── pre-tool-check.sh    # Policy enforcement before tool execution\n│   ├── post-tool-audit.sh   # Audit + PII scan after execution\n│   ├── mcp-auth-headers.sh  # Basic-auth header generation for MCP\n│   └── telemetry-ping.sh    # Anonymous telemetry (fires once per install)\n└── tests/\n    ├── test-hooks.sh        # Hook regression (mock server)\n    ├── E2E_TESTING_PLAYBOOK.md\n    └── e2e/                 # Smoke E2E against live AxonFlow\n```\n\n---\n\n## Testing\n\n```bash\n# Hook regression tests (no live stack required)\n./tests/test-hooks.sh\n\n# Smoke E2E against a live AxonFlow at localhost:8080\nbash tests/e2e/smoke-block-context.sh\n```\n\nThe smoke scenario installs the plugin's `pre-tool-check.sh` against a running platform, feeds a SQLi-bearing Bash tool invocation through it, and asserts the hook returns the `permissionDecision: deny` shape with the richer-context markers (`decision:`, `risk:`) in the reason text. Exits 0 with `SKIP:` if no stack is reachable. Run in CI via `workflow_dispatch` when a reachable endpoint is configured.\n\nFor the broader validation story — explain-decision, override lifecycle, audit-filter parity, cache invalidation — see the [Claude Code integration guide](https://docs.getaxonflow.com/docs/integration/claude-code/) and the [governance test scenarios](https://docs.getaxonflow.com/docs/testing/) documentation.\n\n---\n\n## Telemetry\n\nAnonymous heartbeat at most once every 7 days per machine: plugin version, OS, architecture, bash version, AxonFlow platform version, deployment mode (community-saas / self-hosted production / self-hosted development). **Never** tool arguments, message contents, or policy data. The stamp file mtime advances only after the HTTP POST returns 2xx, so a transient network failure does not silence telemetry until the next window.\n\nOpt out: set `AXONFLOW_TELEMETRY=off` in the environment Claude Code runs in.\n\n### Scope of `AXONFLOW_TELEMETRY=off`\n\n`AXONFLOW_TELEMETRY=off` disables the anonymous heartbeat described above. On **self-hosted** and **in-VPC** deployments, that heartbeat is the only data the plugin sends to AxonFlow, so setting `=off` means we receive nothing. On **Community SaaS** (`try.getaxonflow.com`) the hosted service also processes operational data — registrations, audit logs, policy enforcement records, workflow state, plan data, and request-header metadata aggregated for usage analytics — as part of running the platform; that operational data flow is governed by the [Privacy Policy](https://getaxonflow.com/privacy/), not by `AXONFLOW_TELEMETRY`.\n\n`DO_NOT_TRACK` is **not** honored as an opt-out for AxonFlow telemetry. It is commonly inherited from host tools and developer environments — and in Claude Code specifically, the CLI injects `DO_NOT_TRACK=1` into every hook subprocess regardless of user intent. That makes it an unreliable expression of user intent, so AxonFlow telemetry is controlled exclusively by `AXONFLOW_TELEMETRY=off`.\n\nGuarded by a stamp file at `$HOME/.cache/axonflow/claude-code-plugin-telemetry-sent` (delete to re-send). Details: [docs.getaxonflow.com/docs/telemetry](https://docs.getaxonflow.com/docs/telemetry/).\n\n---\n\n## Links\n\n- **[Claude Code Integration Guide](https://docs.getaxonflow.com/docs/integration/claude-code/)** — the full walkthrough (recommended starting point)\n- [AxonFlow Documentation](https://docs.getaxonflow.com)\n- [Policy Enforcement](https://docs.getaxonflow.com/docs/mcp/policy-enforcement/)\n- [Decision Explainability](https://docs.getaxonflow.com/docs/governance/explainability/)\n- [Session Overrides](https://docs.getaxonflow.com/docs/governance/overrides/)\n- [Self-Hosted Deployment](https://docs.getaxonflow.com/docs/deployment/self-hosted/)\n- [Security Best Practices](https://docs.getaxonflow.com/docs/security/best-practices/)\n- [Anthropic Computer Use Integration](https://docs.getaxonflow.com/docs/integration/computer-use/)\n- [Claude Agent SDK Integration](https://docs.getaxonflow.com/docs/integration/claude-agent-sdk/)\n- [AxonFlow source](https://github.com/getaxonflow/axonflow)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetaxonflow%2Faxonflow-claude-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetaxonflow%2Faxonflow-claude-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetaxonflow%2Faxonflow-claude-plugin/lists"}