Content
# Cupcake
<p align="left">
<picture>
<source srcset="docs/docs/assets/cupcake-dark.png" media="(prefers-color-scheme: dark)">
<img src="docs/docs/assets/cupcake.png" alt="Cupcake logo" width="180">
</picture>
</p>
Make AI agents follow the rules.
[](https://cupcake.eqtylab.io/)
[](LICENSE)
[](https://github.com/eqtylab/cupcake/actions/workflows/ci.yml)
[](https://github.com/eqtylab/cupcake/actions/runs/19737865145/job/56558251812)
**Policy enforcement** layer for AI agents; yielding better performance and security **without consuming model context**.
- **Deterministic rule-following** for your agents. [Interactive Examples](https://cupcake-policy-studio.vercel.app/example-policies/security/symlink-detection?harness=claude-code&format=rego)
- **Better performance** by moving rules out of context and into policy-as-code.
- **Trigger alerts** and put _bad_ agents in timeout when they repeatedly violate rules.
Cupcake intercepts agent events and evaluates them against **user-defined rules** written in **[Open Policy Agent (OPA)](https://www.openpolicyagent.org/) [Rego](https://www.openpolicyagent.org/docs/policy-language).** Agent actions can be blocked, modified, and auto-corrected by providing the agent helpful feedback. Additional benefits include reactive automation for tasks you dont need to rely on the agent to conduct (like linting after a file edit).
## Updates
**`2025-12-10`**: Official open source release. Roadmap will be produced in Q1 2026.
**`2025-04-04`**: We produce the [feature request](https://github.com/anthropics/claude-code/issues/712) for Claude Code Hooks. Runtime alignment requires integration into the agent harnesses, and we pivot away from filesystem and os-level monitoring of agent behavior (early cupcake PoC).
## Supported Agent Harnesses
Cupcake provides lightweight **native integrations** for multiple AI coding agents:
| Harness | Status | Integration Guide |
| --------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------- |
| **[Claude Code](https://claude.ai/code)** | ✅ Fully Supported | [Setup Guide](https://cupcake.eqtylab.io/getting-started/usage/claude-code/) |
| **[Cursor](https://cursor.com)** | ✅ Fully Supported | [Setup Guide](https://cupcake.eqtylab.io/getting-started/usage/cursor/) |
| **[Factory AI](https://docs.factory.ai/welcome)** | ✅ Fully Supported | [Setup Guide](https://cupcake.eqtylab.io/getting-started/usage/factory-ai/) |
| **[OpenCode](https://opencode.ai)** | ✅ Fully Supported | [Setup Guide](https://cupcake.eqtylab.io/getting-started/usage/opencode/) |
| **[AMP](https://ampcode.com)** | Coming soon | [Awaiting release](https://ampcode.com/manual?internal#hooks) |
| **[Gemini CLI](https://docs.cloud.google.com/gemini/docs/codeassist/gemini-cli)** | Coming soon | [Awaiting release](https://github.com/google-gemini/gemini-cli/issues/2779) |
Each harness uses native event formats. Similar to terraform, policies are separated by harness (`policies/claude/`, `policies/cursor/`, `policies/factory/`, `policies/opencode/`) to ensure clarity and full access to harness-specific capabilities. If a particular harness is not supported, it is because it has no means for runtime integration.
#### Language Bindings
Cupcake can be embedded in JavaScript agent applications through native bindings. This enables integration with web-based agent frameworks like LangChain, Google ADK, NVIDIA NIM, Vercel AI SDK, and more.
| Language | Binding |
| ----------------------------------------------------------------------------- | -------------- |
| <img src="docs/docs/assets/typescript.svg" width="24" height="24"> TypeScript | `./cupcake-ts` |
## How it Works
Cupcake acts as an enforcement layer between your coding agents and their runtime environment **via hooks** directly in the agent action path.
<img src="./docs/docs/assets/flow-cupcake.png" alt="Cupcake agent hooks security architecture" width="600"/>
`Agent → (proposed action) → Cupcake → (policy decision) → Agent runtime`
1. **Interception**: The agent prepares to execute an action/tool-call (e.g., `git push`, `fs_write`).
2. **Enrichment**: Cupcake gathers real-time **Signals**—facts from the environment such as the current Git branch, CI status, or database metadata.
3. **Evaluation**: The action and signals are packaged into a JSON input and evaluated against your Wasm policies in milliseconds.
### Deterministic and Non-Deterministic Evaluation
Cupcake supports two evaluation models:
1. **Deterministic Policies**: Policies are written in **OPA/Rego** and **compiled to WebAssembly (Wasm)** for fast, sandboxed evaluation. [Writing Policies](https://cupcake.eqtylab.io/reference/policies/custom/) guide for implementation details.
2. **LLM‑as‑Judge**: For simpler, yet more advanced, oversight of your rules, Cupake can interject via a secondary LLM or agent to evaluate how an action should proceed. [Cupcake Watchdog](https://cupcake.eqtylab.io/watchdog/getting-started/) guide for implementation details.
### Decisions & Feedback
Based on the evaluation, Cupcake returns one of five decisions to the agent runtime, along with a human-readable message:
- **Allow**: The action proceeds. Optionally, Cupcake can inject **Context** (e.g., "Remember: you're on the main branch") to guide subsequent behavior without blocking. _Note: Context injection is supported in Claude Code and Factory AI, but not Cursor._
- **Modify**: The action proceeds with transformed input. Policies can sanitize commands, add safety flags, or enforce conventions before execution. _Note: Supported in Claude Code and Factory AI only._
- **Block**: The action is stopped. Cupcake sends **Feedback** explaining _why_ it was blocked (e.g., "Tests must pass before pushing"), allowing the agent to self-correct.
- **Warn**: The action proceeds, but a warning is logged or displayed.
- **Require Review**: The action pauses until a human approves it.
## Why Cupcake?
Modern agents are powerful but inconsistent at following operational and security rules, especially as context grows. Cupcake turns the rules you already maintain (e.g., `CLAUDE.md`, `AGENT.md`, `.cursor/rules`) into **enforceable guardrails** that run before actions execute.
- **Multi-harness support** with first‑class integrations for **Claude Code**, **Cursor**, **Factory AI**, and **OpenCode**.
- **Governance‑as‑code** using OPA/Rego compiled to WebAssembly for fast, sandboxed evaluation.
- **Enterprise‑ready** controls: allow/deny/review, **enriched audit** trails for AI SOCs, and proactive warnings.
### Core Capabilities
- **Granular Tool Control**: Prevent specific tools or arguments (e.g., blocking `rm -rf /`).
- **MCP Support**: Native governance for Model Context Protocol tools (e.g., `mcp__memory__*`, `mcp__github__*`).
- **LLM‑as‑Judge**: Use a secondary LLM or agent to evaluate actions for more dynamic oversight.
- **Guardrail Libraries**: First‑class integrations with `NeMo` and `Invariant` for content and safety checks.
- **Observability**: All inputs, signals, and decisions generate structured logs and evaluation traces for debugging.
## Installation and development with Nix
If you're using [nix](https://nixos.org/), you can install and run Cupcake using the provided flake:
### Install Cupcake CLI using Nix
```bash
# Install directly from GitHub
nix profile install github:eqtylab/cupcake#cupcake-cli
# Or run without installing
nix run github:eqtylab/cupcake#cupcake-cli -- --help
```
### Install Cupcake CLI on NixOS
Add the following to your `flake.nix`:
```nix
inputs.cupcake.url = "github:eqtylab/cupcake";
```
And then the following package to your environment.systemPackages or home.packages:
```nix
inputs.cupcake.packages.${system}.cupcake-cli
```
### Development Shell
For development, you can also use the provided dev shell that includes Rust toolchain, just, and other dependencies:
```bash
# Enter the development shell
nix develop
```
## FAQ
**Does Cupcake consume prompt/context tokens?**
No. Policies run outside the model and return structured decisions.
**Is Cupcake tied to a specific model?**
No. Cupcake supports multiple AI coding agents with harness-specific integrations.
**How fast is evaluation?**
Sub‑millisecond for cached policies in typical setups.
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
[Apache 2.0](LICENSE)
---
Cupcake is developed by [EQTYLab](https://eqtylab.io/), with agentic safety research support by [Trail of Bits](https://www.trailofbits.com/).
[Follow on X](https://x.com/CupcakeSecures) for a regular updates.
