VS Code on your computer

Experimental. This is new and still being proven. A project editor turns it on for each project, and it is off until they do.

You can work on a feature in your own VS Code instead of Repave IDE in the browser. The code is cloned to your computer, and the feature opens in a container that holds the same tools, the same repave command and the same test setup as a Repave IDE session, so scenarios run and results submit exactly as they do there.

Choose it when you would rather use your own editor, keyboard shortcuts and extensions, or work on your own machine's resources. Choose Repave IDE (in the browser) when you want to start straight away with nothing installed, or are on a computer you cannot install software on. Both work on the same feature branch, so you can switch between them.

What your computer needs

• VS Code 1.101 or newer.
• Docker — Docker Desktop, or Docker Engine on Linux or in WSL 2 — running, and able to run privileged containers. Give it at least as much memory as the project's Repave IDE sessions get; if it has less, Repave warns you before the feature opens.
• Git 2.30 or newer — the Git that comes with a Mac is fine — with your own access to the project's repository. Repave clones and pushes with your Git sign-in, not the project's.
• The Dev Containers extension from Microsoft. You do not need to install it: Repave installs it the first time if it is missing.

The project must have a git repository, and you need edit access to it.

Turning it on for a project

A project editor turns it on once for the project: in Project Settings → General, under VS Code on this computer, tick Allow opening features in VS Code on developers' computers, then Save Changes. Until then the feature page offers only Open in Repave IDE.

Turning it off stops it at once: features can no longer be opened in VS Code, and dev containers already open lose access to Repave. Code already copied to a computer stays there.

Setting up a computer

You do this once per computer.

1. On a feature's page, open the menu beside Open in Repave IDE and choose VS Code on this computer. The steps below appear on the page.
2. Click Download the Repave extension. It comes from your own Repave server.
3. In VS Code, open Extensions, then ⋯ → Install from VSIX…, and pick the file you downloaded.
4. Back on the page, click Open in VS Code.

Your browser asks whether to open VS Code, and VS Code asks whether to let Repave open the link. Choose Always allow and Do not ask me again to skip both questions next time. VS Code may also ask whether you trust the authors of the files in the folder: choose Trust Folder & Continue, or Manage to trust the whole project folder at once.

The first time, the feature takes several minutes to open: Repave downloads the project, its legacy code and the Repave runtime before the container starts. A notification says what it is doing throughout.

Opening a feature

After the first time, the button on a feature's page reads Open in VS Code, and one click opens the feature in a new VS Code window. Its status bar reads Dev Container: Repave: followed by the feature's name. Opening a feature whose window is already open takes a few seconds; starting its container takes a minute or two.

Repave remembers your choice in this browser. To open a feature in the browser instead, choose Repave IDE (in the browser) from the same menu.

VS Code on this computer is unavailable, with the reason shown in the menu, when:

The menu says	Why
Available once the To-Be Gherkin is approved.	The feature has no approved To-Be Gherkin yet.
You need edit access to this project.	You can view the project but not change it.
This project has no git repository to clone from.	The project was uploaded without one.
This feature has been merged. Reopen it to work on it again.	The feature is finished.

Where your files are

Each project is a folder under ~/repave (change it with the Repave: Projects Folder setting):

~/repave/crm-modernization-f6fe80/
  legacy/             the legacy code, read-only, as it is on Repave
  modernized/         the project's repository on its integration branch, for reading
  .worktrees/<id>/    one folder per feature you open, on that feature's branch

Beside them are the project's brief and architecture documents, read-only, as they are on Repave.

The short code after the project's name keeps two projects with the same name apart. Work happens in the feature's folder under .worktrees, which the feature's window opens. Other features are not downloaded until you open them.

Each feature's folder is a git worktree that git worktree list shows as locked: Repave links it to the clone by relative paths, so it works both on your computer and in the container, and the lock stops Git from cleaning it up. Leave the lock in place.

