AI Agent Setup

[TOC]

Context

The data team doesn’t have a standard approach for AI-assisted development — this guide fills that gap. It’s based on what’s already been working for several teammates, so everyone has a solid starting point rather than figuring it out from scratch.

This guide covers setup for:

• OpenCode — a terminal-based AI coding agent
• Snowflake/dbt MCP servers (optional, but highly recommended)
• MacWhisper — voice-driven prompting (optional)

OpenCode Setup

A more comprehensive guide is available in the internal handbook. The steps below are a simplified, data-team-specific version.

Step 1: Install OpenCode

curl -fsSL https://opencode.ai/install | bash

Step 2: Verify the installation

Check that OpenCode is available in your PATH:

which opencode

If which opencode returns nothing, add OpenCode to your PATH by running:

echo 'export PATH=~/.opencode/bin:$PATH' >> ~/.zshrc && source ~/.zshrc

Now verify the installation:

opencode --version

You should see the installed version number.

Step 3: Start OpenCode from the analytics repo

jump analytics
opencode

Step 4: Configure GitLab Duo as your AI provider

GitLab Duo uses OAuth — no token to create or manage.

1. Run /connect inside OpenCode and select GitLab Duo
2. OpenCode will open your browser to complete the OAuth flow
3. Sign in with your @gitlab.com account and authorise the app
4. You’ll be redirected back to OpenCode automatically

Step 4.5: Test the connection

Once connected, test it by saying hi to verify OpenCode responds.

Step 5: Apply the Golden Config

Apply the config from the OpenCode Golden Path.

Note: Use ~/.config/opencode/opencode.jsonc rather than opencode.json — the .jsonc extension allows comments, which is useful for annotating your config.

Step 6: Set plan as your default agent

Open ~/.config/opencode/config.json (this is a separate file from the opencode.jsonc Golden Config in Step 5) and add default_agent:

{
  "$schema": "https://opencode.ai/config.json",
  ...
  "default_agent": "plan"
}

This keeps you in the safer, more deliberate mode by default — you switch to Build explicitly when you’re ready to execute.

Step 7: Review the Agent Usage Guide

Before you start using OpenCode, review the Agent Usage Guide to understand:

• How agents and MCPs work
• Configuration best practices (global vs project-level)
• When to use Plan vs Build mode
• Prompting best practices and context management
• Available skills and agents

Video Resources

Requires using GitLab Unfiltered account:

• OpenCode Setup Tutorial (3m 30s)
• OpenCode Demo (5m 30s)

MCP Server Setup

Snowflake MCP Server (Optional but Highly Recommended)

Connecting OpenCode to Snowflake MCP allows an LLM agent to query Snowflake directly during an OpenCode session.

To set up, run the setup_mcp_analytics.sh script with these commands:

jump analytics
git checkout master && git pull && ./admin/setup_mcp_analytics.sh

The script will prompt you for your GitLab username and analytics repo path.

Important: The script will prompt for your computer login password and request keychain access. Enter your password and click “Always Allow” when prompted.

Verify the connection:

Start OpenCode (jump analytics && opencode), type hi, then look to the right side of the interface. You should see the Snowflake MCP name listed with a green dot indicating “connected”.

SNOWFLAKE_USER=<your GitLab email>
SNOWFLAKE_ACCOUNT=gitlab
SNOWFLAKE_ROLE=<the portion of your email before the @>

dbt MCP Server

If you ran setup_snowflake_mcp.sh above, this is already configured. The script adds the following environment variables to your ~/.zshrc:

# Analytics MCP Environment Variables
export ANALYTICS_DIR="~/repos/analytics/"
export DBT_PROJECT_DIR="$ANALYTICS_DIR/transform/snowflake-dbt"
export DBT_PATH="$DBT_PROJECT_DIR/.venv/bin/dbt"

The only other prerequisite is having the dbt virtualenv set up. To verify or set it up:

jump analytics
make run-dbt
ls .venv/bin/dbt  # Should show the dbt executable

If ls .venv/bin/dbt returns the file path, you’re good to go.

Verify the connection:

Start OpenCode (jump analytics && opencode), type hi, then look to the right side of the interface. You should see the dbt MCP name listed with a green dot indicating “connected”.

MacWhisper for Voice Prompting (Optional)

Typing out detailed prompts is slow. MacWhisper is a macOS voice-to-text app that makes it much faster to describe context and work through problems out loud — particularly for longer prompts where you’d otherwise spend more time typing than thinking.

