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 this returns a path (e.g., /Users/yourusername/.opencode/bin/opencode), you’re good to proceed to Step 3.

If which opencode returns nothing, add OpenCode to your PATH by adding this line to your ~/.zshrc:

export PATH=~/.opencode/bin:$PATH

Then reload your shell:

source ~/.zshrc

Now verify the installation:

opencode --version

You should see the installed version number.

Step 3: Start OpenCode from the analytics repo

cd 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 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 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

• 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_snowflake_mcp.sh script with these commands:

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

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

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 — if you’ve already run make run-dbt for normal dbt development, you’re good to go.

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.

View page source - Edit this page - please contribute.