The editor

VS Code and GitHub with Mokxi

Keep your projects in your own GitHub repository, edit the code in VS Code, and run it in Mokxi.

There are three ways to work with a project outside the browser, and they all use the same files, so you can mix them: save to GitHub from the editor, clone the repository and open it in VS Code, sync from VS Code or the terminal, and open it in Mokxi again.

What a saved project looks like

Every save to GitHub, every mokxi pull and every project VS Code opens has the same layout:

File What it is
Blink/Blink.ino the sketch, as an Arduino IDE folder, with its other tabs beside it
diagram.mokxi.json the whole project: parts, wires, notes and code. Mokxi opens it as it is
README.md what the project is, with an Open in Mokxi badge
.vscode/extensions.json recommends the Mokxi extension when the folder opens in VS Code
.vscode/settings.json which Mokxi project the folder is
.vscode/tasks.json push, pull, run, compile and upload as VS Code tasks
.gitignore leaves out the command line's sync state and build output

The folder takes the project's name, so the Arduino IDE opens it as it is (File > Open > Blink/Blink.ino). A project with two boards gets a folder for each, such as Traffic_Lights_uno1/ and Traffic_Lights_esp1/.

Edit the sketch in the folder, not inside diagram.mokxi.json: when Mokxi reads the repository back, the folder wins. A tab you delete from the folder is deleted from the project, and a new file in it becomes a new tab.

The README, .gitignore and the .vscode files are yours once they exist: Mokxi writes them the first time and leaves your edits alone after that.

Save to GitHub from the editor

  1. Open Export in the editor's header.
  2. Under GitHub, press Connect GitHub. GitHub asks you to let Mokxi write to your public repositories. Tick Include private repositories first if you want private ones too.
  3. Back in the editor, open Export again and press Save to GitHub.
  4. Pick New repository (Mokxi names it after the project) or one of yours, write a commit message if you like, and press Save to GitHub.

You get a link to the commit on GitHub. Every later save is a new commit on the same branch. The line at the top of the card says where you are:

  • Synced with ada/blink (main): GitHub has exactly this project.
  • Changes not saved to ada/blink yet: you changed the project since.
  • ada/blink has newer commits: somebody pushed to the repository. Use Open from GitHub to get them.

Open from GitHub

Open Export and press Open from GitHub, then pick one of your repositories or paste any repository you can read (owner/name or a github.com link).

  • A repository saved from Mokxi opens as it was saved, with any edits made to the sketch folder on GitHub or in VS Code.
  • A plain Arduino sketch repository (a folder with an .ino file) opens too. Mokxi puts it on an Uno, or an ESP32 when the sketch includes WiFi. Change the board if it is meant for another one.

What was open before goes on the shelf first, as with Open JSON, so nothing is lost. The Open in Mokxi badge in a saved repository's README opens the project right away.

Connecting, and disconnecting

Mokxi asks GitHub for repository access only when you press Connect GitHub, never when you sign in. It is a separate permission from signing in with GitHub, and it works the same if you sign in with Google, Microsoft or email.

The access is stored encrypted with your account and used only when you press Save or Open. Nothing else in Mokxi reads it, and it is never sent to your browser.

To disconnect, go to Settings > Connected accounts and press Disconnect. Mokxi revokes its access at GitHub and deletes it. Closing your account does the same. You can also revoke it on GitHub, under Settings > Applications > Authorized OAuth Apps.

GitHub sync is not offered to students in a class or to children's accounts.

VS Code

Install Mokxi from the VS Code Marketplace (search for Mokxi in the Extensions view), or from Open VSX in VSCodium and Cursor. A folder saved from Mokxi already recommends it.

Run the circuit in VS Code

Open a project folder: a Mokxi project, a Wokwi project (wokwi.toml and diagram.json) or a sketch. Press Start Simulator (the play button on a sketch or the diagram). The circuit runs in a panel beside your code, on the same engine as the Mokxi editor, and the Mokxi Serial Monitor terminal shows what the boards print; type a line there and press Enter to send it. Saving the sketch or the diagram, or a new build from your build tool, runs it again. Stop and Restart are on the panel's title bar and in the status bar.

A project with a build (the firmware wokwi.toml names, a PlatformIO build, or an arduino-cli build) runs that build; otherwise the panel compiles the sketch the way the editor does. None of this needs an account.

Tests, lint and CI

  • Scenario files (mokxi.test.yaml, *.test.yaml, Wokwi's *.scenario.yaml) show up in VS Code's Testing view. Each scenario is a test with its steps under it; a failure points at the step's line, with the last serial lines.
  • Mokxi: Check the Circuit (Lint) puts wiring problems in the Problems panel. It runs when you save the diagram too.
  • Mokxi: Screenshot a Display saves a display as a PNG at the moment you pick.
  • Mokxi: Set Up CI (GitHub Actions or GitLab) writes the workflow, the GitLab CI file, or both, and a first mokxi.test.yaml if the project has none. See simulation tests in CI.

Your Mokxi projects

  1. Click the Mokxi icon in the Activity Bar and press Sign In. Approve the short code in your browser, or paste a token from Settings > Developer.
  2. Your projects are listed in the sidebar. Click one to open it as a folder.
  3. Edit the sketch. .ino files get Arduino highlighting, and snippets such as sketch, blink, button and every.
  4. Press Sync (the cloud on the editor's title bar) to send it to Mokxi.
  5. Open in Mokxi (the Mokxi item in the status bar) opens it in the editor in your browser.

Sync refuses to overwrite work done in the browser since your last sync, and Pull refuses to throw away edits you have not synced. Each tells you why and lets you choose. Opening, syncing, pulling and uploading are part of Pro.

Compile and upload

Mokxi: Compile (arduino-cli) uses arduino-cli if you have it, with errors in the Problems panel, and Mokxi: Compile and Upload to Mokxi syncs, compiles and stores the build with the project, so mokxi.com runs exactly what you built. You do not need arduino-cli for the simulator panel, which compiles a sketch itself.

The command line

The same things work from a terminal with npx @mokxi/cli. See The mokxi command line.

npx @mokxi/cli login
npx @mokxi/cli pull https://mokxi.com/p/abc123 blink
cd blink && git init
npx @mokxi/cli push
npx @mokxi/cli run --timeout 5s

Which plans

GitHub sync and the command line are on every plan. mokxi run and mokxi test compile and simulate on your own machine, so they are free and need no sign-in. In VS Code, the simulator panel, tests, lint, screenshots, Set Up CI and Compile are free and need no account too. Your Mokxi projects in VS Code (opening, Sync, Pull and Compile and Upload to Mokxi) are part of Pro (and the student price and Classroom); without it, the extension says so and offers the 7-day Pro trial where you can still start it. CI runs (the GitHub Action, or the command line tool in a CI job) are free for public repositories; for private ones, CI comes with Pro (and the student price, Classroom, the trial, Lifetime, and Ultra for accounts that still have it); see simulation tests in CI. If you used either in the 60 days before October 12, 2026, you keep it until December 11, 2026, and the tool tells you so. mokxi run --cloud and mokxi simulate run on Mokxi's servers and use the API minutes your plan includes; the developers page lists them.