integrations

Codex

Integrate brin with Codex CLI using AGENTS.md instructions and Rules

Unlike other AI coding tools, Codex CLI does not have a hooks system. Instead, it offers two mechanisms for integrating brin:

AGENTS.md - Instruction files that Codex reads before every task
Rules (experimental) - A policy system that can block or prompt for commands

Both approaches ensure that package installations go through brin for security scanning.

Prerequisites

brin CLI installed
Codex CLI

Option A: AGENTS.md Instructions (Recommended)

Codex reads AGENTS.md files before doing any work. This is the simplest way to instruct Codex to use brin for package installations.

Project-level instructions

Create .codex/AGENTS.md in your project root:

MARKDOWN

## Package Installation Rules
 
Always use `brin` instead of direct package manager commands:
 
- Use `brin add <package>` instead of `npm install`, `yarn add`, `pnpm add`, `bun add`
- Use `brin remove <package>` instead of `npm uninstall`, `yarn remove`
- Use `brin scan` to audit existing dependencies
 
This ensures all packages are scanned for vulnerabilities, malicious code,
and supply chain risks before installation.
 
### Why brin?
 
brin is a package gateway that scans packages for:
- Known CVEs and vulnerabilities
- Malicious install scripts
- Obfuscated code and prompt injection
- Supply chain attack indicators
 
Never bypass brin by running package manager commands directly.

Global instructions

To apply these instructions to all your projects, create ~/.codex/AGENTS.md:

Bash

mkdir -p ~/.codex

Then add the same content to ~/.codex/AGENTS.md.

How AGENTS.md works

Codex discovers instruction files in this order:

Global: ~/.codex/AGENTS.md
Project: .codex/AGENTS.md (in trusted projects)
Nested: Files closer to your working directory override earlier ones

Files are concatenated, with later files taking precedence. Use AGENTS.override.md for temporary overrides without deleting the base file.

Option B: Rules (Experimental, Enforcement)

For stricter enforcement, use Codex's experimental Rules system to block package manager commands entirely.

Create the rules file

Create .codex/rules/brin.rules:

STARLARK

# Block npm install commands
prefix_rule(
  pattern=["npm", ["install", "i", "add"]],
  decision="forbidden",
  justification="Use `brin add <package>` instead for security scanning.",
  match=["npm install express", "npm i lodash", "npm add react"],
  not_match=["npm run build", "npm test"],
)
 
# Block yarn add commands
prefix_rule(
  pattern=["yarn", "add"],
  decision="forbidden",
  justification="Use `brin add <package>` instead for security scanning.",
  match=["yarn add express", "yarn add -D typescript"],
)
 
# Block pnpm add commands
prefix_rule(
  pattern=["pnpm", ["add", "i", "install"]],
  decision="forbidden",
  justification="Use `brin add <package>` instead for security scanning.",
  match=["pnpm add express", "pnpm i lodash"],
)
 
# Block bun add commands
prefix_rule(
  pattern=["bun", ["add", "i", "install"]],
  decision="forbidden",
  justification="Use `brin add <package>` instead for security scanning.",
  match=["bun add express", "bun i lodash"],
)
 
# Block pip install commands
prefix_rule(
  pattern=["pip", "install"],
  decision="forbidden",
  justification="Use `brin add <package>` instead for security scanning.",
  match=["pip install requests", "pip install -r requirements.txt"],
)
 
# Block cargo add commands
prefix_rule(
  pattern=["cargo", "add"],
  decision="forbidden",
  justification="Use `brin add <package>` instead for security scanning.",
  match=["cargo add serde", "cargo add tokio"],
)

Understanding rules

Rules use Starlark syntax (Python-like) and support these fields:

Field	Description
`pattern`	Command prefix to match (required)
`decision`	`forbidden`, `prompt`, or `allow`
`justification`	Message shown when blocked
`match`	Test cases that should match
`not_match`	Test cases that should not match

Test your rules

Use codex execpolicy check to verify rules work as expected:

Bash

codex execpolicy check --pretty \
  --rules .codex/rules/brin.rules \
  -- npm install express

Expected output shows the command is forbidden with the justification message.

Global rules

Place rules in ~/.codex/rules/brin.rules to apply them to all projects:

Bash

mkdir -p ~/.codex/rules
cp .codex/rules/brin.rules ~/.codex/rules/

Troubleshooting

Instructions not loading

Verify the file exists at .codex/AGENTS.md
Check that the project is trusted (Codex skips untrusted project files)
Verify the file is not empty
Run codex --ask-for-approval never "Summarize the current instructions." to check what Codex loaded

Rules not applying

Verify the rules file exists at .codex/rules/brin.rules
Test with codex execpolicy check
Check for syntax errors in the Starlark file
Restart Codex after adding rules

Codex still uses npm directly

Make instructions more explicit and emphatic
Use Rules with decision="forbidden" for hard enforcement
Check for conflicting instructions in nested AGENTS.md files

Comparison: AGENTS.md vs Rules

Feature	AGENTS.md	Rules
Enforcement	Soft (instruction-based)	Hard (command blocked)
Setup complexity	Simple	More complex
Flexibility	High	Precise matching
Experimental	No	Yes

Recommendation: Start with AGENTS.md for simplicity. Add Rules if you need stricter enforcement.

On this page

Share feedback