Experimental Preview — This project is under active development and released as an early preview. Interfaces and behavior may change between releases. We welcome your feedback to help shape its future.
coding-agents-kit brings Falco to the world of AI coding agents. It is designed for developers who use coding agents daily and want visibility, auditability, and pre-execution guardrails for what those agents do on their machines.
True to Falco's tradition, the primary goal is detection. The kit provides a monitor mode that lets you observe every tool call your coding agent makes — shell commands, file writes, reads, API calls — in real time, evaluated against Falco rules you define. This gives you a clear picture of what the agent is actually doing during a session.
Unlike classic Falco, this project operates entirely in user space — no kernel modules, no root, no containers. This makes it easy to run on your development machine but comes with known limitations: Falco evaluates tool calls as declared by the agent, not the system calls those commands produce.
That said, detecting unwanted behavior is still valuable — even at the tool-call level, it helps you catch the unexpected. The kit also provides a guardrail-style enforcement mode that relies on the coding agent's own hook API to block or prompt for confirmation before execution. This is strongest when the agent uses structured tools such as file reads and writes, and weaker for generic execution paths such as shell commands or external MCP servers. It is not a substitute for sandboxing, containment, or system hardening — it complements those techniques by adding a policy layer at the agent level.
Ultimately, coding-agents-kit is a new way to let Falco and coding agents collaborate, and a foundation for exploring new approaches to protecting your systems against AI-driven threats.
When your coding agent tries to use a tool, coding-agents-kit intercepts the call before it executes, evaluates it against your security rules, and decides what happens next:
| Verdict | What Happens |
|---|---|
| Allow | The tool call proceeds normally |
| Deny | The tool call is blocked — the agent is told why |
| Ask | You are prompted to approve or reject the call |
Security policies are written as standard Falco rules in YAML. You get a set of sensible defaults out of the box, and you can add your own rules for your specific needs.
Monitor mode is useful on its own for visibility, auditing, and tuning rules. Enforcement mode adds meaningful friction and policy control before execution, especially for structured file operations and obviously risky actions, but it should be treated as a guardrail layer rather than a hard security boundary.
- Good fit when you want to see what the agent is trying to do, add prompts or denials around risky actions, and enforce clear file-access boundaries.
- Best used alongside sandboxing, system hardening, least-privilege environments, or other containment mechanisms.
- Not the right tool if you need guarantees about what allowed shell commands, scripts, binaries, or MCP servers will do at runtime.
Download the .pkg installer from the latest release and open it:
open coding-agents-kit-0.1.0-darwin-universal.pkgThe macOS Installer wizard guides you through the setup. Once complete, the service starts automatically on login.
Note
Since the binaries are not code-signed, macOS Gatekeeper may block them on first run. Go to System Settings > Privacy & Security and allow the blocked binary, or run:
xattr -dr com.apple.quarantine ~/.coding-agents-kit/bin/*Download the package for your architecture from the latest release:
tar xzf coding-agents-kit-0.1.0-linux-x86_64.tar.gz
cd coding-agents-kit-0.1.0-linux-x86_64
bash install.shThe installer copies all components to ~/.coding-agents-kit/, starts a systemd user service, and registers the hook automatically.
~/.coding-agents-kit/bin/coding-agents-kit-ctl status
~/.coding-agents-kit/bin/coding-agents-kit-ctl hook statusTip: Add
export PATH="$HOME/.coding-agents-kit/bin:$PATH"to your shell profile to usecoding-agents-kit-ctlwithout the full path.
# Check status
~/.coding-agents-kit/bin/coding-agents-kit-ctl status
# Monitor mode — rules evaluate and log, but verdicts are not enforced
~/.coding-agents-kit/bin/coding-agents-kit-ctl mode monitor
# Enforcement mode (default) — verdicts are enforced
~/.coding-agents-kit/bin/coding-agents-kit-ctl mode enforcement
# View live logs
~/.coding-agents-kit/bin/coding-agents-kit-ctl logs
# Temporarily disable interception (tool calls proceed unmonitored)
~/.coding-agents-kit/bin/coding-agents-kit-ctl hook remove
# Re-enable interception
~/.coding-agents-kit/bin/coding-agents-kit-ctl hook add
# Stop / start the service
~/.coding-agents-kit/bin/coding-agents-kit-ctl stop
~/.coding-agents-kit/bin/coding-agents-kit-ctl start~/.coding-agents-kit/bin/coding-agents-kit-ctl uninstallThe project ships with rules that provide baseline protection:
| Rule | Verdict | Description |
|---|---|---|
| Monitor activity outside working directory | — | Logs file access outside the project directory |
| Ask before writing outside working directory | ask | Requires your confirmation for writes outside the project |
| Deny writing to sensitive paths | deny | Blocks writes to /etc/, ~/.ssh/, ~/.aws/, .env, and other sensitive locations |
Add your own rules to ~/.coding-agents-kit/rules/user/. They are preserved across upgrades.
Example — block piping content to shell interpreters:
- rule: Deny pipe to shell
desc: Block piping content to shell interpreters
condition: >
tool.name = "Bash"
and (tool.input_command contains "| sh"
or tool.input_command contains "| bash"
or tool.input_command contains "| zsh")
output: >
Falco blocked piping to a shell interpreter (%tool.input_command)
priority: CRITICAL
source: coding_agent
tags: [coding_agent_deny]Rules are written in the standard Falco rule language (YAML). See rules/README.md for all available fields and examples.
A Claude Code skill is included to help you write custom rules interactively.
Register this repository as a Claude Code Plugin marketplace:
/plugin marketplace add leogr/coding-agents-kit
Then install the skill directly:
/plugin install coding-agents-falco-rules@coding-agents-kit-skills
Or browse and install interactively:
- Select
Browse and install plugins - Select
coding-agents-kit-skills - Select
coding-agents-falco-rules - Select
Install now
Once installed, ask Claude Code things like:
- "Block the agent from running git push"
- "Deny any read outside the working directory"
- "Create a rule that requires confirmation before editing Dockerfiles"
The skill guides Claude through writing the rule, placing it in the right directory, and validating it with Falco.
| Agent | Platform | Status |
|---|---|---|
| Claude Code | Linux (x86_64, aarch64) | Supported |
| Claude Code | macOS (Apple Silicon, Intel) | Supported |
| Codex | Linux, macOS | Planned |
| — | Windows | Planned |
We are actively working on expanding agent and platform support. Codex integration and Windows support are next on the roadmap.
Linux
Requires: Rust (latest stable)
make linux # Both architectures
make linux-x86_64 # x86_64 only
make linux-aarch64 # aarch64 only (requires cross toolchain)Output: build/coding-agents-kit-0.1.0-linux-{arch}.tar.gz
See installers/linux/ for details.
macOS
Requires: Rust (latest stable), CMake >= 3.24, Xcode Command Line Tools, OpenSSL via Homebrew
# Install prerequisites
xcode-select --install
brew install cmake openssl@3
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Build
make macos-aarch64 # Apple Silicon
make macos-x86_64 # Intel (must build on matching hardware or via Rosetta)
make macos-universal # Universal binary (requires Rosetta + x86_64 Homebrew)Output: build/coding-agents-kit-0.1.0-darwin-{arch}.{tar.gz,pkg}
Falco does not ship pre-built macOS binaries. The first build compiles Falco from source (~5 min). Subsequent builds use the cached binary.
See installers/macos/ for details.
Individual Components
make build # All components (interceptor, plugin, CLI tool)
make build-interceptor # Interceptor only
make build-plugin # Falco plugin only
make build-ctl # CLI tool only
make falco-macos # Falco binary (macOS only)┌──────────────┐ ┌──────────────┐ ┌────────────────────────────┐
│ Coding Agent │────▶│ Interceptor │────▶│ Falco (nodriver) │
│ │ │ (hook) │ │ ┌───────────────────────┐ │
│ │◀────│ │◀────│ │ Plugin (src + extract│ │
│ │ │ │ │ │ + embedded broker) │ │
└──────────────┘ └──────────────┘ │ └───────────────────────┘ │
│ Rule Engine + Rules │
└────────────────────────────┘
- The coding agent's hook fires before each tool call
- The interceptor sends the event to the plugin's embedded broker via Unix socket
- The plugin feeds the event to Falco's rule engine
- Matching rules produce verdicts (deny/ask/allow)
- The interceptor delivers the verdict back to the coding agent
For design decisions, component specs, and full architectural documentation, see CLAUDE.md.
coding-agents-kit intercepts tool calls at the coding agent's hook API — it sees the commands the agent asks to run, not the side effects those commands produce on the system.
This means that if a coding agent embeds harmful logic in a source file, compiles it, and then runs the resulting binary, Falco can inspect the compile and run commands but cannot analyze what the compiled program actually does at runtime. The rules see gcc main.c -o main and ./main, not the system calls that ./main makes.
Coverage is therefore asymmetric:
- Strongest for structured tools such as
Write,Edit, andRead, where the agent exposes first-class file semantics. - Weaker for generic tools such as
Bash, where rules evaluate the declared command rather than fully resolved shell behavior. - Input-side only for external systems such as MCP, where the kit can inspect the requested call but not the side effects the MCP server later performs.
In practice, this means enforcement mode can block many unsafe or out-of-policy tool calls, but it is not OS-level containment and should not be treated as a hard boundary. For deeper visibility — detecting what processes actually do at the syscall level — Falco's kernel instrumentation (eBPF/kmod) is the right tool (at least for Linux).
Runtime security for AI coding agents is new territory — we're learning alongside the community.
If you're using coding-agents-kit, we'd love to hear from you:
- What works? What rules have you written? What did you catch?
- What's missing? What agents or platforms do you need?
- What broke? What didn't work as expected?
Your experience directly shapes where this project goes next. Open an issue, start a discussion, or reach out to the maintainers. Every bit of feedback helps.
coding-agents-kit was built with significant assistance from Claude Code.
Initial research and ideation by Leonardo Grasso, Loris Degioanni, and Michael Clark.
Support and testing by Alessandro Cannarella, Iacopo Rozzo, and Leonardo Di Giovanna.
Apache License 2.0. See LICENSE.