VSCode / Cursor Setup

May 13, 2026 · View on GitHub

Tips and configuration for developing with VSCode or Cursor. The committed .vscode/ files (tasks.json, launch.json, extensions.json, settings.template.json) give you tasks, debugging, and recommended extensions out of the box — two local-only files need to be created before everything works.

Initial Setup

1. Create your local `settings.json`

.vscode/settings.json is gitignored (each developer has their own). Copy the template to get started:

copy .vscode\settings.template.json .vscode\settings.json

Then build the project (Ctrl+Shift+B) — the build populates python.analysis.extraPaths in settings.json with all _build/ extension paths, enabling Python autocomplete.

2. Create a workspace file (optional but recommended)

.code-workspace files are also gitignored. Create one to get the best multi-root experience:

File → Save Workspace As → .vscode\lightspeed-kit.code-workspace

3. Install recommended extensions

When prompted, install the recommended extensions (or run Extensions: Show Recommended Extensions). Key ones:

Extension	Purpose
`charliermarsh.ruff`	Linter + formatter (replaces pylint/flake8/autopep8)
`ms-python.python` + `anysphere.cursorpyright`	Python language server, autocomplete
`psioniq.psi-header`	Auto-inserts the SPDX license header on new Python files
`tamasfe.even-better-toml`	Syntax highlighting for `.toml` and `.kit` files
`eamodio.gitlens`	Git history and blame

Tasks

Run tasks via Ctrl+Shift+B (default build) or Ctrl+Shift+P → Tasks: Run Task:

Task	What it does
3. Build (default)	Incremental build — `build.bat`
4. Rebuild	Clean rebuild — `build.bat --rebuild`
5. Clean	Clean artefacts only — `build.bat --clean`
1. Format Code	Run `format_code.bat` (black + isort)
2. Lint Code	Run `lint_code.bat all` (ruff)
7. Launch (Release)	Start full app with VSCode debugger enabled
8. Launch (Development)	Start dev app with VSCode debugger enabled

The launch tasks automatically pass --enable omni.kit.debug.vscode so the debugger server is already running when the app starts.

Debugging

The .vscode/launch.json is pre-configured with a Python: Remote Attach config (port 3000).

Use Task 7 or 8 to launch the app — the debug server starts automatically.
Run the Python: Remote Attach launch config (F5 or the Run panel).
Set breakpoints and debug normally.

For everything else — how the debug server works, debugging tests, debugging startup logic, and the PyCharm alternative — see Debugging Guide.

Code Quality

Format on save is configured in settings.template.json (Ruff, modifications only) and copied into your local settings.json. No manual steps needed during development once set up. For a full format pass: Task 1. Format Code.

License header is auto-inserted on new Python files via the psioniq.psi-header extension. The template is configured in settings.template.json — just create a new .py file and save it.