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:

  1. Write and test a survey script in VS Code. Use the QubeSurvey extension, its qube command line and your LLM agent of choice.
  2. Upload for team testing and tickets. Use the QubeSurvey app.
  3. Run fieldwork. Use an open survey link or personal invitations when enabled.
  4. 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

  1. 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….

  2. 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.qube before uploading. You can also create a script using the QubeScript quickstart.

  3. Open the Problems panel. Resolve the reported errors; inspect warnings before deciding that they are acceptable for your questionnaire.

  4. With the script active, run QubeSurvey: Run Interview from the Command Palette. The local interview opens beside the source.

  5. 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.

A QubeScript interview running beside source in VS Code

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.

QubeScript source and questionnaire navigation in VS Code

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.

  1. 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.
  2. Run QubeSurvey: Set Up AI Agent. It shows what it will write, asks you to confirm, then writes the output of qube agent-guide into AGENTS.md in 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.
  3. Start your agent in that folder. It checks the complete source with qube check, walks routes with qube interview and reads the language guide with qube 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 .qube or .odin editor active and check its language selection. Run QubeSurvey: Show Extension Status for installation status.
  • qube not found in a terminal: open a new integrated terminal after installing or updating the extension. QubeSurvey: Show Extension Status shows the bundled qube version 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.

CommandApplies to
QubeSurvey: New Hello World SurveyNew QubeScript
QubeSurvey: Run InterviewBoth
QubeSurvey: Refresh Questionnaire NavigatorBoth
QubeSurvey: Show Extension StatusBoth
QubeSurvey: Set Up AI AgentBoth
QubeSurvey: Connect to QubeSurvey (online)Both
QubeSurvey: Disconnect from QubeSurveyBoth
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 PositionsOdin
QubeSurvey: Unfix Odin Data PositionsOdin
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.

SettingDefaultMeaning
qube.lint.singleUseOptionListstrueReport named option lists used by only one question
qube.lint.duplicateInlineOptionListstrueSuggest a shared named list for identical static inline options
qube.lint.questionBlankLinetrueReport consecutive question declarations with no blank line between them
qube.lint.preferIfOverGototrueSuggest an @if guard instead of a @goto/@route that skips exactly one question

Connections and Odin

SettingDefaultMeaning
qube.qubeSurvey.baseUrlhttps://app.qubesurvey.comHosted service URL; explicit URL overrides are preserved
odin.diagnostics.enabletrueParse and report problems
odin.diagnostics.showWarningstrueInclude warnings and infos
odin.diagnostics.stricttrueCATI-safe strict mode: unfixed positions and undefined variables become errors
odin.diagnostics.unfixedPositionstrueGroup unfixed-position findings
odin.renumber.defaultStart10Default start for Renumber Questions
odin.renumber.defaultStep10Default 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.