My first two open-source PRs, on Windows, in four days: what broke when I set up Switch and what I learned

Elle — Sat, 07 Nov 2026 17:19:14 +0000

Four days ago I had never opened a pull request. I knew what GitHub was, roughly, and that was it. This is the story of how I set up Switch — the open-source layer that puts AI coding agents like Claude Code, Codex and OpenCode into team chat — from a clean clone on Windows 11 and Debian 13 for the Flip the Switch hackathon, what broke along the way, and how that turned into two documentation PRs to Switch's core repository.

If you are a first-time contributor, or on Windows, or both: this is for you.

What I set out to do

Switch's hackathon had a "core contribution" track with issues labelled hackathon. Two of them were documentation:

#807 — write a user guide for the headless agent controller, the small Node program that runs agents on a machine of yours (a server, a VM) instead of your desktop.
#808 — a five-minute quickstart for new contributors: from clone to an agent answering in a room.

Docs issues sounded "easy". They were not easy; they were honest. You cannot write a guide that says "run this and you will see that" without running it and seeing it, so most of my four days went into running things.

Setting up Switch from a clean clone

The developer setup is small and well designed: a justfile with a handful of recipes.

git clone https://github.com/<you>/switch.git && cd switch
just init-env             # writes .env with freshly generated secrets, prints the admin login
uv sync --project core    # Python packages for switch-core (the project lives in core/)
just up                   # PostgreSQL + Mattermost in Docker
just run                  # switch-core on http://localhost:8000
just gateway-dev          # the dashboard on http://localhost:5173

On Debian this took about a minute of actual compute. uv sync --project core took one second, just run was ready in four. On Windows 11 the first just up took 2 min 8 s (it pulls two images and builds a small setup image) and just run booted in about 30 s. Then you open Switch Console, Add a Switch server → Connect to an existing server, type http://localhost:8000, sign in as admin@switch.local with the password just init-env printed, and Console even shows the local Mattermost as already linked, because a switch-setup container connected it for you.

That is the happy path. Here is everything that was not.

What broke on Windows (and how to get past it)

1. `just` from PowerShell does not work

Several just recipes are bash scripts (#!/usr/bin/env bash). From PowerShell:

error: could not find `cygpath` executable to translate recipe `init-env` shebang interpreter path: program not found

Fix: run everything from Git Bash, the shell that comes with Git for Windows. (And open a new window after winget install Casey.Just, so it is on your PATH.)

2. A fresh clone cannot start switch-core: CRLF

Git for Windows defaults to core.autocrlf=true, so every file is checked out with CRLF line endings. Switch's connector catalog loader reads SKILL.md files as raw bytes and matches the frontmatter against ---\n, which never matches ---\r\n. So, on an untouched clone:

switch_core.connections.loader.CatalogError: Connection airtable SKILL.md needs frontmatter with name: airtable and a description.

Another contributor had found this before me and opened a one-line .gitattributes fix (* text=auto eol=lf, PR #1016). Until it lands:

git config core.autocrlf false && git rm -q --cached -r . && git reset --hard

re-checks the clone out with LF endings, and just run starts.

3. The controller's npm package refuses Windows

The README says the agent controller "runs natively on Windows". The published package says otherwise:

npm error code EBADPLATFORM
npm error notsup Unsupported platform for switch-agent-controller@0.31.0: wanted {"os":"darwin,linux"} (current: {"os":"win32"})

npm install --global --force <tarball-url> installs a working binary (--version, doctor work). The fix is one word (win32) in the package's os list; I documented the workaround in the guide and offered the fix as a separate PR.

4. Switch Console 0.40.1 does not see npm-installed CLIs

This one I could not get past. Console's own check shows OpenCode as Installed (Found v1.19.3), but the embedded controller that would actually run the agent reports CLI not installed, so every provider in the New agent form is "Not supported here". Choosing the opencode.cmd shim explicitly, rechecking, restarting Console, even uninstalling and reinstalling OpenCode from Console's own Install button: same result. So on my Windows machine I got everything up to a signed-in Console connected to my dev server, and not the first room reply. I wrote that down in the quickstart rather than pretending otherwise.

5. Small things in CONTRIBUTING.md

uv sync at the repository root fails with No pyproject.toml found — the Python project lives in core/, so it is uv sync --project core. And the link to the README's "getting started" pointed at a heading that no longer exists. Both fixed in my PR.

What the Linux side taught me about the controller

For the controller guide I enrolled a real controller (release 0.31.0) against a local switch-core on Debian 13 with the agent_management flag on, and ran every command and every error path I could think of. Two findings worth sharing:

The controller's error messages are excellent. Enrolling a data directory twice tells you it "already belongs to controller … Use another --data-dir, or remove that directory"; a non-loopback http:// server tells you it "must use https (plain http is accepted only for a loopback server)"; a machine without systemd tells you to "Run switch-agent-controller run under your own supervisor, restarting it on exit code 1 only". Every exit code means one thing. That made the troubleshooting table almost write itself.
install.sh on main only installs signed releases, and the stable 0.31.0 release has no signature yet, so the one-liner currently fails with "the release has no signature". The guide shows the npm install fallback and explains why.

The two PRs

#1538 — docs/agent-controller-guide.md (530 lines): requirements, install, enrollment, service, doctor/status, provider sign-in, updates, Windows, exit codes, troubleshooting, uninstall.
#1540 — docs/contributing/quickstart.md (277 lines) plus the CONTRIBUTING fixes.

Both say exactly which OS each statement was tested on and what did not work.

What I learned, as a first-timer

Comment on the issue first, with a plan. The maintainers assigned issues to everyone who asked, and they answered every question within hours, including "where should this page live?" — which saved several people from writing in a generated directory.
Git is less scary than it looks when you only need six commands: clone, checkout -b, add, commit, push, and the PR button.
Test on the machine your reader has. Half of what is in my pages came from Windows doing something the README did not expect.
Say what did not work. A guide that admits "this step fails on Windows 11 with Console 0.40.1, here is why" is more useful than one that pretends.
Sign the CLA with the exact sentence the bot asks for. It takes ten seconds and covers all your future PRs.

If you have Docker, Git and an afternoon, Switch is a very good first open-source repository: the maintainers are responsive, the dev stack is clean, and the hackathon label still has issues with one or two PRs on them.

All commands above were run on Windows 11 (Git for Windows 2.56, Docker Desktop, Node 24, uv 0.11, just 1.59, Switch Console 0.40.1) and Debian 13, against Switch main on 29 October and 5 November 2026 and controller release 0.31.0.

DEV Community: Elle