Skip to main content

IDE Integration

X4 includes a VS Code/Cursor adapter under:

extensions/vscode-x4/

The extension is a thin adapter over the CLI. Its job is to make common X4 actions available from the editor without changing the underlying workflow.

Cursor Cloud Agents are not the primary X4 cloud execution layer today. X4 owns cloud workers, environment profiles, secrets, service access, validation evidence, and merge gates. Cursor remains supported as an editor and coding surface through this extension and the generated multi-root workspace.

See Cloud Agent Strategy for the current decision.

Install​

scripts/install-editor-extension.sh

Design Contract​

IDE actions should:

  • call x4 commands rather than duplicating logic;
  • surface command output clearly;
  • preserve repo-local and workspace-local state;
  • avoid printing secrets;
  • keep preview and evidence URL safety rules intact.

Typical Actions​

  • inspect workspace status;
  • run workspace validation;
  • bootstrap a workspace;
  • switch between generated feature workspaces;
  • start sandbox/preview flows;
  • open logs or generated artifacts;
  • help launch PR workflows.

The X4 Activity Bar view shows the currently open X4 workspace. The Bootstrap and Open row opens an X4 source picker. With no folder open, choose Choose Multiple Repos to select the whole repo set with checkboxes, then pick the entry repo. The Workspace row is clickable and opens X4: Switch Workspace, which scans x4.workspaceRoot for generated .x4/x4-workspace.code-workspace files. The repo rows below it are the repos in the selected workspace, not installed extensions. The switcher always includes create actions, even when existing workspaces are present. Choose one base repo when that repo already has an X4 registry, or choose multiple repos to generate a starter registry before bootstrapping the selected entry repo. The multi-repo path uses a checkbox picker of discovered Git repos under ~/dev/repos, not the native folder dialog.

When no workspace registry exists yet, sandbox selection offers generic starter profiles: azure-remote and env-file.

X4: Sandbox Run is the recommended agentic path. It asks what the sandbox should run, then calls x4 sandbox run "<goal>" so X4 can prepare a validated profile and start it through the deterministic sandbox runner.

X4: Sandbox Up remains the deterministic path. It loads sandbox profile choices from the selected workspace registry when available. The generic fallback is azure-remote, a metadata-only profile that does not start local app services. For env-backed profiles, the command offers the registry env bundle when configured and discovers workspace repo env files such as .env, .env.test, and .env.local so the developer can select one env file per repo or one global dotenv file.

See Agent Awareness Adoption for the extension behavior X4 should provide when a workspace repo is missing the stable AGENTS.md pointer.