It’s noticeably more accurate than built-in macOS Dictation app, and unlike cloud-based transcription it runs entirely on-device, so nothing leaves your machine.

Skills Setup

Skills provide reusable workflows and conventions that agents can automatically invoke. To use all available Data Team skills:

1. Complete the OpenCode setup steps above
2. Complete the MCP setup steps above (Snowflake/dbt)
3. Clone and symlink the data-team-agentic-skills repo by following the setup instructions

OpenCode Plugins

OpenCode Notify

OpenCode Notifier is a plugin that sends native macOS system notifications when OpenCode prompts you for something.

Install Steps

1. Add the opencode-notifier plugin to your ~/.config/opencode/opencode.jsonc. It should look something like this:

   {
     "$schema": "https://opencode.ai/config.json",
     "share": "disabled",
     "autoupdate": true,
     "plugin": ["@mohak34/opencode-notifier@latest"],
   

2. Optional (but recommended): by default, this plugin notifies on every event, which gets noisy fast. To customize which events trigger notifications, create a file ~/.config/opencode/opencode-notifier.json and paste in the following config:

{
  "sound": true,
  "notification": true,
  "bell": false,
  "timeout": 5,
  "showProjectName": true,
  "showFullPath": false,
  "showSessionTitle": false,
  "showIcon": true,
  "customIconPath": null,
  "suppressWhenFocused": true,
  "enableOnDesktop": false,
  "notificationSystem": "osascript",
  "suppressGhosttySound": false,
  "linux": {
    "grouping": false
  },
  "minDuration": 0,
  "command": {
    "enabled": false,
    "path": "/path/to/command",
    "args": [
      "--event",
      "{event}",
      "--message",
      "{message}"
    ],
    "minDuration": 0
  },
  "events": {
    "permission": {
      "sound": true,
      "notification": true,
      "command": true,
      "bell": false
    },
    "complete": {
      "sound": false,
      "notification": false,
      "command": true,
      "bell": false
    },
    "subagent_complete": {
      "sound": false,
      "notification": false,
      "command": true,
      "bell": false
    },
    "error": {
      "sound": false,
      "notification": true,
      "command": true,
      "bell": false
    },
    "question": {
      "sound": true,
      "notification": true,
      "command": true,
      "bell": false
    },
    "user_cancelled": {
      "sound": false,
      "notification": false,
      "command": true,
      "bell": false
    },
    "plan_exit": {
      "sound": false,
      "notification": false,
      "command": true,
      "bell": false
    },
    "session_started": {
      "sound": false,
      "notification": false,
      "command": true,
      "bell": false
    },
    "user_message": {
      "sound": false,
      "notification": false,
      "command": true,
      "bell": false
    },
    "client_connected": {
      "sound": false,
      "notification": false,
      "command": true,
      "bell": false
    }
  },
  "messages": {
    "permission": "Session needs permission: {sessionTitle}",
    "complete": "Session has finished: {sessionTitle}",
    "subagent_complete": "Subagent task completed: {sessionTitle}",
    "error": "Session encountered an error: {sessionTitle}",
    "question": "Session has a question: {sessionTitle}",
    "user_cancelled": "Session was cancelled by user: {sessionTitle}",
    "plan_exit": "Plan ready for review: {sessionTitle}",
    "session_started": "Session started: {sessionTitle}",
    "user_message": "User sent a message: {sessionTitle}",
    "client_connected": "OpenCode connected"
  },
  "sounds": {
    "permission": null,
    "complete": null,
    "subagent_complete": null,
    "error": null,
    "question": null,
    "user_cancelled": null,
    "plan_exit": null,
    "session_started": null,
    "user_message": null,
    "client_connected": null
  },
  "volumes": {
    "permission": 0.5,
    "complete": 1,
    "subagent_complete": 1,
    "error": 1,
    "question": 0.5,
    "user_cancelled": 1,
    "plan_exit": 1,
    "session_started": 1,
    "user_message": 1,
    "client_connected": 1
  }
}

1. Restart OpenCode to load the opencode-notifier plugin.
2. Validate: trigger a permission prompt (e.g. ask OpenCode to run rm ~/Downloads/some-file.csv). You should hear a sound and see a notification banner in the top right of your screen. No notification should fire on task completion.

View page source - Edit this page - please contribute.