Local LookML Development with the Looker Extension for VS Code

Every LookML developer has the same two browser tabs open: the Looker IDE and everything else. The browser-based IDE is good, but it is not your editor. It does not have your keybindings, your linters, your terminal, or the AI coding agent you use for every other repository you touch.

That changed with the Looker extension for VS Code, which reached general availability in September 2026. It lets you edit LookML on your own machine, in VS Code (or Cursor, Windsurf, Kiro, Antigravity, Code-OSS, VSCodium and other VS Code forks), while Looker still treats your work as a normal Development Mode session. Combined with the Looker-managed MCP server, it is also the supported path for AI-assisted or "vibe coded" LookML.

This tutorial walks through what the extension actually does, how to set it up, how the three-way sync between your laptop, your Looker instance and your Git remote really works, and where teams get burned.

What the extension does (and does not) do

The extension provides four things:

• Syntax highlighting and autocomplete for .lkml files locally.
• Bidirectional file sync with your Looker instance: read-on-open, write-on-save.
• Inline LookML validation, run automatically on every save against the Looker server.
• A local MCP proxy that lets an AI agent in your IDE talk to your Looker instance with authenticated tool calls.

What it does not do is replace Git, and it does not replace deployment. Saving a file locally pushes content to your Development Mode branch on the Looker server — it does not create a commit, and it does not deploy to production. Your branch, commit, push and deploy discipline stays exactly as it is today. If you have not formalised that yet, start with our guide to the Looker Git workflow and advanced deploy mode.

Prerequisites

Before anyone on your team installs anything, check the following:

• Looker 26.6 or later. Earlier instances are not supported. Some pieces arrived later still — Kiro OAuth support, for example, landed in 26.16, and the Antigravity IDE callback in 26.12.
• The develop permission on every model you intend to edit. The extension is not a permission bypass; it inherits exactly what your Looker user already has.
• A configured LookML project, either Git-connected or a bare repository.
• Git installed locally if you intend to clone the LookML repo rather than populate an empty workspace from the instance.
• An OAuth client ID from your Looker admin, if you use OAuth (you should).

Step 1: The admin registers the extension as an OAuth client

This is the step that stalls rollouts, because it is done once, centrally, and developers cannot do it themselves.

A Looker admin registers the extension as an OAuth client application using the API Explorer (install it from the Looker Marketplace if your instance does not have it, at LOOKER_INSTANCE_URL/extensions/marketplace_extension_api_explorer::api-explorer/). Three fields matter:

• client_guid — any globally unique ID. Write it down; every developer needs it.
• redirect_uri — the callback URL for the IDE your developers use. Looker validates these against an allowlist of supported schemes, so an unsupported IDE fails at registration time, not later. Common values:

IDE or tool	Callback URL
VS Code	vscode://google.vscode-looker-official/oauth_callback
Cursor	cursor://google.vscode-looker-official/oauth_callback
Windsurf	windsurf://google.vscode-looker-official/oauth_callback
Kiro	kiro://google.vscode-looker-official/oauth_callback
Antigravity	antigravity-ide://google.vscode-looker-official/oauth_callback
Code-OSS	code-oss://google.vscode-looker-official/oauth_callback

• enabled — must be true.

If your team uses more than one IDE, register the appropriate redirect URI for each.

On a Looker (Google Cloud core) instance that uses private services access, the Marketplace and API Explorer are unavailable, so the admin calls the endpoint directly:

curl -X POST "https://LOOKER_INSTANCE_URL/api/4.0/oauth_client_apps/CLIENT_GUID" \
  -H "Authorization: token ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_uri": "vscode://google.vscode-looker-official/oauth_callback",
    "display_name": "Looker VS Code Extension",
    "description": "OAuth client for local LookML development",
    "enabled": true
  }'

Verify with the Get OAuth Client App endpoint and confirm the redirect URI came back exactly as sent.

Step 2: Install and configure

Install Looker by Google Cloud from the Visual Studio Marketplace (standard VS Code) or the Open VSX Registry (Cursor, Antigravity, VSCodium). The Looker icon then appears in the Activity Bar.

With a workspace open, run Looker: Show Onboarding Walkthrough from the Command Palette (Cmd-Shift-P / Ctrl+Shift+P). The walkthrough is the recommended configuration path, and for API-key auth it is the only one — looker.clientSecret cannot be typed into settings.json by hand.

You will be asked for your instance URL, your project ID (the value in the Project column on the LookML Projects page), and your authentication details: OAuth client ID, or an API client ID and secret. For a bare repository, the walkthrough also offers to populate the workspace with the project's files.

Settings live in settings.json. Put them at workspace level, not global, so each project directory carries its own instance and project details:

