Data observability skills and enforcement hooks for AI coding agents, powered by Monte Carlo.
Run the install script from your target repo:
bash <(curl -fsSL https://raw.githubusercontent.com/monte-carlo-data/mc-agent-toolkit/main/plugins/codex/scripts/install.sh)Or specify a target repo path:
bash install.sh /path/to/your/repoThe script handles everything:
- Copies the plugin into
<repo>/plugins/mc-agent-toolkit/ - Registers skills in
<repo>/.agents/skills/(prevent, generate-validation-notebook, push-ingestion) - Writes hooks to
<repo>/.codex/hooks.json(project-level) - Creates
.agents/plugins/marketplace.jsonfor Codex plugin discovery - Adds the Monte Carlo MCP server to
~/.codex/config.tomlwith the requiredUser-Agentheader (workaround for codex#12859) - Enables
codex_hooksin your config - Opens a browser for OAuth login with your Monte Carlo account
After installation, restart Codex in your project. You should see "Installed mc-agent-toolkit plugin" on startup.
The plugin uses two hooks to enforce the Monte Carlo Prevent workflow:
| Hook | Event | Matcher | Purpose |
|---|---|---|---|
| pre_commit | PreToolUse | Bash | Prompt for validation before git commit |
| turn_end | Stop | — | Suggest validation queries for pending tables |
Note: Codex currently only emits PreToolUse/PostToolUse for the Bash tool. Pre-edit and post-edit hooks (Edit|Write) are included in the plugin for forward compatibility but are not registered until Codex expands tool coverage.
All skills are registered in .agents/skills/ during installation.
| Skill | Description | Details |
|---|---|---|
| Prevent | Gates dbt model edits with impact assessments, generates monitors-as-code, and produces targeted validation queries. | Skill README |
| Generate Validation Notebook | Generates SQL validation notebooks for dbt model changes from a PR or local repo. | Skill README |
| Push Ingestion | Generates warehouse-specific collection scripts for pushing metadata, lineage, and query logs to Monte Carlo. | Skill README |
| Automated Triage | Guides you through automated alert triage — scoring, deep troubleshooting, classification, and actions. Requires extended MCP toolset. | SKILL |
Codex activates skills automatically when you work with dbt models or SQL files. You can also invoke prevent explicitly with $monte-carlo-prevent.
Codex hook coverage is incomplete, which may cause hooks to not fire consistently:
- openai/codex#16732:
ApplyPatchHandlerdoesn't emit PreToolUse/PostToolUse hook events — hooks only fire for the Bash tool. When Codex uses its native edit path (• Edited), our pre-edit gate is bypassed entirely. We work around this by parsingapply_patchcommands within the Bash hook, but native edits remain ungated. - openai/codex#14754: Add PreToolUse and PostToolUse hook events for code quality enforcement — tracks the broader request for non-Bash hook parity.
- openai/codex#16246: PostToolUse is missing for tools that complete via exec session / polling path — prevents reliable post-edit tracking.
The skill-based impact assessment (via SKILL.md) works reliably regardless of these hook limitations.
This plugin uses the shared core library at hooks/prevent/lib/ (symlinked). All business logic lives in the shared library; the hooks in this plugin are thin adapters (~20 lines each) that translate Codex JSON to/from the platform-agnostic interface.