QubeSurvey extension
Use the QubeSurvey extension in Visual Studio Code to write and test QubeScript
locally. Save new questionnaires as .qube. Odin support: run Odin surveys on
QubeSurvey, or audit and test scripts using QubeSurvey then run them on NIPO
Fieldwork System. Odin has its own parser and runtime. NIPO filenames are
conventionally extensionless and end in q, such as p1234q; use an editor copy
named p1234q.odin for automatic language recognition in VS Code. See
Using existing Odin scripts.
Use this four-step route from source to data:
- Write and test a survey script in VS Code. Use the QubeSurvey extension,
its
qubecommand line and your LLM agent of choice. - Upload for team testing and tickets. Use the QubeSurvey app.
- Run fieldwork. Use an open survey link or personal invitations when enabled.
- Export and download the data. Use an available Run export.
The four-step survey guide explains the sequence and current limits. This page covers installation, local tools and hosted uploads.
Local editing and interview testing are free and require no QubeSurvey sign-in. Install the QubeSurvey extension from the VS Code Marketplace, or download QubeSurvey extension 0.8.18 and install the VSIX in VS Code with Extensions: Install from VSIX….
Hosted uploads require Account permission and access to the Script. A
configured identity provider can allow new account registration; a signed-in
user can create a billing Account and Script without an invitation. Email
sign-in links are limited to existing accounts and the exact address on a
current project invitation. To upload to an existing Script, ask its owner to
check your Account membership and Script role. Account billing access does not
grant access to private Scripts.
The extension also bundles the qube command line, which it puts on the
integrated terminal’s PATH. See Use qube with an AI agent.
On this page
- Install and run a first interview
- Find and change the source
- Write with an AI agent
- Upload a reviewed version
- Existing Odin questionnaires
- If something is unavailable
- Commands
- Settings
- Privacy
Install and run a first interview
-
Use VS Code 1.102 or later. Install the QubeSurvey extension from the VS Code Marketplace (in VS Code, open Extensions, search for QubeSurvey, and choose Install). Alternatively, download QubeSurvey extension 0.8.18 and install the VSIX in VS Code with Extensions: Install from VSIX….
-
Open a folder for your questionnaire. Run QubeSurvey: New Hello World Survey to open a runnable example in a new unsaved editor. Save it as
hello-world.qubebefore uploading. You can also create a script using the QubeScript quickstart. -
Open the Problems panel. Resolve the reported errors; inspect warnings before deciding that they are acceptable for your questionnaire.
-
With the script active, run QubeSurvey: Run Interview from the Command Palette. The local interview opens beside the source.
-
Test with invented answers. Check a normal completion, every branch, required and skipped answers, exclusive choices and a correction using Back. Compare the result with what you expected before changing the script.

Keep the source file as your editable questionnaire. A browser upload creates an immutable version; it does not turn the browser into a source editor.
Find and change the source
Both languages provide syntax highlighting, an outline, folding, a questionnaire navigator and parser diagnostics. Completion, hover, Go to Definition, Find References and Rename help you work with declared questions and other entities. QubeScript also exposes its option domains, structs, repeats and routes.