{
  "looker.instanceURL": "https://mycompany.looker.com",
  "looker.oauthClientId": "your-client-guid",
  "looker.projectId": "ecommerce",
  "looker.askBeforeOverwritingRemote": true
}

That last setting is off by default, and we recommend turning it on for every team of more than one person. We will come back to why.

All looker.* properties — including looker.mcpServerUrl — must be defined in VS Code settings.json. Putting them in an AI agent's MCP config file will silently not work.

Step 3: Understand the three-way sync before you trust it

The extension keeps a three-way relationship between your local filesystem, your Looker Development Mode session and your Git remote. Internalise these rules:

• Read-on-open. Opening a .lkml file fetches the current server version of that file from your checked-out Development Mode branch. You are not editing a stale local copy.
• Write-on-save. Cmd-S immediately pushes the file to the Looker server, where it shows up in the browser IDE as an uncommitted change. This is not a Git commit.
• Branches follow you. git checkout locally is detected, and your server-side session switches to the matching branch. The extension verifies that local and remote branches match before syncing, pausing sync and prompting you if they diverge — this is the guard that prevents cross-branch overwrites.
• Uncommitted stays uncommitted. Committing locally does not clear the "uncommitted" state in the Looker IDE. Only after git push, when your instance pulls from the remote, does the change stop showing as uncommitted.

Conflicts

If a file is edited in the browser IDE while it is also open in VS Code, the default behaviour is that your local version overwrites the server version. With looker.askBeforeOverwritingRemote enabled, you instead get a prompt offering View Diff, Overwrite Remote, or Overwrite Local. On any shared branch, enable it. The five seconds it costs you is cheaper than silently reverting a colleague's afternoon.

Step 4: Validation on every save

The extension runs the Looker LookML Validator on each save and surfaces syntax and model errors inline in your files. You can also trigger it manually with Looker: Validate LookML without saving.

Treat this as the first gate, not the only one. It is the LookML Validator, not the SQL Validator, not your data tests, and not your content validation. The full CI picture — data tests, LAMS, Spectacles running on pull requests — is unchanged; see our walkthrough of CI for LookML.

Step 5: Wire up an AI agent (optional, but this is the point)

The extension runs a local reverse proxy at http://127.0.0.1:5050/mcp that forwards to your instance's Looker-managed MCP server at LOOKER_INSTANCE_URL/mcp. The proxy injects OAuth bearer tokens and — importantly — buffers agent tool requests until pending local file syncs complete, so validation tools never evaluate stale server-side code.

Point your agent's MCP configuration (.agents/mcp_config.json in VS Code, .mcp.json in Claude Code, .cursor/mcp.json in Cursor) at that local proxy rather than at Looker directly. If you run a self-hosted server, such as the MCP Toolbox for Databases, set looker.mcpServerUrl accordingly. For background on what an MCP server exposes, see Connecting an AI Agent to Looker with an MCP Server.

The extension also installs and updates prebuilt skill files that give the agent LookML-specific context and coding standards. Refresh them with Looker: Install Skills in this Workspace or Looker: Install Skills Globally.

With that in place, the agent can read local files, inspect database schemas through MCP, propose edits, and run validation to self-correct. Prompts that work well are specific and reference real files:

"Use the MCP tools to connect to the ecommerce_db connection. Inspect the schema for the users and orders tables. Generate users.view.lkml and orders.view.lkml with primary keys, dimensions for all columns, and a count measure. Then generate ecommerce.model.lkml exploring orders joined to users on user_id."

"Review products.view.lkml. For every type: number dimension representing a price or cost, add a corresponding sum and average measure with descriptions, matching the style in the workspace skills."

"The LookML validator returned Inaccessible view: users. Review the model file and users.view.lkml, find the cause, and propose a fix."

The discipline that makes this safe

Generated LookML is code that writes SQL that finance will read. The workflow we hold clients to:

1. Review the diff in the Source Control view before accepting anything. Never accept an agent edit you have not read.
2. Validate locally with Looker: Validate LookML before committing.
3. Commit and push with Git as usual — and remember that until you push, Looker still shows the change as uncommitted.
4. Let CI do the real work. Agents are excellent at boilerplate views and terrible at judgement calls about grain, fanout and symmetric aggregates.
5. Guard the destructive edits. Field renames and deletions break saved content whether a human or an agent made them; our post on renaming and retiring LookML fields still applies, doubly so when generation is cheap.

Used with those guardrails, local-first LookML development is the biggest quality-of-life change the platform has shipped in years: your editor, your agent, your Git tooling, with Looker's validator sitting inline in the file you are typing in.

Vistelio's senior Looker developers build and maintain LookML models for teams adopting this workflow. If you want help rolling out local-first development, standing up the OAuth registration and MCP configuration, or reviewing AI-generated LookML before it reaches production, get in touch.