The legacy code is updated on every open. If someone uploads new legacy files while you are working, run Repave: Refresh legacy code from the Command Palette.

Working in the container

The feature's window runs inside a container, with a private Docker for the project's databases and services. Everything you know from Repave IDE is there:

• Scenarios lists the feature's scenarios; run one or all of them from there.
• BDD Runs lists each run, with its log and its traces.
• The repave command, Claude Code and the test browser are installed.
• Claude Code has the Repave commands and your project's own skills from the Skills page. A change made there while the window is open reaches it within a minute or two, as it does in Repave IDE.

The first time on a computer, the project's test database has to download before the first run. The Scenarios view says so — for example "Downloading the test database (SQL Server) — 0.4 of 1.6 GB…" — and offers Run once it is done.

Sign in to Claude Code inside the container once per project; your own Claude Code settings on the computer are not touched.

Submitting results

When the newest run has passed, BDD Runs offers Submit results. Repave accepts results only for code it can see, so commit and push first: until you do, the run reads "Push your commits to submit these results." After a push the button appears by itself.

Submitted results count exactly as results submitted from Repave IDE do.

Working with others

Others can work on the same feature at the same time — in Repave IDE, on their own computer, or as an implementation run. You meet in git: whoever pushes second pulls first. Repave never force-pushes your branch.

Another computer

On a second computer, install the extension the same way: click Open in VS Code, and when the page shows VS Code didn't pick up the link, follow its steps and use its Open in VS Code. A link from the main button cannot sign in a new computer; only the one from these steps can. If the extension is already installed, VS Code says "This computer isn't signed in to Repave, and this link can't sign it in." — the steps on the page are the way in.

A computer you have not used for 30 days signs in the same way again.

Updates

The extension keeps itself at your Repave server's version. After Repave is upgraded, the next time you open a feature VS Code shows "Updating the Repave extension to match Repave…", then asks you to reload the window. Click Reload, and the feature opens. The runtime and the container's tools update on the same open.

Troubleshooting

Every message below comes with Show log where it helps: the log is VS Code's Repave output, with every step and each git and docker command that failed.

VS Code says	What to do
Repave needs Git to download the project.	Install Git, then open the feature again.
Repave needs Git 2.30 or newer. This computer has Git …	Update Git, then restart VS Code so it finds the new one.
Repave needs Docker to run this project. Start Docker, or install it, then try again.	Start Docker and click Try again.
Couldn't install the Dev Containers extension: …	Install Dev Containers from the Extensions view, then try again.
Docker has … GB of memory. … runs with … GB on Repave, so builds or the database may fail.	Raise Docker's memory limit in its settings, or choose Open anyway.
This link has expired. Open the feature from Repave again.	A link works for five minutes. Click Open in VS Code again.
VS Code on this computer is turned off for this project. …	A project editor turned it off in Project Settings. Open the feature in Repave IDE, or ask them to turn it on again.
This computer isn't signed in to Repave, and this link can't sign it in.	Use Open in VS Code in the steps on the Repave page — see Another computer.
This link is from a different Repave server.	The extension opens links only from the Repave server it was downloaded from. Download it from this server.
This Repave extension was not downloaded from a Repave server, so it cannot open links.	Download the extension from your Repave server.
Can't reach Repave at …	Check your network or VPN, then try again.
Git couldn't sign in to … You need your own access to …	Ask whoever manages the repository for access.
… holds another project, so Repave left it alone.	Move or delete that folder, then open the feature again.
Couldn't download …: …	Check the log for git's or the server's reason, then try again.
Couldn't download the Repave runtime: …	Check Docker has disk space, then try again.
Couldn't update the Repave extension: …	Try again; if it keeps failing, install the extension from the setup steps by hand.
Repave access in this window has run out. Open the feature from Repave again to continue.	The window's access lasts a week from when you opened the feature. Open it from Repave again.

If the page says VS Code didn't pick up the link, VS Code did not receive it or the extension is missing: follow the steps the page shows.