Use Rename for an existing declared identifier rather than changing only one use of it. Review the resulting source changes and rerun the affected paths. A source check catches language errors. Running the interview lets you check the questions, routes and outcomes against your specification.
The language reference describes QubeScript syntax. The examples provide fictional studies to inspect and run.
Write with an AI agent
A script gives your agent the questions, answer choices and routing as context.
The extension bundles the qube command line, which supplies language guidance
and native checks while you and your agent edit that source.
- Open a terminal in VS Code (Terminal → New Terminal) and run
qube --help. A terminal that was open before the extension was installed or updated needs to be restarted. - Run QubeSurvey: Set Up AI Agent. It shows what it will write, asks you to
confirm, then writes the output of
qube agent-guideintoAGENTS.mdin the workspace root, between<!-- qube:agent-guide:start -->and<!-- qube:agent-guide:end -->. Other content in the file is not touched, and running the command again gives the same file. It needs a trusted workspace with a folder open. - Start your agent in that folder. It checks the complete source with
qube check, walks routes withqube interviewand reads the language guide withqube guide.
Prompt your agent in plain English to draft, expand or review questions and routing logic. Review the source changes, then run the interview with invented answers and check the expected routes and outcomes yourself. Upload a version only after reviewing it. See Use qube with an AI agent for the loop and every command.
qube checks source on this computer and does not provide an AI model. Your
agent and model are configured separately; their data settings and charges apply
to source you share. qube uses the node on your PATH when it is version 22 or
later, and otherwise VS Code’s own runtime. The extension changes only the
environment of VS Code’s integrated terminals and installs nothing globally.
Upload a reviewed version
The Get Started with QubeSurvey walkthrough (Command Palette: Welcome: Open Walkthrough) lists the same steps: create a Hello World survey, run the interview, connect and upload.
Run QubeSurvey: Upload Version. Authorize through the browser when prompted, then choose a Script where you have editing access. Creating a new Script requires an explicit eligible Account choice followed by a name. The selected Account owns the Script; see People, access and billing.
The command uploads the current editor source as a new immutable version and
opens it for hosted testing. It supports .qube and .odin. The configured
destination defaults to https://app.qubesurvey.com; change
qube.qubeSurvey.baseUrl only for an intended authorized environment.
Hosted authorization is stored in VS Code’s SecretStorage. Use QubeSurvey:
Disconnect from QubeSurvey to remove the local connection.
Testing a version does not create a live Run response. Continue with Fieldwork to prepare an activity and test its access and exports.
Connection destinations and disconnection
Online commands use browser device authorization and store the token in VS Code’s SecretStorage. Connections and remembered Script selections belong to the configured service URL, including its base path. Changing that URL requires a connection for the new destination; a token from an older release with no recorded destination is not reused. Run an online command to authorize again.
Disconnect from QubeSurvey removes the current destination’s local connection. It also requests server sign-out; the result message distinguishes local removal from accepted or unconfirmed remote sign-out. Local removal alone does not prove that the server revoked the session. An upload already sent to the server may still exist if you change the connection while it is running.
Existing Odin questionnaires
Odin has additional commands for fixing/unfixing data positions, renumbering questions, extracting translation text and appending language sections. Use QubeSurvey: Reproduce Ticket (online) for an authorized Odin ticket’s exact reported source and journey. QubeSurvey: Mark Ticket Fixed with Current Script (online) uploads a proposed Odin fix for human verification; it does not approve it.
QubeSurvey uses its own Odin parser and runtime. The
Odin reference explains supported commands and differences.
For example, the extension can navigate to a *MERGE file, but merged runtime
execution is not supported. Test imported scripts against their expected paths;
if you also deploy to NIPO, test there too.
If something is unavailable
Tested on macOS. Windows and remote extension hosts still need testing.
- No interview command: make the
.qubeor.odineditor active and check its language selection. Run QubeSurvey: Show Extension Status for installation status. qubenot found in a terminal: open a new integrated terminal after installing or updating the extension. QubeSurvey: Show Extension Status shows the bundledqubeversion and path.- No Account or upload permission: ask the Account owner to check your Account role and the Script owner to check project access. Local editing remains available.
- A runtime failure: retain the source and the smallest failing answer path. Use Testing and Tickets to report expected behavior.
Upgrade from an earlier extension
Upgrading from agentic-labs.vscode-qube or an earlier Odin extension?
Explicitly uninstall agentic-labs.vscode-qube or the earlier Odin extension
after installing the new extension. Released odin.* command aliases remain available.
A custom service URL is set with qube.qubeSurvey.baseUrl.
Commands
Commands use the QubeSurvey: prefix in the Command Palette. Commands marked (online) require a QubeSurvey connection.
| Command | Applies to |
|---|---|
| QubeSurvey: New Hello World Survey | New QubeScript |
| QubeSurvey: Run Interview | Both |
| QubeSurvey: Refresh Questionnaire Navigator | Both |
| QubeSurvey: Show Extension Status | Both |
| QubeSurvey: Set Up AI Agent | Both |
| QubeSurvey: Connect to QubeSurvey (online) | Both |
| QubeSurvey: Disconnect from QubeSurvey | Both |
| QubeSurvey: Upload Version (online) | Both |
| QubeSurvey: Connect or Refresh Tickets (online) | Both |
| QubeSurvey: Reproduce Ticket (online) | Both |
| QubeSurvey: Open Ticket in Browser (online) | Both |
| QubeSurvey: Mark Ticket Fixed with Current Script (online) | Odin |
| QubeSurvey: Fix Odin Data Positions | Odin |
| QubeSurvey: Unfix Odin Data Positions | Odin |
| QubeSurvey: Renumber Odin Questions… | Odin |
| QubeSurvey: Extract Odin Translation Section (Strip Commands) | Odin |
| QubeSurvey: Append Odin Language Section… | Odin |
Settings
QubeScript lint visibility
In VS Code Settings, search for Qube lint. Both preferences are on by default
and can be changed for your user or workspace. Open files refresh immediately.
These settings control extension warnings; qube check continues to report its native
lint findings. Syntax and validation errors remain visible.
| Setting | Default | Meaning |
|---|---|---|
qube.lint.singleUseOptionLists | true | Report named option lists used by only one question |
qube.lint.duplicateInlineOptionLists | true | Suggest a shared named list for identical static inline options |
qube.lint.questionBlankLine | true | Report consecutive question declarations with no blank line between them |
qube.lint.preferIfOverGoto | true | Suggest an @if guard instead of a @goto/@route that skips exactly one question |
Connections and Odin
| Setting | Default | Meaning |
|---|---|---|
qube.qubeSurvey.baseUrl | https://app.qubesurvey.com | Hosted service URL; explicit URL overrides are preserved |
odin.diagnostics.enable | true | Parse and report problems |
odin.diagnostics.showWarnings | true | Include warnings and infos |
odin.diagnostics.strict | true | CATI-safe strict mode: unfixed positions and undefined variables become errors |
odin.diagnostics.unfixedPositions | true | Group unfixed-position findings |
odin.renumber.defaultStart | 10 | Default start for Renumber Questions |
odin.renumber.defaultStep | 10 | Default increment for Renumber Questions |
ODIN language settings remain under odin.*.
Privacy
Editing, diagnostics, transforms, local interview execution, replay and case history inspection run locally. The extension sends no telemetry.
Online commands connect to the configured hosted service. Upload Version and Mark Ticket Fixed upload the current editor source; Tickets
reads authorized project, ticket, reported-source and reproduction data. Local
interview answers and case history are not otherwise uploaded by the extension.
The bundled qube command line checks source locally and needs no hosted
connection. An AI assistant that runs it can send that source to its configured
model and has its own file access, connection and data handling settings.
Set Up AI Agent writes only the AGENTS.md section you confirm in your
workspace.
Learn more at qubesurvey.com.