Monte Carlo Prevent

Detect and prevent breaking schema changes in dbt projects using Monte Carlo lineage, monitoring, and data observability.

What it does

When you edit a dbt model, the plugin:

1. Blocks the edit until a change impact assessment is completed via Monte Carlo tools
2. Tracks edited tables throughout your session
3. Generates validation queries to verify changes behaved as intended
4. Generates monitors-as-code (validation, metric, comparison, or custom SQL monitors) for new or changed logic
5. Prompts for validation and monitor coverage before committing changes

For detailed workflow descriptions, activation rules, and synthesis guidelines, see the MC Prevent skill.

Prerequisites

• OpenCode installed
• Bun installed
• A Monte Carlo account with API access

Installation

Quick install (recommended)

From the repo root, run the install script targeting your dbt project:

./plugins/opencode/install.sh /path/to/your/dbt-project

This installs all three components and creates the MCP server config:

• Plugin → .opencode/plugins/mc-prevent/ (hooks that gate edits)
• Skill → .opencode/skills/prevent/ (workflow instructions for the LLM)
• Command → .opencode/commands/mc-validate.md (slash command)
• Config → opencode.json with Monte Carlo MCP server

Then authenticate:

opencode mcp auth monte-carlo-mcp

Manual install

If you prefer to install components individually:

1. Plugin (hooks that gate edits and track changes):

mkdir -p .opencode/plugins/mc-prevent
cp -r plugins/opencode/{src,package.json,tsconfig.json} .opencode/plugins/mc-prevent/
cd .opencode/plugins/mc-prevent && bun install

2. Skill (workflow instructions — required for impact assessments):

mkdir -p .opencode/skills
cp -r skills/prevent .opencode/skills/prevent

3. Command (slash command for validation queries):

mkdir -p .opencode/commands
cp plugins/opencode/commands/mc-validate.md .opencode/commands/

4. MCP server config (add to your opencode.json):

{
  "mcp": {
    "monte-carlo-mcp": {
      "type": "remote",
      "url": "https://mcp.getmontecarlo.com/mcp/toolkit"
    }
  }
}

5. Authenticate:

opencode mcp auth monte-carlo-mcp

Updating

Re-run the install script to update all components. It will overwrite existing files and re-install dependencies.

./plugins/opencode/install.sh /path/to/your/dbt-project

Usage

Automatic behavior (via hooks)

• Edit a dbt model — the plugin blocks the edit and asks you to run an impact assessment first
• Complete the assessment — emit MC_IMPACT_CHECK_COMPLETE: <table_name> markers and the edit is unblocked
• Commit dbt changes — the plugin prompts about validation queries and monitor coverage

Slash command

Use /mc-validate to generate validation queries for all dbt models changed in the current session.

How it works

The plugin registers three OpenCode hook events:

Hook	Event	Behavior
Pre-edit gate	tool.execute.before (edit/write/apply_patch/multiedit)	Blocks dbt model edits until impact assessment verified
Edit tracker	tool.execute.after (edit/write/apply_patch/multiedit)	Silently accumulates edited table names
Pre-commit gate	tool.execute.before (bash with git commit)	Prompts for validation on staged dbt files
Turn-end prompt	session.idle event	Reminds about validation queries and monitor coverage

State is managed via temp files under $TMPDIR/mc_prevent_* with a three-state machine:

• absent → injected (instruction sent, waiting for completion)
• injected → verified (completion marker found in session messages)

All hooks are wrapped in error handling — failures never block the engineer.

Differences from Claude Code plugin

Feature	Claude Code	OpenCode
Hook language	Python	TypeScript
Packaging	Marketplace plugin	.opencode/plugins/ directory
Pre-edit gate	PreToolUse hook with deny decision	tool.execute.before with thrown error
Transcript scanning	Reads transcript file	Uses SDK client to read session messages
Turn-end prompt	Stop hook with block decision	session.idle event with SDK message
Git staged files	subprocess.run(["git", ...])	Bun.spawn(["git", ...])

Troubleshooting

See skills/prevent/references/TROUBLESHOOTING.md for common issues.

Plugin not loading

1. Ensure bun install was run in the plugin directory
2. Check OpenCode logs: .opencode/logs/
3. Verify the plugin directory contains src/index.ts with a default export

MCP tools not appearing

1. Run opencode mcp auth monte-carlo-mcp to authenticate
2. Check that opencode.json has the mcp.monte-carlo-mcp configuration
3. Verify connectivity: the testConnection tool should succeed

Telemetry

The toolkit sends an anonymous install beacon — a Toolkit Installed event so we can count installations and version adoption. It includes an opaque per-install UUID, a per-session UUID, the toolkit version, and the editor it runs in (opencode). No prompts, arguments, skill names, or code are ever sent. It fires once per machine per toolkit version — the first time you start OpenCode after installing, and again after each version change (deduped by a local marker) — and is fail-open and non-blocking, never delaying or interrupting your session.

Authenticated MCP traffic (v1.13.3+). The same anonymous install_id and the toolkit version also ride as HTTP headers (x-mcd-toolkit-install-id, x-mcd-toolkit-version) on authenticated requests to the Monte Carlo MCP server (injected at config-load by the plugin's config hook). This lets the otherwise-anonymous install record be correlated with your account's MCP tool usage server-side — still no prompts, arguments, or code. The opt-out below disables these headers too.

To opt out, set MC_AGENT_TOOLKIT_TELEMETRY_DISABLED=1 in your shell environment before starting OpenCode. The toolkit will not phone home.

The data is stored in Mixpanel and Datadog and is used only for product-development decisions. The UUIDs are generated locally on first session and stored under ~/.config/opencode/mc-agent-toolkit/. Deleting that directory resets your install identity to a fresh anonymous one.

Architecture

See the plugins README for the overall plugin architecture and editor support comparison.

Changelog

See CHANGELOG.md for release history.