Omni's model-local-editor: Sync Your Locally Developed Semantic Layer Code to Your Omni Instance

This is an English translation of the original Japanese article below:
https://dev.classmethod.jp/articles/try-model-local-editor/

This is Sagara.

In Omni, you can create Semantic Layer code through GUI operations on the instance itself. However, with the recent rise of AI coding agents like Claude Code, there are increasing cases where you'd want to develop Omni's Semantic Layer locally.

I actually faced this exact situation. I developed Omni's Semantic Layer code locally, issued a pull request, and merged it into the main branch — only to find that the latest code wasn't reflected on the Omni instance. (I also tried using the API, but it didn't work as expected.)

When I consulted with an Omni engineer about this, they told me about a package called "model-local-editor". By using this package, you can sync locally developed Omni Semantic Layer code to your Omni instance.

https://www.npmjs.com/package/@omni-co/model-local-editor

In this article, I'll walk through my experience trying out this package.

Prerequisites

• OS: Ubuntu 24.04 LTS (running on WSL2)
• Package manager: npm 11.11.0
• model-local-editor: 0.2.0

I'm assuming that the Model you develop in Omni is connected to Git, and you've cloned that repository locally for development. (For Omni setup details, please refer to this blog post.)

Also, I'm assuming this repository manages not only Omni code but also dbt code and other resources.

Preparation

Installing model-local-editor

First, install model-local-editor:

npm install -g @omni-co/model-local-editor

Setting Environment Variables

Set the following two environment variables. (If you want them to persist, consider adding them to ~/.bashrc or a .env file.)

export OMNI_API_KEY="your-api-key-here"
export OMNI_BASE_URL="https://my-org.omniapp.co"  # or your Omni instance URL

Trying It Out

Now that preparation is complete, let's sync to the Omni instance using model-local-editor.

Recommended: Create a Local Git Branch with the Same Name as the Omni Branch

Before using model-local-editor, I recommend creating a local branch with the same name as the branch you'll create on the Omni side.

The reason is that model-local-editor only creates a branch on the Omni instance side, so the sync process will push to the specified branch regardless of which local branch you're on.

For this walkthrough, I'll create and switch to a branch called 20260306-local-sync-test locally:

git switch -c 20260306-local-sync-test

Initial Setup and Branch Creation

Run the following command to specify the Omni Model, use the --dir option to point to the folder path managing the target Model, and create a new branch on Omni. (You can find the model-id from the URL bar when you open the target Model.)

For other options, please refer to the package documentation.

omni-sync init <model-id> --dir <folder-path-managing-the-target-Omni-Model> --branch <branch-name-to-create-on-Omni> --create-branch

Running this command displays the following:

Additionally, a .omni-sync.json file is created in the directory specified by the --dir option. This file tracks the change history of each file. (This file is used internally by model-local-editor, so users generally should not edit it directly.)

When you open the target Model in Omni and view the branch list, you can see that the 20260306-local-sync-test branch (specified with --branch 20260306-local-sync-test) has been created.

Syncing Local Edits to Omni

Next, let's sync locally edited content to Omni.

First, run the following command locally to start and keep the model-local-editor sync process running. Be careful to include the --dir option — without it, Omni's folders and files will be automatically moved to the root of your repository.

omni-sync start <model-id> --dir <folder-path-managing-the-target-Omni-Model> --branch <branch-name-specified-in-omni-sync-init>

You'll see output like the following. Once File watcher ready appears at the end, you're good to go. The key point is to keep this process running.

With the process running, edit and save any Omni file, and you'll see log output like this:

Now, when you switch to the branch on the Omni instance and check the target file, you'll see it has been synced! (Note: there were a few cases where syncing took some time, possibly due to browser caching.)

This means you can develop locally and immediately verify your changes on the Omni instance.

Bonus: I Recommend Creating Pull Requests from the Omni UI

By now, you should have a good picture of how to use model-local-editor to develop Omni code locally and verify it on the Omni instance.

However, when it comes to creating pull requests after you've finished development, I recommend issuing pull requests from the Omni instance UI. The reason is that even if you create a pull request and merge it from your local environment, the main branch code on the Omni instance won't be updated...

Below is the flow of creating a pull request from the Omni UI. You can see that the dimension updated_at_20260306 that was added earlier gets merged into the main branch and is reflected in the Shared model on the Omni instance (the shared model that syncs with the main branch code).

Bonus: If There Are Syntax Errors

If the file you want to sync to Omni has syntax errors, it will be displayed as shown below.

Conclusion

I tried out "model-local-editor," which lets you sync locally developed Omni code with your Omni instance.

While Omni's built-in IDE is excellent, as someone who has recently fallen in love with Claude Code, I found this capability to develop locally and immediately verify on the Omni instance incredibly convenient!

If you're using coding agents locally to develop Omni's Semantic Layer, I highly recommend giving this package a try.