Windsurfing the Codespaces

Vibing with AI-first IDE Windsurf in a GitHub codespace

Life is full of hardship, pain, and disappointment, but it needn't include suffering. The formula I found for a life of serenity and joy is:

1. Meditate twice daily-ish.

2. Soak in a hot bubble bath most evenings.

3. Read the news sparingly, and when I do, pretend to myself that it's just a parody of last year's news.

4. Don't run any software development projects on my local machine. Instead, I rely exclusively on GitHub Codespaces.

This last point is of particular importance. Setting up development environments for software projects on a local machine is a never-ending nightmare. By the time I set up virtual environments, Docker containers, dependencies, and compilation steps, I often lose momentum and energy. And what’s worse, after setting everything up, hacking, and then leaving the project, I come back to it a few weeks later just to find out that the entire development environment has deteriorated into a pile of digital debris and I have to start all over again.

GitHub Codespaces is a brilliant solution to this problem. Codespaces run in a containerised environment on GitHub's cloud so that I don't have to run anything on my machine. And the state and configuration of the environment are source controlled and live alongside the code in my repo. I can leave a project and come back to it months later to find a pristine working environment. I love it. I switched to working exclusively in codespaces a couple of years ago and never looked back.

Codespaces get first class support in Visual Studio Code, which I have been using as my main IDE for the last few years. You just pull a menu and choose to open a codespace, and the connection is established automatically, and you land editing the code in your workspace. Recently, however, I decided to give some of these newer AI-first IDEs a try, starting with Windsurf. And even though Windsurf and other AI IDEs like Cursor are themselves Visual Studio Code forks, I was disappointed to find out that they do not inherit the built-in support for Codespaces.

It took a bit of research (with help from Perplexity and Grok) to figure out the solution and turns out it's not that difficult at all. I now have Windsurf connecting to my Codespaces and working in them without difficulty.

Connecting with Windsurf

1. You need the gh command-line from GitHub, logged in to your GitHub account. The GitHub CLI can SSH into your codespaces, produce SSH configuration, and act as a proxy when connecting from Windsurf.

2. Identify the codespace you want to work in. You’re looking for the hostname provided by GitHub, not the fancy name you set. It would look something like funky-monkey-q3879fh347a.
   If you’re not sure, you can run gh cs list to get a listing of all your existing codespaces.

3. Use the GitHub CLI to generate SSH configuration for your codespace and add it to your .ssh/config. The command should look something like this:
   $ gh cs ssh --config -c funky-monkey-q3879fh347a >> ~/.ssh/config

4. You are now all set for connecting from Windsurf to your codespace. In Windsurf, run the command Remote-SSH: Connect to SSH Host. When prompted for a hostname, enter the hostname provided by GitHub (like funky-monkey-q3879fh347a). This will start the SSH connection, authenticate using whatever you have set up (I use an SSH-agent, which is convenient), and connect to codespace.

5. Now that you are connected, you’ll want to open the folder with your repository. You will find it at /workspaces/my-repo-name (and not in the home directory, which you’ll land at by default).

That’s it. You can now edit files, command Windsurf’s Cascade AI agent to make changes on your behalf, commit and push changes, etc…