brin
integrations

Codex

Add brin to Codex CLI with Rules that block direct installs and a wrapper that checks brin before every package install.

Codex's Rules system can block commands before they run. that makes it a better fit for brin than AGENTS.md: Rules are enforced, instruction files are advisory.

##setup

1. Create .codex/rules/brin.rules:

STARLARK
prefix_rule(
  pattern=["npm", ["install", "i", "add"]],
  decision="forbidden",
  justification="Use ./scripts/brin-install npm <package> so brin can approve the package first.",
)
 
prefix_rule(
  pattern=["pnpm", ["install", "i", "add"]],
  decision="forbidden",
  justification="Use ./scripts/brin-install pnpm <package> so brin can approve the package first.",
)
 
prefix_rule(
  pattern=["yarn", "add"],
  decision="forbidden",
  justification="Use ./scripts/brin-install yarn <package> so brin can approve the package first.",
)
 
prefix_rule(
  pattern=["bun", ["install", "add"]],
  decision="forbidden",
  justification="Use ./scripts/brin-install bun <package> so brin can approve the package first.",
)
 
prefix_rule(
  pattern=["pip", "install"],
  decision="forbidden",
  justification="Use ./scripts/brin-install pip <package> so brin can approve the package first.",
)
 
prefix_rule(
  pattern=["cargo", "add"],
  decision="forbidden",
  justification="Use ./scripts/brin-install cargo <package> so brin can approve the package first.",
)

2. Create scripts/brin-install:

Bash
#!/usr/bin/env bash
set -euo pipefail
 
manager="${1:?usage: brin-install <npm|pnpm|yarn|bun|pip|cargo> <package>}"
pkg="${2:?usage: brin-install <npm|pnpm|yarn|bun|pip|cargo> <package>}"
 
case "$manager" in
  npm)
    origin="npm"
    install_cmd=(npm install "$pkg")
    ;;
  pnpm)
    origin="npm"
    install_cmd=(pnpm add "$pkg")
    ;;
  yarn)
    origin="npm"
    install_cmd=(yarn add "$pkg")
    ;;
  bun)
    origin="npm"
    install_cmd=(bun add "$pkg")
    ;;
  pip)
    origin="pypi"
    install_cmd=(pip install "$pkg")
    ;;
  cargo)
    origin="crate"
    install_cmd=(cargo add "$pkg")
    ;;
  *)
    echo "unsupported package manager: $manager" >&2
    exit 1
    ;;
esac
 
url="https://api.brin.sh/${origin}/${pkg}"
verdict="$(curl -sf -o /dev/null -w "%header{x-brin-verdict}" "$url" || true)"
 
if [[ -z "$verdict" ]]; then
  if [[ "${BRIN_FAIL_CLOSED:-0}" == "1" ]]; then
    echo "brin unavailable, blocking install" >&2
    exit 1
  fi
 
  echo "brin unavailable, continuing install" >&2
  exec "${install_cmd[@]}"
fi
 
if [[ "$verdict" != "safe" ]]; then
  score="$(curl -sf -o /dev/null -w "%header{x-brin-score}" "$url" || true)"
  echo "brin blocked ${pkg}: verdict=${verdict} score=${score:-unknown}" >&2
  exit 1
fi
 
exec "${install_cmd[@]}"

3. Make it executable:

Bash
chmod +x scripts/brin-install

4. Use the wrapper instead of calling the package manager directly:

Bash
./scripts/brin-install npm react
./scripts/brin-install pip requests
./scripts/brin-install cargo tokio

##how it works

the Rules file is the hard gate: it stops direct install commands from reaching the shell. the wrapper is the approved path: it checks brin using response headers, only continues when the verdict is safe, and exits before the install runs otherwise.

by default the script fails open if brin is unreachable so your workflow keeps moving. set BRIN_FAIL_CLOSED=1 if you want installs blocked whenever brin can't be reached.

##optional soft guidance

if you still want Codex to explain the policy in natural language, add a short note to AGENTS.md or ~/.codex/AGENTS.md. treat that as documentation only — the real enforcement lives in Rules and wrappers.